Saltar al contenido principal
Migo Docs

Integra tu solución de pagos

Esta página es para proveedores — wallets de push, redes de QR, bancos o rieles de efectivo (como akisiQR o Nequi) — que quieran que Migo enrute pagos a su servicio. Describe lo que tu servicio debe exponer para que Migo pueda ofrecer tu riel a los comercios.

En la integración, Migo es el orquestador: un comercio crea una transacción con Migo, el cliente elige tu riel y Migo le pide a tu servicio que produzca la instrucción de pago. Tu servicio es dueño de la experiencia de pago del cliente y reporta el resultado a Migo.

Flujo de integración (ejemplo akisiQR)​

Comercio ──► Migo ──► tu servicio: crear pago / QR
                          │
                          ▼
              devuelves un QR / URL / referencia, o haces push a la app del cliente, + tu id de transacción
                          │
                          ▼
              el cliente paga en tu app / escanea el QR / aprueba el push
                          │
                          ▼
   tu servicio ──► webhook de Migo: "este pago se completó"
                          │
                          ▼
              (opcional) Migo ──► tu servicio: cancelar / reversar

Esto es exactamente lo que provee akisiQR: una API para que Migo cree el QR de akisi, y un webhook que le avisa a Migo cuando el usuario final lo pagó.

Servicios API requeridos​

1. Crear un pago (QR / cobro)​

Un endpoint que Migo llama para iniciar un pago de tu lado. Recibe el monto, la moneda, una referencia externa y cualquier identificador del cliente, y devuelve la instrucción de pago más tu id de transacción.

  • Request (desde Migo): monto, moneda, referencia externa, identificador del cliente (requerido para rieles de push como Nequi, donde la solicitud va dirigida al teléfono / app del cliente).
  • Response (hacia Migo): tu id de transacción + la instrucción de pago en una de estas formas:
    • un QR (imagen base64 o string EMVCo),
    • una URL de redirección a tu página hospedada,
    • una referencia estructurada (p. ej. un código de pago/efectivo), o
    • un push a la app del cliente — para rieles de push (como Nequi), tu servicio envía una solicitud de pago directo a la wallet del cliente (por número de teléfono / id de usuario). No hay nada que el comercio renderice; el cliente aprueba en tu app y el resultado llega por tu webhook. En este caso la respuesta solo necesita confirmar que el push se envió (tu id de transacción + un estado pendiente).
  • Expiración: la respuesta debe incluir el momento de expiración de la instrucción de pago (expiresAt, o la ventana de validez en segundos). Pasado ese tiempo el QR / URL / push deja de ser pagable y debes notificar el resultado EXPIRED por el webhook.
Los rieles de push pueden requerir un paso previo

Si tu riel de push requiere que el comercio provea o confirme un valor primero (p. ej. el número de teléfono registrado del cliente), expón una consulta ligera para que Migo pueda obtenerlo antes de crear el pago. Migo lo expone a los integradores como un payment intent.

2. Webhook de notificación de pago​

Tu servicio debe notificar a Migo cuando el usuario final complete (o falle) el pago — este es el resultado autoritativo. Migo expone una URL de webhook dedicada por proveedor, y tu servicio hace POST de un cuerpo JSON cuando el pago alcanza un estado terminal.

  • Envía a Migo: tu id de transacción (y/o la referencia externa), el estado final, el monto y cualquier código de autorización.
  • Debe enviarse para cada resultado terminal y debe reintentarse hasta recibir confirmación con un 200.

Estructura del webhook​

Los campos de abajo son el contrato común de los rieles que ya tenemos (akisiQR, Nequi, …). El identificador de transacción y el código de resultado son obligatorios; el resto se envía cuando tu riel los produce. Los nombres exactos de los campos se confirman durante el onboarding.

CampoTipoRequeridoDescripción
transactionIdstringSíEl id que tu servicio devolvió al crear el pago (o la referencia externa que Migo envió). Migo lo usa para localizar la transacción.
responseCodestringSíCódigo de resultado terminal — ver mapeo abajo.
descriptionstringSíDescripción legible del estado (p. ej. "Authorizado").
amountstringSíMonto pagado, como string para evitar pérdida de decimales.
currencystringCuando aplicaCódigo de moneda ISO (p. ej. COP, GTQ).
authorizationCodestringCuando esté disponibleCódigo de autorización / aprobación de tu lado.

Mapeo de responseCode — el webhook debe enviarse en todo resultado terminal, no solo en los exitosos:

responseCodeEstado en MigoCuándo lo envías
00APPROVEDel cliente pagó
01DENIEDel pago fue rechazado o el usuario no quiso pagarlo
11CANCELLEDel cliente o el sistema canceló el pago
12EXPIREDel pago expiró sin pagarse (acuerda el valor exacto con Migo si tu riel usa otro)
Notifica también los resultados no exitosos

No basta con avisar los pagos aprobados. Tu webhook debe disparar igualmente cuando el pago se cancela, cuando el usuario decide no pagarlo / lo rechaza, y cuando expira sin completarse — así Migo cierra la transacción y libera al comercio en lugar de dejarla colgada en PENDING.

Ejemplos de payload:

webhook akisiQR
{
  "responseCode": "00",
  "description": "Authorizado",
  "amount": "30",
  "commerce_name": "migoTest",
  "transactionId": "33273710655533943897"
}
webhook Nequi
{
  "responseCode": "00",
  "authorizationCode": "ABC123456",
  "description": "Pago autorizado",
  "currency": "COP",
  "amount": "50000",
  "transactionId": "TRX-20240603-12345"
}

Migo confirma el webhook con:

Confirmación de Migo
{
  "success": true,
  "message": "Webhook received",
  "data": {
    "uid": "<uid de transacción de migo>",
    "status": "approved",
    "total": 30,
    "externalId": "33273710655533943897"
  }
}
Entrega

POST sobre HTTPS con Content-Type: application/json, autenticado según lo acordado (ver Autenticación). Considera la llamada exitosa solo ante un HTTP 200 con "success": true; reintenta ante cualquier otro resultado hasta recibir confirmación.

3. Cancelación / reversión (si está disponible)​

Si tu riel lo soporta, expón un endpoint que Migo pueda llamar para cancelar un pago pendiente o reversar uno completado. Indica claramente qué se soporta (cancelar antes de completar, reembolsar después) y cualquier ventana de tiempo. Si tu riel no soporta reversión, documéntalo explícitamente.

Otros requisitos​

Métodos de autenticación​

Define cómo se autentican ambas direcciones:

  • Migo → tu API: cómo Migo autentica sus llamadas hacia ti (p. ej. API key, OAuth2 client credentials, requests firmados con HMAC, o mTLS).
  • Tu webhook → Migo: cómo Migo verifica que el webhook vino de ti (p. ej. un secreto compartido / header de firma).

Soporta al menos un mecanismo estándar de la industria en cada dirección.

Límites y expiración​

Declara las restricciones operativas de tu riel para que Migo valide antes de crear el pago y no genere cobros que tu servicio rechazará:

  • Monto mínimo y máximo soportados, por moneda (p. ej. GTQ 1.00–GTQ 50 000.00). Indica también el número de decimales que maneja la moneda.
  • Tiempo de expiración de la instrucción de pago: cuánto tiempo es válido el QR / URL / push antes de caducar (un valor fijo del riel, o configurable por transacción). Migo lo usa para fijar el expiresAt y para esperar el resultado EXPIRED.

Ambiente de pruebas y credenciales​

Provee un ambiente de sandbox y credenciales de prueba para que Migo pueda construir y certificar la integración sin mover dinero real — incluyendo una forma de simular un pago exitoso, una falla y una expiración.

Documentación​

Provee documentación escrita de la API que cubra: endpoints y payloads, autenticación, valores de estado, códigos de error, el contrato del webhook, y las URLs base y credenciales de sandbox.

Siguientes pasos​

Para iniciar una integración como proveedor, contacta a tu contacto comercial o de integraciones de Migo con los puntos anteriores. Migo compartirá el endpoint de webhook, las credenciales y el checklist de certificación.