Saltar al contenido principal
Migo Docs

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.

Contrato sin firma ni reintentos

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.callback desde el flujo de Update Client Config.

Para la configuración asistida, envía:

  1. URL del endpoint. La URL de tu lado que recibirá las notificaciones POST (por ejemplo https://api.yourdomain.com/webhooks/transactions).
  2. Headers de seguridad (opcional). Cualquier header HTTP personalizado que Migo deba incluir para que puedas autenticar la solicitud — típicamente un x-api-key estático o un Authorization: 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"
}
}
}
}
}
}
CampoTipoRequeridoDescripción
config.callback.enabledbooleanSíHabilita la configuración de callback para el cliente.
config.callback.typestringSíTipo de callback configurado. Para este contrato usa generic.
config.callback.functionNamestringCondicionalNombre 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.statusarray de stringsSí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.urlstringSíURL absoluta de tu receiver. Debe ser válida y no vacía.
config.callback.data.methodstringSí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.headersobjectSí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.dataobjectSí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.extraDataobjectNoObjeto 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:

  • url debe ser una URL válida y no vacía.
  • method debe ser un método HTTP soportado.
  • headers debe ser un objeto.
  • data debe ser un objeto.
  • extraData es opcional.
  • status debe ser un array no vacío con estados soportados.
  • Si callback es inválido, la actualización no se persiste.
Headers sensibles

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 triggerEstados 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óncancelled
Flujos de servicios / créditos (despacho directo)approved, denied

Dos aclaraciones importantes:

  • authorized se notifica solo en integraciones con captura manual, cuando el procesador autoriza el pago pendiente de captura.
  • cancelled se 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 en callback.status.
  • callback.status es 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"
}
CampoTipoLargo máx.DescripciónEjemplo
referencestring100Referencia emitida por Migo para la transacción. Devuelta en la respuesta de POST /transactions.ORDER-98765
uidstring100Identificador único de la transacción emitido por Migo. Mismo valor que devuelve la llamada de creación de link.ak_D3b0ETlw3Hw...
countrystring2Código ISO 3166-1 alpha-2 del país donde se realizó la operación.GT
currencystring3Código de moneda ISO 4217.GTQ
channelstring100Canal o plataforma donde originó la transacción.WhatsApp
statusstring20Estado de la transacción. Uno de approved, denied, reversed, refunded, cancelled; en flujos de captura manual también authorized.approved
amountinteger12Monto total de la transacción en la unidad mínima de la moneda.150
externalIdstring100Identificador 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
createdAtstring19Marca 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 extraData se 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 2xx una 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​