Flujo de pago por API (requiere PCI)
Además del webview hospedado, puedes gestionar el flujo de pago tú mismo por API: recolectas los datos de la tarjeta en tu propio frontend y los envías a Migo para autorizar el cobro. Tú controlas toda la experiencia de checkout.
Este flujo envía datos de tarjeta en crudo (PAN, CVV y vencimiento) a la API de Migo. Recolectar, transmitir o almacenar datos de tarjeta sin tokenizar te obliga a estar certificado PCI DSS con el nivel que corresponda a tu volumen.
Si no cuentas con certificación PCI, este flujo no funcionará para ti — integra con el webview hospedado de links de pago: el cliente ingresa la tarjeta dentro de la página de Migo y tú nunca tocas los datos de tarjeta, por lo que tu alcance PCI se reduce a SAQ-A.
Resumen del flujo
1. POST /transactions crea la transacción → uid
2. POST /pay envía los datos de tarjeta → autoriza el cobro (requiere PCI)
3. GET /transactions?uid=... consulta el estado
4. POST /pay/revert reversa un cobro autorizado
5. POST .../{uid}/dismiss descarta una transacción no pagada
Es el mismo modelo de transacción que el link de pago: creas la transacción igual, pero en lugar de entregar la URL del webview al cliente, tú capturas la tarjeta y llamas a /pay.
Autenticación y hosts
Todas las llamadas se autentican con tu merchant token en el header Authorization (token crudo; un prefijo Bearer se tolera y se elimina).
| Entorno | Host |
|---|---|
| Sandbox | https://sb-mw.migopayments.com |
| Producción | https://mw.migopayments.com |
1. Crear la transacción
Idéntico a Crear un link de pago: POST /transactions.
curl -X POST https://sb-mw.migopayments.com/transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{
"client": "<your-client-slug>",
"amount": 49,
"currency": "GTQ",
"userId": "oo41332322",
"channel": "web",
"ads": []
}'
Respuesta:
{
"uid": "RULbsGlJRAWFCi6TkuTEa",
"reference": "INFOTECHGT000015",
"URL": "https://sandbox.migopayments.com/?orderId=RULbsGlJRAWFCi6TkuTEa"
}
En este flujo ignoras el campo URL (es el webview hospedado) y te quedas con el uid para cobrar por API.
2. Cobrar con los datos de tarjeta — POST /pay
Este es el único paso que toca datos de tarjeta. Solo envíalo desde un backend dentro de tu alcance PCI — nunca desde el navegador con tu merchant token expuesto.
curl -X POST https://sb-mw.migopayments.com/pay \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{
"processor": "visa-cybersource",
"installments": 1,
"card": {
"number": "4111111111111111",
"expMonth": "11",
"expYear": "2030",
"cvv": "123"
},
"transactionUid": "RULbsGlJRAWFCi6TkuTEa",
"billTo": {
"firstName": "Braian",
"lastName": "Florian",
"email": "cliente@example.com",
"phoneNumber": "50244866448",
"address": "Guatemala zona 10, Oakland",
"city": "Guatemala",
"state": "GU",
"country": "GT",
"zipCode": "01000"
},
"sessionId": "58f60d2807514d8d9700308bad100287",
"tokenize": false,
"isForSubscription": false
}'
| Campo | Tipo | Notas |
|---|---|---|
processor | string | Procesador de tarjeta para tu cliente (p. ej. visa-cybersource). Confírmalo con Migo. |
installments | number | Número de cuotas (1 si no aplica). |
card.number | string | PAN de la tarjeta. Dato PCI. |
card.expMonth / card.expYear | string | Mes y año de vencimiento. El formato del año depende del procesador de tu cuenta —dos o cuatro dígitos— y te lo confirmamos al habilitarla. Mandar el que no corresponde no se rechaza como error de validación: se manifiesta como una falla de comunicación con el procesador. |
card.cvv | string | Código de seguridad. Dato PCI. |
transactionUid | string | El uid devuelto al crear la transacción. |
billTo | object | Datos de facturación del titular (firstName, lastName, email, phoneNumber, address, city, state, country, zipCode). |
sessionId | string | Id de sesión de device fingerprint que exige el procesador para su análisis antifraude. |
tokenize | boolean | true para guardar un token reutilizable de la tarjeta. |
isForSubscription | boolean | true si el cobro corresponde a una suscripción. |
Respuesta (aprobado) — incluye el estado y el paymentData del procesador:
{
"transaction": {
"reference": "INFOTECHGT000015",
"status": "approved",
"channel": "web",
"createdAt": "2026-06-12T22:43:39.000Z",
"paymentData": { "id": "7813042339096130604807", "pay": { "...": "..." } }
}
}
3. Consultar la transacción — GET /transactions
curl 'https://sb-mw.migopayments.com/transactions/?uid=RULbsGlJRAWFCi6TkuTEa' \
-H 'Authorization: <merchant-token>'
Devuelve el registro completo de la transacción, incluido status (approved, reversed, …), total, currency, installments, los timestamps y paymentInfo — un resumen normalizado del pago (marca y últimos 4 dígitos de la tarjeta, datos del pagador, resultado de 3D Secure y los eventos de autorización/captura) que es igual sin importar qué procesador atendió el cobro. Ver Detalles de pago normalizados (paymentInfo) para la forma completa del campo.
4. Reversar un cobro — POST /pay/revert
curl -X POST https://sb-mw.migopayments.com/pay/revert \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{ "transactionUid": "RULbsGlJRAWFCi6TkuTEa" }'
La transacción pasa a status: "reversed".
5. Descartar una transacción — POST .../{uid}/dismiss
Para una transacción aún no pagada (abandonada o expirada):
curl -X POST https://sb-mw.migopayments.com/api/v1/integrations/transactions/RULbsGlJRAWFCi6TkuTEa/dismiss \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>'
Responde 200 OK. Comportamiento y estados elegibles en Descartar transacción.
Recibir el resultado
El estado terminal también se entrega a tu backend mediante el Merchant Generic Callback, igual que en el flujo del webview hospedado.
Errores
Consulta el Catálogo de errores para los códigos de error del Middleware (error.code) y su semántica.
Relacionado
- Webview hospedado — la alternativa sin requerimiento PCI (alcance SAQ-A).
- Crear un link de pago — el paso de creación de la transacción.
- Anulaciones y reembolsos.