Procesar pago alternativo
Inicia el flujo de pago alternativo con un procesador específico seleccionado de la lista retornada en el momento de creación. La forma de la respuesta depende del procesador — Migo la normaliza mediante un discriminador data.type para que el frontend del comercio pueda renderizar la UI correcta.
POST https://mw.migopayments.com/api/v1/integrations/transactions/{transactionId}/payments
Consulta la entrada en el spec en vivo: POST /api/v1/integrations/transactions/{transactionId}/payments.
Recordatorio de auth. Toda llamada envía
Authorization: Bearer <token>.
Petición — un solo body para todos los métodos
El body es idéntico para cada procesador: un processor más un objeto data. Mapea una sola vez todos los campos posibles de data y deja en null o vacíos los que no apliquen al método elegido — el runtime de Migo lee únicamente las llaves que el processor necesita e ignora el resto. Así mantienes un único tipo de body del lado del cliente para todos los métodos.
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
processor | string | sí | Debe estar presente en el array paymentMethods retornado al crear la transacción. |
data | object | sí (puede ir {}) | Envoltorio unificado de campos. Envía todos los campos y deja en null los que no apliquen; ve el mapeo de campos por procesador. |
Mapeo de campos por procesador
Mantén un único data que cubra todos los métodos. Llena solo lo que aplica al processor elegido; el resto va en null, vacío u omitido — Migo solo lee las llaves del procesador activo.
{
"processor": "<akisiQR | bamPaymentButton | bancoIndustrial | pronet | quickPayQR | yoloQR | zigi | zigiQR | nequi | globalPay-PSE | fri>",
"data": {
"phoneNumber": null,
"user": null,
"bank": { "key": null },
"email": null,
"fisType": { "key": null },
"fiscalNumber": null,
"installments": null,
"userName": null,
"userType": { "key": null }
}
}
Campo en data | Tipo | Usado por |
|---|---|---|
phoneNumber | string | nequi; fri (al menos uno de phoneNumber / user) |
user | string | fri (al menos uno de phoneNumber / user) |
bank | object { key } | globalPay-PSE |
email | string | globalPay-PSE |
fisType | object { key } | globalPay-PSE |
fiscalNumber | string | globalPay-PSE |
installments | number | globalPay-PSE |
userName | string | globalPay-PSE |
userType | object { key } | globalPay-PSE |
Procesadores sin campos en data (envía data: {}): akisiQR, bamPaymentButton, bancoIndustrial, pronet, quickPayQR, yoloQR, zigi, zigiQR. En Guatemala todos los métodos disponibles caen aquí — el cliente paga desde su app tras el QR / push de Migo.
Los valores de los campos de globalPay-PSE (las llaves de bank, fisType, userType) y el descriptor de campos de fri se obtienen vía payment intents.
cURL — BAM Payment Button (Guatemala)
curl -X POST https://mw.migopayments.com/api/v1/integrations/transactions/trx_8f3c2b1d9e7a/payments \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"processor": "bamPaymentButton",
"data": {}
}'
Node.js
const res = await fetch(
`https://mw.migopayments.com/api/v1/integrations/transactions/${transactionId}/payments`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MIGO_JWT}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
processor: 'bamPaymentButton',
data: {},
}),
}
);
const { data } = await res.json();
// data.type drives the rendering branch
if (data.type === 'url') window.location.href = data.data; // Zigi, BAM Payment Button
if (data.type === 'base64') renderImage(data.data); // Akisi QR, Banco Industrial, YOLO QR
if (data.type === 'json') renderStructuredPayload(data.data); // Pronet, QuickPay QR, FRI
Ejemplos de petición por procesador
Cada ejemplo usa la misma forma de body unificada. Mantén el mismo tipo del lado del cliente y solo pobla los campos que aplican — Migo ignora las llaves fuera del payload del procesador activo.
Guatemala — métodos sin data
akisiQR, bamPaymentButton, bancoIndustrial, pronet, quickPayQR, yoloQR, zigi, zigiQR — el cliente paga desde su app después de que Migo emite el QR / push notification. Envía data vacío:
{
"processor": "akisiQR",
"data": {}
}
yoloQR (billetera YOLO de Bantrab)
yoloQR sigue esta misma forma (data vacío) y devuelve un QR listo para pintar en data.type base64:
{
"success": true,
"message": "Success",
"data": {
"transaction_id": "37d25fa5-608f-f111-9968-005056afc378",
"type": "base64",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMQAAADE…",
"cancelAt": 600
}
}
transaction_id es el identificador del cobro en Bantrab, no el uid de la transacción en Migo: para consultar el estado o descartar la transacción, usa el uid que devolvió crear transacción.
Antes de integrarlo, conviene conocer estas reglas:
- Solo GTQ. En una transacción en otra moneda, yoloQR no aparece en data.paymentMethods y /payments responde 400.
- Monto dentro de los límites. Migo aplica el mínimo y el máximo configurados para tu cuenta y para el método; si no hay un mínimo configurado, el mínimo es GTQ 50.00. Fuera de esos límites el método sigue apareciendo en data.paymentMethods y la página de pago lo muestra deshabilitado u oculto, según la configuración de tu cuenta; una llamada directa a /payments se rechaza con 400.
- QR de un solo uso. Cada QR admite un único pago y cada transacción genera un solo QR. Si el cliente necesita intentarlo de nuevo, crea una transacción nueva.
- Vencimiento del lado de Migo. El campo cancelAt indica cuántos segundos le quedan al QR; al vencer, Migo cancela la transacción. El proveedor no admite reversos ni cancelaciones, así que descartar la transacción solo la cancela en Migo.
- Confirmación asíncrona. El resultado llega cuando el proveedor notifica el pago, y Migo te lo informa por el callback configurado para tu cuenta.
- Pago después del vencimiento. Si el cliente paga un QR que ya venció, la transacción sigue cancelled y no recibes un nuevo callback: el pago queda para revisión manual de Migo. Si tu cliente reporta haber pagado una transacción vencida, contacta a Migo Operations con el uid.
Para mostrar el avance mientras el cliente paga, consulta el estado de la transacción. El campo cancelAt es el tiempo que le queda al QR:
curl https://mw.migopayments.com/api/v1/integrations/transactions/{transactionId} \
-H 'Authorization: Bearer <token>'
{
"success": true,
"message": "Transaction status",
"data": {
"uid": "{transactionId}",
"status": "pending",
"cancelAt": 2940
}
}
Si la transacción no existe o no pertenece a tu cuenta, la consulta responde 404. El estado que devuelve es el que Migo tiene guardado; el resultado autoritativo sigue siendo el callback.
Como con cualquier otro método, la lista autoritativa para una transacción es el array data.paymentMethods que devuelve crear transacción: si yoloQR no aparece ahí, no está habilitado para tu cuenta. Contacta a Migo Operations para solicitarlo.
fri (push payment, sandbox de Guatemala)
fri requiere al menos uno de user o phoneNumber (descriptor obtenido vía payment intents):
{
"processor": "fri",
"data": { "user": "fri-user-001" }
}
globalPay-PSE (Colombia — selector de banco)
Rellena el data con los valores que devuelve el payment intent:
{
"processor": "globalPay-PSE",
"data": {
"bank": { "key": "1552" },
"email": "cliente@example.com",
"fisType": { "key": "CC" },
"fiscalNumber": "2345678421",
"installments": 1,
"userName": "John Doe",
"userType": { "key": "N" }
}
}
Forma de respuesta por data.type
data.type | Estrategia de render | Campo de payload | Procesadores de ejemplo |
|---|---|---|---|
url | Redireccionar al cliente a la URL | data.data es el string de URL | Zigi, BAM Payment Button |
qr | Renderizar imagen QR a partir de un string EMVCo crudo | data.data es el string del QR | (ninguno actualmente) |
base64 | Insertar el valor directo en <img src=...> | data.data es un URI data:image/png;base64,… | Akisi QR, Banco Industrial, YOLO QR |
json | Payload estructurado (referencias) | data.data es el payload estructurado | Pronet, QuickPay QR, FRI |
data.data, no data.valueEl runtime emite el payload bajo data.data. Recetas anteriores (especialmente recipes/guatemala.md) usaban data.value — esa variante está desactualizada. Al parsear la respuesta, siempre lee data.data.
Ejemplo para type: "url":
{
"success": true,
"message": "success",
"data": {
"uid": "trx_8f3c2b1d9e7a",
"type": "url",
"data": "https://gateway.example.com/redirect/abc",
"cancelAt": 600
}
}
Ejemplo para type: "base64" (Akisi QR — verificado contra sb-mw.migopayments.com):
{
"success": true,
"message": "Success",
"data": {
"transaction_id": "12740927961946781727",
"type": "base64",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAJQAAA…"
}
}
El identificador de la transacción en la respuesta vuelve como uid para algunos rieles (p. ej. Zigi, BAM Payment Button) y como transaction_id para otros (p. ej. Akisi QR, QuickPay QR, YOLO QR). Los dos campos que siempre debes leer para renderizar son type y data.
Detalles del pago
Una vez confirmada, la transacción expone el resultado normalizado en paymentInfo, igual que los pagos con tarjeta: el método de pago, el pagador y los eventos de cobro. Los métodos alternativos se cobran en un solo paso, así que paymentInfo.authorization viene vacío y el resultado está en paymentInfo.capture. Ver Detalles de pago normalizados (paymentInfo).
Polling vs webhooks
Migo confirma el estado final mediante el webhook del procesador (APPROVED, DENIED, EXPIRED; en yoloQR el vencimiento termina en cancelled). Para UX puedes hacer polling al estado de la transacción cada 3–5 segundos mientras el cliente completa el rail; no dependas del polling como fuente de verdad — el webhook es autoritativo.
Errores
| HTTP | Causa |
|---|---|
| 400 | Parámetros faltantes, procesador no permitido para este cliente, o llaves de data requeridas faltantes (la respuesta incluye data.missingValues) |
| 401 | Falló la autenticación del lado del usuario (Ridivi) |
| 405 | Procesador temporalmente no disponible (por ejemplo, Banco Industrial retorna un unavailabilityReason) |
| 500 | El request al procesador no pudo ser procesado |
Para la semántica de cada ownCode del Middleware y el mapeo de status codes, consulta el Catálogo de errores.