Callback de suscripciones
Migo notifica a tu backend por HTTP POST cada vez que cambia el estado de una suscripción o se
ejecuta un cobro. Ese aviso —subsCallback— es tu fuente de verdad.
Que el cliente vuelva a tu URL de éxito no significa que el pago se haya aprobado: puede cerrar la pestaña antes, o abrir esa URL a mano. Da acceso solo cuando llega el callback.
Los dos avisos del primer cobro
El primer pago dispara dos notificaciones distintas, con el mismo identificador de transacción.
Distínguelas por la presencia de subscriptionId:
| Aviso | Trae subscriptionId | Qué hacer |
|---|---|---|
| Resultado del pago | No | Trátalo como un pago puntual |
subsCallback | Sí | Da de alta / renueva / revoca la suscripción |
app.post('/migo/callback', async (req, res) => {
if (!verificarSecreto(req)) return res.status(401).end();
const { subscriptionId } = req.body;
if (subscriptionId) {
await manejarSuscripcion(req.body); // idempotente
} else {
await manejarPago(req.body); // resultado del cobro
}
return res.status(200).end(); // responde rápido
});
Si respondes algo distinto de 2xx, Migo reintenta. Por eso tu handler debe ser idempotente.
Payload — subsCallback
Los campos van en la raíz del cuerpo:
{
"subscriptionId": "sub_000001",
"transactionId": "trx_A1",
"status": "active",
"transactionStatus": "approved",
"plan": "Plan mensual",
"amount": 99.00,
"email": "cliente@ejemplo.com",
"nextRenewalDate": "Sat Aug 08 2026 06:00:00 GMT+0000 (Coordinated Universal Time)"
}
| Campo | Notas |
|---|---|
subscriptionId | El identificador de la suscripción. Es lo que distingue este aviso del de pago. |
transactionId | La transacción que originó el cobro |
status | active o inactive |
nextRenewalDate | No es ISO 8601. Es un Date.toString() de JavaScript — parséalo con una librería tolerante, no con Date.parse estricto. |
amount | Número en el subsCallback; string en el callback de pago. No asumas el mismo tipo en ambos. |
Estados que llegan por callback
status | Cuándo |
|---|---|
active | Alta de la suscripción y cada renovación cobrada con éxito |
inactive | Se agotaron los reintentos de cobro — deja de facturar y revoca el acceso |
cancelled y expired no se notificanEl callback solo emite active e inactive. Si necesitas enterarte de una cancelación o de un
vencimiento, concilia contra la API: consulta
GET /api/v1/subscriptions/detail/{subUid}
con un job periódico. Es el hueco más común al construir sobre esta integración.
Autenticación del aviso
El aviso llega con una cabecera y un secreto que se configuran por comercio — no hay HMAC ni un nombre de header fijo. También se soporta HTTP Basic.
Verifica el secreto antes de leer el cuerpo y responde 401 si no coincide. Acuerda con Migo el
nombre exacto de la cabecera y el secreto al dar de alta tu cuenta.
Payload configurable
El cuerpo se arma con una plantilla por comercio, así que las llaves exactas que recibas dependen de tu configuración.
La plantilla por defecto puede omitir subscriptionId y transactionId. Sin ellos no puedes ni
distinguir los dos avisos ni conciliar. Confirma con Migo que ambos estén incluidos antes de salir a
producción.
Prueba tu handler sin esperar un pago real
Manda estos POST a tu propio endpoint. Reproducen la forma real del aviso:
# 1. Alta / renovación → dar acceso
curl -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: $CALLBACK_SECRET" \
-d '{"subscriptionId":"sub_TEST_001","transactionId":"trx_TEST_A1","status":"active",
"transactionStatus":"approved","plan":"Plan mensual","amount":99.00,
"email":"cliente@ejemplo.com",
"nextRenewalDate":"Sat Aug 08 2026 06:00:00 GMT+0000 (Coordinated Universal Time)"}'
# 2. Resultado del pago del MISMO cobro (sin subscriptionId, amount es string)
curl -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: $CALLBACK_SECRET" \
-d '{"uid":"trx_TEST_A1","status":"approved","reference":"REF000123","amount":"99",
"currency":"GTQ","externalId":"tu-orden-0001"}'
# 3. Entrega duplicada del aviso 1 → no debe cambiar nada
# 4. Reintentos agotados → revocar acceso
curl -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: $CALLBACK_SECRET" \
-d '{"subscriptionId":"sub_TEST_001","transactionId":"trx_TEST_A2","status":"inactive","plan":"Plan mensual"}'
# 5. Secreto incorrecto → debe responder 401
curl -i -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: INCORRECTO" -d '{"subscriptionId":"x","status":"active"}'
Tu handler pasa la prueba si: (1) da acceso y guarda subscriptionId + nextRenewalDate;
(2) trata el aviso 2 como pago y no pisa la suscripción; (3) el duplicado no cambia nada;
(4) el inactive revoca el acceso; (5) el secreto incorrecto devuelve 401.
Notificaciones por email
Además del callback, Migo le envía emails al cliente final en varios momentos del ciclo:
addPaymentMethod, deletePaymentMethod, cancelSubscription, subPayProblem,
subscriptionSuspended y notifyCardExpiration.
Son notificaciones al tarjetahabiente, no un contrato de integración: no dependas de ellas para tu lógica de negocio.
Relacionado
- Suscripciones — los cuatro estados y cómo consultarlos
- Cobros — qué dispara cada aviso