A lo largo de esta sección definiremos cómo funciona la API de pago de MYMOID. Esta documentación está orientada al departamento de desarrollo de los comercios que quieran realizar una integración, ya que es de carácter técnico. Esta guía asume que ha registrado previamente su negocio y que cuenta con las credenciales necesarias para poder interactuar con la API de pagos. Los contenidos que vamos a abordar son los siguientes:


1. Introducción

2. Llamadas a la API

3. Entornos MYMOID

4. PaymentOrder

5. Estados de un PaymentOrder

6. Crear un PaymentOrder

7. Cancelar un PaymentOrder

8. Comprobar el estado de un PaymentOrder

9. Pagar un PaymentOrder

10. Realizar una devolución sobre un PaymentOrder


1. Introducción


La API de MYMOID consiste en una API REST con una serie de servicios segurizados por unas credenciales únicas asignadas a cada comercio. Toda la API se basa en el concepto de orden de pago, al que denominaremos PaymentOrder a partir de ahora. Dicho PaymentOrder refleja un pago y la interacción entre un comercio y un cliente. Por lo tanto, este documento hará referencias constantes a este término, que definiremos con más detalle en el apartado correspondiente.


2. Llamadas a la API

Todas las llamadas a la API que no son públicas, deben llevar una cabecera HTTP específica en todas las peticiones para poder identificar y validar a la aplicación del negocio que realiza las mismas. La cabecera que se debe utilizar es 'Authorization' encargada, por definición, de autenticar las peticiones recibidas. El contenido que debe llevar la cabecera se compone de la siguiente manera:


'Basic ' + Base64( 'ID de aplicación' + ':' + 'Clave secreta de aplicación')

En primer lugar, se debe concatenar el ID de aplicación, seguido del símbolo ':' y de la clave secreta de aplicación. Esto lo convertimos a Base64 y el resultado lo concatenamos a continuación del texto 'Basic ' (entre la palabra Basic y el Base64 calculado hay un espacio en blanco). Vamos a ver como formarlo con los siguientes datos de ejemplo:

  • ID de aplicación: 5f93015589fcea018f0c2d97bd0a3508186a8b7d360591b0547d0743de2fe284
  • Clave secreta de aplicación: 97158fbb7852bfa0661033650a721ff7b97a3c1a0d41aafaa680b6f68c786196

Cabecera de autorización:

Basic NWY5MzAxNTU4OWZjZWEwMThmMGMyZDk3YmQwYTM1MDgxODZhOGI3ZDM2MDU5MWIwNTQ3ZDA3NDNkZTJmZTI4NDo5NzE1OGZiYjc4NTJiZmEwNjYxMDMzNjUwYTcyMWZmN2I5N2EzYzFhMGQ0MWFhZmFhNjgwYjZmNjhjNzg2MTk2

La cabecera que habría que incluir en la petición a la API sería la siguiente:

Authorization Basic NWY5MzAxNTU4OWZjZWEwMThmMGMyZDk3YmQwYTM1MDgxODZhOGI3ZDM2MDU5MWIwNTQ3ZDA3NDNkZTJmZTI4NDo5NzE1OGZiYjc4NTJiZmEwNjYxMDMzNjUwYTcyMWZmN2I5N2EzYzFhMGQ0MWFhZmFhNjgwYjZmNjhjNzg2MTk2

3. Entornos MYMOID

La API de MYMOID dispone de dos entornos. El primero estará destinado a pruebas de integración de nuevos comercios y lo denominaremos sandbox. En él no habrá movimiento de dinero real y todas las pruebas se realizarán con una tarjeta de pruebas. En dicho entorno no podremos introducir una tarjeta de pago real ya que no funcionará. Los datos de configuración de dicho entorno son:
La tarjeta de pruebas disponible para operar en él son los siguientes:
  • Nombre del titular: cualquiera
  • Número de tarjeta: 4548812049400004
  • Validez: 12/20
  • CVV: 123
El segundo entorno será el real denominado producción. En él todas las operaciones tendrán validez y sólo aceptará tarjetas reales. Los datos de configuración del entorno son:
Todas las peticiones funcionan igual en ambos entornos, lo único que cambia es la url y las credenciales de un comercio. Una vez se haya integrado un comercio en sandbox, si todas sus peticiones funcionan correctamente sólo tendría que sustituir la url de un entorno por otro así como sus credenciales.


4. PaymentOrder

Como ya hemos mencionado en el apartado anterior, toda la API de pago de MYMOID se apoyará en el concepto PaymentOrder. Un PaymentOrder tendrá los siguientes atributos:

  • currency: moneda asociada a la orden de pago, siguiendo el estándar ISO-4217
  • reference: referencia de la orden de pago.
  • concept: concepto de la orden de pago.
  • amount: importe de la orden de pago. Es una cantidad entera (no admite decimales) y representa el valor en céntimos. Para una orden de pago de 1 euro el valor sería 100.
  • payType: tipo de la orden de pago. El valor que debemos introducir es PAY.
  • status: estado de la orden de pago (detallados en el siguiente apartado).
  • paymentOrderId: identificador de la orden de pago.
  • shortCode: identificador corto de la orden de pago.

5. Estados de un PaymentOrder

Los estados por los que puede pasar un PaymentOrder son los siguientes:

  • AVAILABLE: Disponible. Estado inicial en el que se encuentra una orden de pago tras ser generada.
  • EXPIRED: Expirada. Una orden de pago expira si superado el periodo de expiración (24 horas por defecto) no se ha realizado un pago sobre ella.
  • CANCELLED: Cancelada. Se puede cancelar una orden de pago cuyo estado sea AVAILABLE.
  • PAID: Pagada. Sólo se puede llegar a este estado desde AVAILABLE.
  • PARTIALLY_REFUNDED: Parcialmente devuelta. Una orden de pago se encontrará en dicho estado si tras ser pagada, hacemos una devolución de un importe menor al total de esta.
  • REFUNDED: Devuelta. El importe asociado a la orden de pago que fue cobrado en su día se ha devuelto completamente. Para poder proceder a su devolución, la orden de pago tiene que estar en estado PAID ó PARTIALLY_REFUNDED.

6. Crear un PaymentOrder

Tras definir lo qué es un PaymentOrder y los distintos estados en los que se puede encontrar, vamos a ver como podemos generarlo a través de la API. La petición que debemos hacer es la siguiente:

POST {urlServidorMymoid}/views/button/order

Si queremos generar una orden de pago normal, el cuerpo de la petición sería el siguiente:

{
  "currency": "EUR",
  "reference": "Payment Order Reference",
  "amount": 20500,
  "payType": "PAY",
  "concept": "Payment Order Concept"
}
La respuesta devuelta por la API tendrá el siguiente formato:
{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 20500,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "Payment Order Reference",
    "concept": "Payment Order Concept",
    "status": "AVAILABLE",
    "currentStatus": {},
    "creationDate": 1454490217151
  }
}


A partir de momento, todas las operaciones que queramos realizar sobre la orden de pago que hemos generado las tendremos que hacer indicando el paymentOrderId recibido en el momento de crear una orden de pago. Ese id único de 64 caracteres nos servirá para indicar en cada momento con que orden de pago estamos operando. También es importante recordar el valor devuelto en el campo shortCode. Este identificador único también representa una orden de pago y lo necesitaremos a la hora de cargar el fomulario de pago del que hablaremos más adelante.


7. Cancelar un PaymentOrder

Tras crear una orden de pago, tenemos la posibilidad de cancelarla siempre y cuando esté en estado AVAILABLE y no haya pasado su plazo de expiración. Una vez cancelada la orden de pago no podremos realizar ninguna otra acción sobre ella, y por tanto no podremos proceder a su pago. Para cancelar una orden de pago, la petición a realizar es la siguiente:

PUT {urlServidorMymoid}/pay/order/cancel/{paymentOrderId}
Y la respuesta recibida de la API:
{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "04a2cda611b5e2f7b18a6ad5b713b602e84502df690ac3dd2bdae14b46d6fdd8",
    "shortCode": "YY2HHG",
    "currencyCode": "EUR",
    "amount": 20500,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "Payment Order Reference",
    "concept": "Payment Order Concept",
    "status": "CANCELLED",
    "currentStatus": {},
    "creationDate": 1454514264000
  }
}

8. Comprobar el estado de un PaymentOrder

Una vez creada una orden de pago, podremos consultar en qué estado se encuentra en cualquier momento. Esa petición nos dará la información actualizada asociada con la orden de pago recibida como parámetro. La llamada a la API que tenemos que llevar a cabo para ello será la siguiente:

GET {urlServidorMymoid}/pay/order/{paymentOrderId}

Siendo paymentOrderId el identificador de la orden de pago que queremos consultar. La respuesta de la API a dicha petición será la siguiente:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "c9b2dd940ed9614d5424e12a59c2d31167975fffc85c3dbca9ccd3386bd29bfd",
    "shortCode": "RGLL3P",
    "currencyCode": "EUR",
    "amount": 100,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "New Payment Order Reference",
    "concept": "New Payment Order Concept",
    "status": "PAID",
    "currentStatus": {},
    "expirationCard": "01/20",
    "pan": "xxxxxxxxxxxx0003",
    "creationDate": 1454504239000
  }
}

Si la orden de pago se encuentra en estado PAID, observamos dos campos que nos serán de utilidad, PAN y expirationCard. El PAN refleja los cuatro últimos dígitos de la tarjeta utilizada para realizar el pago, mientras que expirationCard muestra su fecha de expiración.

 

9. Pagar un PaymentOrder

Para realizar el pago de una orden de pago tendremos que introducir los datos de la tarjeta que vayamos a utilizar en el formulario de pago. Dicho formulario está disponible en la siguiente dirección:

{urlServidorMymoid}/tpv/?p={shortCode},

siendo shortCode el identificador devuelto a la hora de generar la orden de pago. En el caso de la orden de pago que generamos anteriormente, la url sería:

{urlServidorMymoid}/tpv/?p=JZ3PLK

El formulario de pago tendrá la siguiente apariencia:


Una vez que el cliente introduce los datos de su tarjeta se realizará la redirección a la pantalla de resultado correspondiente.  


Ejemplo de pago correcto:

Ejemplo de pago incorrecto:

Existe la posibilidad de redirigir al usuario a unas URLs específicas a través de un botón continuar, una vez se ha finalizado la operación de pago y dependiendo del resultado de la misma. Para ello tendremos que configurar unos parámetros en la url del formulario, como se muestra en los siguientes ejemplos.

Ejemplo del formato de la url con parámetros de redirección final: 

{urlServidorMymoid}/tpv/?p={shortCode}&urlok={URL_OK}&urlko={URL_KO}
Ejemplo de pago correcto:

Ejemplo de pago incorrecto:

10. Realizar una devolución sobre un PaymentOrder

Cuando tenemos una orden de pago en estado PAID podemos realizar una devolución. Existen dos tipos de devolución, la devolución parcial y la devolución total. La diferencia entre ambas es que con la primera tenemos la posibilidad de devolver una cantidad menor a la asociada a la orden de pago y realizar múltiples devoluciones, siempre y cuando el importe devuelto en conjunto sea menor o igual al importe total de la orden de pago. El segundo tipo devuelve todo el importe pagado con una sola petición.

En la devolución parcial indicamos la cantidad a devolver. Si la cantidad a devolver es igual al importe total de la orden de pago, la devolución parcial sería equivalente a la devolución total. La ventaja de la segunda opción respecto a la primera es que no necesitamos conocer el importe pagado inicialmente, ya que devolvemos el total del importe de una sola vez. A continuación vamos a ver ambas peticiones.

a) Devolución parcial

Url de la petición:

PUT {urlServidorMymoid}/pay/order/refund/{paymentOrderId}/amount/{amount}

Siendo el parámetro amount el importe a devolver de la orden de pago.

Respuesta:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "a7350bdc601805fdffcca67ff073675598097ae51c5074832461f4c9e9a19b69",
    "shortCode": "1L1GMP",
    "currencyCode": "EUR",
    "amount": 20500,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "referencia del PaymentOrder",
    "concept": "concepto del PaymentOrder",
    "status": "PARTIALLY_REFUNDED",
    "currentStatus": {},
    "creationDate": 1454518718000
  }
}

b) Devolución total


Url de la petición:

PUT {urlServidorMymoid}/pay/order/refund/{paymentOrderId}

Respuesta:

{
  "status": true,
  "code": 0,
  "data": {
    "paymentOrderId": "2e0d250097047b7abf1528fd271dd08cb8bc7b3fb7f51e37b3c8fc5c1eb19ec8",
    "shortCode": "JZ3PLK",
    "currencyCode": "EUR",
    "amount": 20500,
    "merchantId": "282682dd6b19c81ee7d6b3322505ebe20e03467c0a6dac129c2206e5202ba375",
    "reference": "Payment Order Reference",
    "concept": "Payment Order Concept",
    "status": "REFUNDED",
    "currentStatus": {},
    "creationDate": 1454490217000
  }
}