En este apartado describiremos el proceso que nos permitirá almacenar los medios de pago de un usuario. A lo largo del documento denominaremos a los usuarios mediante la palabra reference. Damos por supuesto que la persona que está leyendo esta documentación ha consultado la documentación de Pago previamente. Los apartados en los que vamos a dividir el contenido son los siguientes:


  1. Introducción
  2. Crear un reference
  3. Obtener detalle de un reference
  4. Eliminar un reference
  5. Añadir un medio de pago de tipo tarjeta para un reference
  6. Obtener los medios de pago de un reference
  7. Obtener el detalle de un medio de pago
  8. Modificación del alias de un medio de pago
  9. Eliminar un medio de pago asociado a un reference
  10. Verificación de un medio de pago de tipo tarjeta
  11. Realizar un pago usando un medio de pago de un reference


1.- Introducción

Algunos comercios necesitan poder almacenar los medios de pago de sus usuarios para reutilizarlos posteriormente. Los usuarios de los comercios serán denominados references de ahora en adelante.

2.- Crear un reference


Éste método nos permitirá crear un reference asociado a un comercio existente. Los comercios realcionarán sus usuarios con un identificador que ellos indiquen. Este identificador debe ser único. Por motivos de seguridad, el comercio no se recibirá como parámetro y se obtendrá de las credenciales que realizan la petición.


La petición que habría que realizar es la siguiente:

 

POST                {urlServidorMymoid}/pay/reference

 

El cuerpo de la petición será el siguiente:

  

{
  "value" : "reference_value"
}

 

Siendo el contenido del parámetro value el identificador del usuario. Este identificador ha de ser único y puede ser elegido por el comercio. La longitud del identificador será de 64 caracteres como máximo.

 
Si la petición es correcta, obtendremos un http status 200 con el identificador del reference creado, así como el value que se le asoció: 

{
    "status": true,
    "code": 0,
    "data": {
        "referenceId": "6d5a802ad90bec047defce7d37157e23433c19a00f25ebbe7bf49d68eef9204b ",
        "value": "reference_value"
    }
}

 

En caso de que la petición sea errónea, obtendremos un http status distinto de 200 que variará en función del error y una descripción del error sucedido. El siguiente ejemplo mostraría el error obtenido al intentar crear un reference sin enviar el parámetro “value” en la petición:
 
{
    "status": false,
    "code": 400,
    "data": [
        {
            "fieldName": "value",
            "message": "may not be null",
            "code": "Validator.notNull",
            "params": {}
        }
    ]
}

En el resto de peticiones que describiremos a continuación el funcionamiento será el mismo, por lo que no entraremos a describir cada una de ellas. Para cada petición se adjuntará un ejemplo de respuesta correcta.

3.- Obtener detalle de un reference

Nos permite obtener el detalle de un reference. La petición a realizar es la siguiente:
 
GET                {urlServidorMymoid}/pay/reference/{referenceId}

 

Siendo el parámetro referenceId de la url el identificador que nos facilitó la operación de crear reference del paso anterior. Como este parámetro se utilizará en las sucesivas llamadas, evitaremos describirlo cada vez ya que siempre hará referencia a lo mencionado anteriormente. La información devuelta por la API será la misma que en la operación de crear reference:
 
{
    "status": true,
    "code": 0,
    "data": {
        "referenceId": "6d5a802ad90bec047defce7d37157e23433c19a00f25ebbe7bf49d68eef9204b ",
        "value": "reference_value"
    }
}

4.- Eliminar un reference

Elimina un reference previamente creado. Se llevará a cabo a la petición

DELETE                {urlServidorMymoid}/pay/reference/{referenceId}

 

Un ejemplo de respuesta sería:

{
    "status": true,
    "code": 0,
    "data": {
        "message": "Reference correctly deleted."
    }
}

Hay que tener en cuenta que si eliminamos un reference, sus medios de pago también serán eliminados (en caso de tener alguno asociado).

5.- Añadir un medio de pago de tipo tarjeta para un reference

Añade un medio de pago de tipo tarjeta a un reference existente. Esta petición será llevada a cabo por el usuario, ya que por motivos de seguridad tiene que ser él el que la de de alta en un entorno que cumpla con los requisitos de seguridad de PCI-DSS. Para ello introducirá el medio de pago en un formulario similar al utilizado en el apartado 9 de la documentación de Pago . La url del formulario al que hay que acceder es la siguiente {urlServidorMymoid}/reference/?referenceId={referenceId} siendo {referenceId} el identificador del reference al que queremos asociar el medio de pago.

El cliente podrá introducir los datos de su tarjeta en el formulario, y si es válida se almacenará el medio pago. Al añadir un medio de pago al cliente se le hará un cargo en la tarjeta para verificar que la tarjeta le pertenece. Este proceso lo describiremos en el apartado 9 de este documento.

6.- Obtener los medios de pago de un reference

Por medio de esta petición podremos obtener los medios de pago asociados a un reference. La petición a realizar sería la siguiente:

GET                {urlServidorMymoid}/pay/reference/{referenceId}/paymentmethod

 

Si el reference no tiene medios de pago, el valor del atributo data de la respuesta estará vacío:
 
{
    "status": true,
    "code": 0,
    "data": []
}

 

En caso contrario, mostrará el detalle de los medios de pago asociados:

 

{
    "status": true,
    "code": 0,
    "data": [
        {
            "paymentMethodType": "CREDIT_CARD",
            "paymentMethodId": "84e17818008a1e170834b23fea682faec29813023dbdb73a82b3627684be887e",
            "firstNumbers": "454881",
            "lastNumbers": "0004",
            "expirationDate": 1608163200000
        }
    ]
}

7.- Obtener el detalle de un medio de pago

Nos permitirá obtener el detalle de un medio de pago concreto por su identificador. La petición para conseguir dicha información será:
 
GET                {urlServidorMymoid}/pay/reference/{referenceId}/paymentmethod/{paymentMethodId}


El parámetro paymentMethodId que utilizaremos en la url es el asociado al medio de pago del que queremos obtener el detalle. Al igual que el parámetro referenceId, paymentMethodId se utilizará en las peticiones que tengan relación con un medio de pago concreto. Por eso no definiremos en cada apartado con qué se corresponde, ya que siempre representará la misma información. La respuesta a esta petición tendrá el siguiente formato:
 
{
    "status": true,
    "code": 0,
    "data": {
        "paymentMethodType": "CREDIT_CARD",
        "paymentMethodId": "84e17818008a1e170834b23fea682faec29813023dbdb73a82b3627684be887e",
        "firstNumbers": "454881",
        "lastNumbers": "0004",
        "expirationDate": 1608163200000
    }
}

8.- Modificación del alias de un medio de pago

Tras haber creado un medio de pago para un reference, podemos actualizar el alias asociado a él. Para ello llevaremos a cabo la siguiente llamada a la API:
 
PUT                {urlServidorMymoid}/pay/reference/{referenceId}/paymentmethod/{paymentMethodId}

El único parámetro que tendremos que incluir en el cuerpo de la petición es el “alias” del medio de pago, que será obligatorio. En caso de no indicar dicho parámetro, recibiremos un httpStatus 400 (Bad Request) y el siguiente mensaje:
 
{
    "status": false,
    "code": 200,
    "data": [
        {
            "message": "Error updating payment method: alias should not be null.",
            "code": "Error updating payment method: alias should not be null."
        }
    ]
}

 

A continuación veremos un ejemplo de petición:
 
{
  "alias" : "Nuevo alias"
}

 

La respuesta recibida sería:

 

{
    "status": true,
    "code": 0,
    "data": {
        "holderName": "Miguel Sanchez",
        "alias": "Nuevo alias",
        "paymentMethodType": "CREDIT_CARD",
        "token": "4295d1a811d31fa5fe3be1b98f3606be576328d5",
        "paymentMethodId": "89c6e4c4d33da4464464f37f0cc377fcee7c2601e592b2fe1b280971b356e9da",
        "expirationDate": 1513468800000
    }
}

 

9.- Eliminar un medio de pago asociado a un reference

Elimina un medio de pago que pertenece a un reference. Se llevará a cabo a través la petición
 
DELETE                {urlServidorMymoid}/pay/reference/{referenceId} paymentmethod/{paymentMethodId}

 

Un ejemplo de respuesta sería:

 
{
    "status": true,
    "code": 0,
    "data": {
        "message": "Payment method successfully deleted."
    }
}

 

10.- Verificación de un medio de pago de tipo tarjeta

Cuando creamos un medio de pago de tipo tarjeta, antes de poder realizar pagos con él es necesario que el usuario lo verifique. En el momento de creación de dicho medio de pago, se realizará un cargo de una determinada cantidad, que el usuario deberá proporcionar para verificar que es el propietario de la tarjeta. Para proceder a la verificación,realizaremos la siguiente llamada
 
PUT                {urlServidorMymoid}/pay/reference/{referenceId}/paymentmethod/{paymentMethodId}/verify/{amount}

 

El valor amount que aparece como parámetro en la url es la cantidad que hemos mencionado anteriormente y que fue cargada en la tarjeta en el momento de creación del medio de pago. Por motivos de seguridad, existe un número máximo de intentos que el usuario podrá realizar para verificar un medio de pago. En caso de superar dicho límite recibiremos un httpStatus 400 (Bad Request) y el siguiente mensaje de error:

 
{
    "status": false,
    "code": 200,
    "data": [
        {
            "message": "This credit card has reached the max attempts to be verified.",
            "code": "Validator.mymoPay.creditCardVerificationMaxAttemtpsReachedError"
        }
    ]
}

Por último, si la verificación se ha llevado a cabo correctamente, el medio de pago quedará habilitado para realizar pagos y recibiremos el siguiente mensaje:
 
{
    "status": true,
    "code": 0,
    "data": {
        "message": "Payment method successfully verified."
    }
}

11.- Realizar un pago usando un medio de pago de un reference

Nos permite realizar un pago de una orden de pago previamente generada (ver información relativa a este proceso en el la documentación de Pago) y en estado AVAILABLE. Para ello, realizaremos la siguiente petición:
 
POST                {urlServidorMymoid}/pay/reference/order/{paymentOrderId}/paymentmethod/{paymentMethodId}

 

El parámetro de la url paymentOrderId lo obtendremos en la respuesta devuelta al generar una orden de pago (ver información relativa a este proceso en el la documentación de Pago). Un ejemplo de respuesta sería:
 
{
    "status": true,
    "code": 0,
    "data": {
        "paymentOrderId": "c8849ce5a9b4eabcc0c29587b16b1b13c1439cbeb188fed8065a69475cd3395f",
        "shortCode": "2NLN1P",
        "currencyCode": "EUR",
        "amount": 2,
        "merchantId": "bacfeb8f01a06f93d76a7d82b6c39c17a7830001b91e22098bae2ff4b226d072",
        "reference": "string reference",
        "concept": "string concept",
        "status": "PAID",
        "currentStatus": {}
    }
}

Como podemos observar en la respuesta, el estado de la orden de pago representado por el atributo "status" de la respuesta ha cambiado a PAID.