Merchant Generic Callback
El Merchant Generic Callback es la solicitud HTTP saliente que Migo envía a un endpoint del comercio con los datos del resultado final de la transacción. Aplica a todos los flujos de pago de Migo: transacciones creadas vía link de pago (POST /transactions) y transacciones procesadas vía las APIs de métodos de pago alternativos. Tu backend registra una URL con Migo y recibe ahí la notificación cuando la transacción alcanza su estado final.
Para la mayoría de integraciones Migo envía un payload JSON estándar documentado abajo. El despacho está dirigido por configuración por cliente, así que el método HTTP, URL, headers, body y timeout pueden personalizarse cuando es necesario; el payload estándar cubre el caso común y es lo que deberías diseñar como base de tu handler salvo que hayas acordado un shape personalizado con Migo.
El Merchant Generic Callback no firma el body con HMAC y no tiene reintentos automáticos. La autenticidad se valida con los headers que registres (ver Autenticando la solicitud) y la entrega es un único intento (ver Comportamiento ante error).
Cómo configurar tu callback
Hay dos formas de configurar el callback:
- Configuración asistida por Migo. Envía la información a Migo vía ticket de soporte o tu contacto de integración para que Migo registre tu endpoint.
- Configuración self-service. Si tu comercio tiene acceso habilitado a Client Config Management, puedes actualizar
config.callbackdesde el flujo de Update Client Config.
Para la configuración asistida, envía:
- URL del endpoint. La URL de tu lado que recibirá las notificaciones
POST(por ejemplohttps://api.yourdomain.com/webhooks/transactions). - Headers de seguridad (opcional). Cualquier header HTTP personalizado que Migo deba incluir para que puedas autenticar la solicitud — típicamente un
x-api-keyestático o unAuthorization: Bearer <token>. Por defecto Migo no envía headers extra; debes proveerlos explícitamente si los necesitas.
Configuración self-service vía Client Config Management
Cuando el acceso está habilitado para tu comercio, el flujo de Update Client Config de Client Config Management (PUT /properties en esa superficie) puede persistir la configuración del callback en la estructura existente de Client Config. Envía callback dentro de config; si no envías callback, Update Client Config mantiene el comportamiento anterior y solo actualiza las propiedades que incluiste.
status define los estados transaccionales configurados para el callback. Actúa como filtro sobre los estados que Migo notifica (ver Cuándo se dispara el callback). No lo pongas dentro de callback.data.status: se persiste como callback.status.
Ejemplo de request:
{
"client": "merchant-slug",
"source": "merchant-portal",
"config": {
"callback": {
"enabled": true,
"type": "generic",
"functionName": "generic",
"status": ["approved", "denied"],
"data": {
"url": "https://merchant.example.com/callback",
"method": "POST",
"headers": {
"x-api-key": "<merchant-secret>"
},
"data": {
"reference": "{{reference}}",
"uid": "{{uid}}",
"country": "{{country}}",
"currency": "{{currency}}",
"channel": "{{channel}}",
"status": "{{status}}",
"createdAt": "{{createdAt}}",
"amount": "{{total}}",
"externalId": "{{externalId}}",
"extraData": {
"source": "client-config"
}
}
}
}
}
}
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
config.callback.enabled | boolean | Sí | Habilita la configuración de callback para el cliente. |
config.callback.type | string | Sí | Tipo de callback configurado. Para este contrato usa generic. |
config.callback.functionName | string | Condicional | Nombre de función o mecanismo configurado para el callback. Para callback genérico puede usarse generic; otros mecanismos pueden requerir un valor acordado con Migo. |
config.callback.status | array de strings | Sí | Estados transaccionales configurados para el callback. Debe ser un array no vacío con estados soportados, por ejemplo approved y denied. Se persiste como callback.status. |
config.callback.data.url | string | Sí | URL absoluta de tu receiver. Debe ser válida y no vacía. |
config.callback.data.method | string | Sí | Método HTTP que Migo usará para llamar tu endpoint. Debe ser un método soportado por la configuración de callback. |
config.callback.data.headers | object | Sí | Headers que Migo enviará al receiver. Debe ser un objeto; usa placeholders o valores estáticos solo cuando estén acordados para tu integración. |
config.callback.data.data | object | Sí | Template del body que Migo resolverá contra la transacción antes de enviar el callback. Debe ser un objeto. Acepta una clave extraData con campos adicionales — ver Campos adicionales. |
config.callback.data.extraData | object | No | Objeto opcional que se persiste junto con la configuración del callback. Para agregar campos al body de la notificación, usa extraData dentro de data (ver Campos adicionales). |
Validaciones de configuración:
urldebe ser una URL válida y no vacía.methoddebe ser un método HTTP soportado.headersdebe ser un objeto.datadebe ser un objeto.extraDataes opcional.statusdebe ser un array no vacío con estados soportados.- Si
callbackes inválido, la actualización no se persiste.
Los headers como Authorization, x-api-key, token, secret, password o apiKey pueden contener credenciales. No deben exponerse completos en logs, tickets, capturas o ejemplos compartidos; usa valores enmascarados o placeholders cuando los documentes.
Cuándo se dispara el callback
Migo emite el callback al final de la transacción, solo para estados terminales, sin importar cómo se originó el pago (link de pago, API directa o método de pago alternativo):
| Origen del trigger | Estados que disparan el callback |
|---|---|
| Flujos de pago (tarjetas y métodos de pago alternativos) | approved, denied, refunded, reversed |
| Flujos de captura manual (autorización pendiente de captura) | authorized |
| Flujos de cancelación | cancelled |
| Flujos de servicios / créditos (despacho directo) | approved, denied |
Dos aclaraciones importantes:
authorizedse notifica solo en integraciones con captura manual, cuando el procesador autoriza el pago pendiente de captura.cancelledse notifica cuando la transacción se cancela (por ejemplo, cancelación de un QR o de un pago pendiente).- Otros estados del ciclo de vida (
expired,pending,challenge, etc.) no disparan el Merchant Generic Callback, aunque la configuración acepte declararlos encallback.status. callback.statuses un filtro adicional: si lo defines, de los estados que disparan arriba solo se entregan los que estén en tu lista.
Puedes recibir el callback por cualquiera de los dos caminos dependiendo de qué flujo de Migo manejó la transacción. Tu handler no debe asumir una sola fuente; diseñalo para ser idempotente sobre (uid, status).
Payload estándar
Migo envía un POST con Content-Type: application/json a la URL que registraste. El body es:
{
"reference": "ORDER-98765",
"uid": "ak_D3b0ETlw3HwPmQ3MNK",
"country": "GT",
"currency": "GTQ",
"channel": "WhatsApp",
"status": "approved",
"amount": 150,
"externalId": "ext_auth_123",
"createdAt": "05/03/2026 07:22:32"
}
| Campo | Tipo | Largo máx. | Descripción | Ejemplo |
|---|---|---|---|---|
reference | string | 100 | Referencia emitida por Migo para la transacción. Devuelta en la respuesta de POST /transactions. | ORDER-98765 |
uid | string | 100 | Identificador único de la transacción emitido por Migo. Mismo valor que devuelve la llamada de creación de link. | ak_D3b0ETlw3Hw... |
country | string | 2 | Código ISO 3166-1 alpha-2 del país donde se realizó la operación. | GT |
currency | string | 3 | Código de moneda ISO 4217. | GTQ |
channel | string | 100 | Canal o plataforma donde originó la transacción. | WhatsApp |
status | string | 20 | Estado de la transacción. Uno de approved, denied, reversed, refunded, cancelled; en flujos de captura manual también authorized. | approved |
amount | integer | 12 | Monto total de la transacción en la unidad mínima de la moneda. | 150 |
externalId | string | 100 | Identificador externo asociado a la transacción. Su contenido depende del método de pago y del procesador: puede ser la referencia o id de pago del procesador, el número de orden, el id del QR generado, o el identificador que tu backend envió al crear la transacción. | ext_auth_123 |
createdAt | string | 19 | Marca temporal de cuándo se creó originalmente la transacción, formato DD/MM/YYYY HH:MM:SS. | 05/03/2026 07:22:32 |
Campos adicionales (extraData)
Si necesitas que la notificación incluya campos extra, configura extraData dentro del template del body (data en la configuración del callback): un objeto de pares clave/valor que se agrega al payload. Los valores pueden ser estáticos o placeholders {{...}} resueltos contra la transacción.
La composición del body sigue estas reglas:
- Sin template de body configurado → Migo envía el payload estándar de arriba.
- Template de body solo con
extraData→ Migo envía el payload estándar más tus campos extra. - Template de body con campos propios → tus campos reemplazan el payload estándar, y
extraDatase agrega al final.
Autenticando la solicitud en tu lado
El Merchant Generic Callback no firma el body con HMAC. La autenticidad se delega al comercio mediante los headers que registraste con Migo — típicamente un API key estático en Authorization o un header personalizado (por ejemplo x-api-key).
Verifica el header en tu handler antes de procesar el body. Si necesitas garantías más fuertes (HMAC, JWT firmado, mTLS), coordínalo con Migo para extender la configuración de tu cliente; no es parte del contrato estándar.
Esqueleto de receiver (Node.js / Express)
import express from 'express';
const app = express();
const MIGO_API_KEY = process.env.MIGO_WEBHOOK_API_KEY;
app.post(
'/webhooks/transactions',
express.json({ limit: '1mb' }),
async (req, res) => {
// 1. Authenticate the request via the header you registered with Migo.
if (req.header('x-api-key') !== MIGO_API_KEY) {
return res.status(401).send('invalid credentials');
}
const { uid, status, reference, amount, currency } = req.body;
// 2. Idempotency: dedupe on (uid, status). Migo may deliver the same
// notification more than once if a queued message is replayed.
if (await alreadyProcessed(uid, status)) {
return res.status(200).json({ ack: 'duplicate' });
}
// 3. Process based on req.body.status:
// - "approved" -> mark order as paid, fulfill, etc.
// - "denied" -> mark order as failed, notify the customer.
// - "refunded" -> reverse fulfillment, update accounting.
// - "reversed" -> idem.
// - "authorized" -> payment authorized, pending capture (manual capture flows).
// - "cancelled" -> transaction cancelled, release the order.
await processCallback(req.body);
// 4. Respond 2xx so Migo records a successful delivery.
res.status(200).json({ ack: 'received' });
},
);
Recomendaciones:
- Responde siempre
2xxuna vez tu procesamiento sea durable; fallar la respuesta hace que Migo registre un error de entrega. - Haz tu handler idempotente sobre
(uid, status). Trata las entregas repetidas como un caso normal. - Valida el schema contra el payload estándar de arriba; extiéndelo solo si tienes acordado un payload personalizado con Migo.
- Mantén el procesamiento rápido o muévelo a una cola dentro de tu sistema. Migo aplica un timeout por defecto de 25 segundos.
Comportamiento ante error
Migo hace un solo intento de entrega por notificación: no hay reintentos automáticos en ningún camino de despacho. Si tu endpoint responde un error HTTP o la solicitud excede el timeout (25 segundos por defecto), el fallo se registra y la solicitud / respuesta se persisten como pasos de la transacción, de modo que el operador de Migo puede reprocesar manualmente si es necesario.
Aun sin reintentos, diseña tu handler idempotente: la infraestructura de colas que despacha parte de los callbacks garantiza entrega at-least-once, por lo que ocasionalmente puedes recibir la misma notificación más de una vez.
Si tu negocio requiere garantías de entrega específicas, coordínalo con Migo.
Ejemplo de configuración
{
"enabled": true,
"type": "generic",
"functionName": "generic",
"status": ["approved", "denied"],
"data": {
"method": "POST",
"url": "https://api.merchant.com/migo/callback?trx={{uid}}",
"headers": {
"Authorization": "Bearer <merchant-static-api-key>",
"Content-Type": "application/json"
},
"data": {
"transactionUid": "{{uid}}",
"reference": "{{reference}}",
"status": "{{status}}",
"amount": "{{total}}",
"currency": "{{currency}}",
"metadata": "{{customKeys}}",
"extraData": {
"source": "client-config"
}
},
"timeout": 30000
}
}
Cuando una transacción con uid = "abcd1234efgh" alcanza approved, Migo envía un POST a https://api.merchant.com/migo/callback?trx=abcd1234efgh con el header Authorization de arriba y un body JSON donde cada placeholder se resuelve contra la transacción, más el campo source agregado por extraData.
Relacionado
- Crear un link de pago — el contrato entrante que llamas para obtener la URL del webview.
- Webview hospedado — la experiencia de pago del cliente para links de pago.