Guía de integración para negocios

Guía de integración avanzada para negocios

Versión 1.3 Agosto 2014

1. Introducción

En esta guía te explicamos el detalle de las llamadas a la API de MYMOID que componen el proceso de pago. Este documento contiene información técnica. Si lo que buscas es una forma más rápida de incorporar MYMOID a tu e-commerce y comenzar a aceptar pagos, revisa la “Guía rápida para negocios”.

Esta guía asume que has podido registrar tu negocio de forma correcta y dispones de los IDs necesarios para realizar las llamadas (e.g. merchant_id, application_id, application_secret).

2. Pasos para la integración

Paso 0: Preparación de la cabecera para realizar 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 que existen en curso. El contenido que debe llevar la cabecera se debe formar 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 seguido de la clave secreta de aplicación. Esto lo convertimos a Base64 y el resultado lo concatenamos a continuación del texto 'Basic'.

Paso 1: Creación de órdenes de pago

Endpoint

protocolo://servidor/views/button/order

Ejemplo:
https://api.mymoid.com/views/button/order

Llamada

• Verbo: POST
• URL: [ENDPOINT]
• Entrada: OrderDTO
• Salida: PaymentOrderOutDTO

Mediante esta llamada puedes crear ordenes de pago que estarán inmediatamente listas para su ejecución.

Ejemplo

Cuerpo de la solicitud POST para crear una orden de pago sin preautorización:

{
 "currency": "EUR",
 "amount": 100,
 "reference": "Prueba TECHNO",
 "concept": "Prueba TECHNO",
 "payType": "PAY"
}

La respuesta del servicio (nota: contiene los campos pertenecientes al formato estándar de respuesta del API):

{
 "status": true,
 "code": 0,
 "data": {
  "paymentOrderId":"cb89e6ee5d161255aba3f22c507b08b3ed10169c576913b768fe6a78de09e7f1",
  "shortCode": "2N11L2",
  "currencyCode": "EUR",
  "amount": 4990,
  "merchantId":"bacfeb8f01a06f93d76a7d82b6c39c17a7830001b91e22098bae2ff4b226d072",
  "reference": "sw-xl-0231842",
  "concept": "Camiseta Star-Wars XL",
  "status": "AVAILABLE",
  }
 }

Paso 2: Enviar notificación al usuario

Envío de una notificación push al dispositivo del usuario.

Endpoint

protocolo://servidor/views/button/order/{paymentOrderId}/push/{phone}

Ejemplo: https://api.mymoid.com/views/button/order/bb139e49f8431baf3f0a73abba48e50626a68de7907a77f9d5567181d674dd6d/push/+34777777777

Llamada

• Verbo: PUT
• URL: [ENDPOINT]
• Entrada:
• Salida:

Ejemplo de respuesta:

{
}

Paso 3: Consultar el estado de la orden

Si quieres puedes consultar activamente el estado de la orden de pago para ver si se ha llegado a pagar o no (polling).

Endpoint

protocolo://servidor/pay/order

Ejemplo:
https://api.mymoid.com/pay/order/62168ceddec16d15f1b15114a75c4c957eae30315f3b81615da52a790736c9f1

Llamada

• Verbo: GET
• URL: [ENDPOINT]/{paymentOrderId}
• Entrada: identificador de la orden de pago
• Salida: PaymentOrderOutDTO

Ejemplo de respuesta:

{
 "status": true,
 "code": 0,
 "data": {
  "paymentOrderId":"cb89e6ee5d161255aba3f22c507b08b3ed10169c576913b768fe6a78de09e7f1",
  "shortCode": "2N11L2",
  "currencyCode": "EUR",
  "amount": 4990,
  "merchantId":"bacfeb8f01a06f93d76a7d82b6c39c17a7830001b91e22098bae2ff4b226d072",
  "reference": "sw-xl-0231842",
  "concept": "Camiseta Star-Wars XL",
  "status": "PAID",
  "currentStatus": {},
  "expirationCard": "12/15",
  "pan": "xxxxxxxxxxxx0003"
 }
}

Paso 4: Interceptar el callback

Aparte de la confirmación "online" de la operación de pago, MYMOID realiza una llamada "callback" a la URL que hayas indicado a nuestro equipo de soporte. Esta URL debe poder interpretar los datos del callback y devolver una respuesta con un código de estado HTTP OK (200). La solicitud realizada por MYMOID es un POST. A continuación mostramos dos ejemplos del contenido de la llamada:

Ejemplo del cuerpo POST de callback, pago realizado con éxito:

{
 user: {
 publicId:"2516494bc7db56913a1b8970e9d0b4a08065206fa34c2be772c1a26adc681169",
 "paymentMethod":{"pan":"xxxxxxxxxxxx0003",
 "expirationDate":"12/15"}
},
 paymentOrder: {
  reference: "sw-xl-0231842",
  concept: "Camiseta Star-Wars XL",
  amount: 4990,
  currency: "EUR",
  paymentOrderId:"cb89e6ee5d161255aba3f22c507b08b3ed10169c576913b768fe6a78de09e7f1",
  status: "PAID"
 },
  application: {
   name: "MYMOID",
   id:"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }
 }

Ejemplo del cuerpo POST de callback, pago fallido (tarjeta rechazada por el banco):

{
 "user": {
 "publicId":"2516494bc7db56913a1b8970e9d0b4a08065206fa34c2be772c1a26adc681169",
 "paymentMethod":{"pan":"xxxxxxxxxxxx0003",
 "expirationDate":"12/15"}
 },
 "paymentOrder": {
   reference: "sw-xl-0231842",
   concept: "Camiseta Star-Wars XL",
   amount: 4990,
   currency: "EUR",
   paymentOrderId:"cb89e6ee5d161255aba3f22c507b08b3ed10169c576913b768fe6a78de09e7f1",
   status: "PAID"
  },
  "application": {
   "name": "MYMOID",
   "id":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "error": {
   "message": "Invalid card number",
   "code": "Validator.invalidCardNumber"
  }
 }

1. Posibles códigos de error devueltos en el callback

Message: Error authenticating paymentMethod.
Code: Validator.mymoPay.paymentMethodAuthenticationError

Message: Operation not allowed for external merchant. Trade should contact the processing center to solve the problem.
Code: Validator.mymoPay.operationNotAllowedForExternalMerchant.

Message: Gateway system error. Try in a few minutes
Code: Validator.mymoPay.gatewayServiceError

Message: This payment method has expired
Code: Validator.mymoPay.paymentMethodExpired

Message: Amount too small for this transaction
Code: Validator.mymoPay.amountTooSmall

Message: Invalid card number
Code: Validator.invalidCardNumber

Message: Error authenticating paymentMethod
Code: Validator.mymoPay.paymentMethodAuthenticationError

Message: Operation not allowed for this payment method, use another
Code: Validator.mymoPay.paymentMethodNotValid

Paso 5: Cancelar una orden de Pago

Cancelar una orden de pago

Endpoint

protocolo://servidor/pay/order/cancel/

Ejemplo:
https://api.mymoid.com/pay/order/cancel/

Llamada

• Verbo: PUT
• URL: [ENDPOINT]/{paymentOrderId}
• Entrada:
• Salida: PaymentOrderOutDTO

Ejemplo de respuesta:

{
 "status": true,
 "code": 0,
 "data": {
  "paymentOrderId":"e5b71ed0e9fd3d4ba8dc44f85cf8971c50d6db8aacfd5193849a08829ea16389",
  "shortCode":"R23HRR",
  "currencyCode":"EUR",
  "amount":2000,
  "merchantId":"741f8f58d8c2a44c9600a6059f049ba805098650e105264eb06cd772e345577b",
  "reference":"string reference",
  "concept":"string concept",
  "status":"CANCELLED",
  "currentStatus": {}
 }
}

4. DTOs

OrderDTO

@NotNull

String reference; // referencia interna de negocio. Se muestra al usuario.  

@NotNull

String concept; // concepto del pago. Se muestra al usuario.

@NotNull
@Max(999999)

int amount; // cantidad del pago. Se muestra al usuario. Esta cantidad no debe contener fracciones por tanto las dos ultimas cifras se tratan como decimales; por ejemplo un pago de 49,99€ debería rellenar este campo con 4999.

@NotNull

String currency; // moneda del pago. En estos momentos el único valor aceptado por este campo es EUR

@NotNull

 PaymentOrderType payType; // tipo de la orden de pago. (PAY para órdenes que son cobradas al instante y PREAUTH para órdenes que será necesario autorizarlas en un futuro). 

@Size(max = 256)

String payload; // datos adicionales para el negocio. Transparente a MYMOID, se devuelve en el proceso de callback.

PaymentOrderOutDTO
Esta información se devuelve como el resultado de una creación correcta de orden de pago.

String paymentOrderId; // identificador de la orden de pago
String shortCode; // identificador corto de la orden de pago
String currencyCode; // código de la moneda. e.g. EUR
int amount; // cantidad de la orden de pago
String merchantId; // identificador del negocio
String reference; // referencia interna del negocio
String concept; // concepto del pago
String status; // el estado de la orden de pago. Ver Estados de una Orden de Pago

5. Estados de una orden de pago

AVAILABLE: Orden disponible para ser ejecutada.
PREAUTH: Orden ya ejecutada por el usuario y efectivo retenido en su cuenta bancaria, pero que era de tipo PREAUTH y necesita ser confirmada.
PREAUTH_REFUNDED: Orden de tipo PREAUTH la cual fue ejecutada por el usuario, pero el negocio la ha devuelto, devolviendo el efectivo retenido al cliente a su cuenta bancaria.
PREAUTH_EXPIRED: Orden previamente ejecutada por el usuario, pero que no se ha confirmado por el negocio en un periodo de tiempo variable (suele ser de 72 horas).
PAID: Orden pagada.
PARTIALLY_REFUNDED: Orden parcialmente devuelta al usuario por el negocio.
REFUNDED: Orden devuelta al usuario por el negocio.
CANCELLED: Orden cancelada por el negocio. Sólo se puede llegar a este estado desde una orden en estado AVAILABLE.
EXPIRED: Orden expirada. Cuando una orden lleva mucho tiempo inactiva, expira automáticamente.