Saltar al contenido principal
Migo Docs

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.

Requiere certificación PCI DSS

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).

EntornoHost
Sandboxhttps://sb-mw.migopayments.com
Producciónhttps://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​

Paso PCI

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
}'
CampoTipoNotas
processorstringProcesador de tarjeta para tu cliente (p. ej. visa-cybersource). Confírmalo con Migo.
installmentsnumberNúmero de cuotas (1 si no aplica).
card.numberstringPAN de la tarjeta. Dato PCI.
card.expMonth / card.expYearstringMes 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.cvvstringCódigo de seguridad. Dato PCI.
transactionUidstringEl uid devuelto al crear la transacción.
billToobjectDatos de facturación del titular (firstName, lastName, email, phoneNumber, address, city, state, country, zipCode).
sessionIdstringId de sesión de device fingerprint que exige el procesador para su análisis antifraude.
tokenizebooleantrue para guardar un token reutilizable de la tarjeta.
isForSubscriptionbooleantrue 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​