Saltar al contenido principal
Migo Docs

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.

El redirect del navegador no es una confirmación

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:

AvisoTrae subscriptionIdQué hacer
Resultado del pagoNoTrátalo como un pago puntual
subsCallbackSí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)"
}
CampoNotas
subscriptionIdEl identificador de la suscripción. Es lo que distingue este aviso del de pago.
transactionIdLa transacción que originó el cobro
statusactive o inactive
nextRenewalDateNo es ISO 8601. Es un Date.toString() de JavaScript — parséalo con una librería tolerante, no con Date.parse estricto.
amountNúmero en el subsCallback; string en el callback de pago. No asumas el mismo tipo en ambos.

Estados que llegan por callback​

statusCuándo
activeAlta de la suscripción y cada renovación cobrada con éxito
inactiveSe agotaron los reintentos de cobro — deja de facturar y revoca el acceso
cancelled y expired no se notifican

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

Pide que la plantilla incluya los identificadores

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​