Integración en 4 pasos
Todo el flujo recurrente son cuatro pasos, y solo dos son código tuyo. Trabaja en sandbox de principio a fin; el cambio a producción es únicamente cambiar la URL base.
La Guía para agentes de IA es este mismo recorrido en formato determinista, pensado para entregárselo a un asistente de IA.
Antes de empezar
export MIGO_API_BASE="https://sb-mw.migopayments.com" # sandbox
export MIGO_TOKEN="<tu-token-de-comercio>"
export MIGO_CLIENT="<tu-client-slug>"
En POST /transactions el token se envía sin el prefijo Bearer. Las rutas /v1/* sí usan
Authorization: Bearer <token>. Es la diferencia que más tiempo hace perder.
Paso 1 — Crea el plan
El plan define cuánto y cada cuánto. Se crea una vez y lo reutilizas en todas las suscripciones que quieras.
curl -X POST "$MIGO_API_BASE/api/v1/plans" \
-H "Authorization: Bearer $MIGO_TOKEN" -H "Content-Type: application/json" \
-d '{"client":"'"$MIGO_CLIENT"'","plan":{"name":"Plan mensual","amount":99.00,
"currency":"GTQ","type":"interval","methods":["<processor-slug>"],"installments":[1],
"frequency":{"frequency":30,"day":1,"shortDescription":"Mensual",
"longDescription":"Se cobra cada 30 días"},
"autoRenewal":true,"dailyAttempts":3,"daysNotifyExpiringCard":7}}'
Verifica: la respuesta trae el uid del plan. Guárdalo — es lo único que necesitas del paso 1.
→ Contrato completo de campos en Planes.
Paso 2 — Genera el link de pago
Esta es la única llamada que haces por cada venta. El plan viaja dentro de la transacción en
customKeys.plan.uid: esa clave es exactamente lo que convierte un cobro único en una suscripción.
curl -X POST "$MIGO_API_BASE/transactions" \
-H "Authorization: $MIGO_TOKEN" -H "Content-Type: application/json" \
-d '{"amount":99.00,"currency":"GTQ","userId":"cliente@ejemplo.com","channel":"web",
"client":"'"$MIGO_CLIENT"'","externalId":"tu-orden-0001","ads":[],
"customKeys":{"emailTo":"cliente@ejemplo.com","plan":{"uid":"<uid-del-plan>"}}}'
Respuesta (201):
{
"uid": "Ypo5z2zTpLqWoe3eVvZMH",
"reference": "REF000123",
"URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}
Verifica:
- Léelo como
URLen mayúsculas.const { url } = responsedevuelveundefined— es el error más frecuente de esta integración. - Guarda
uid: es el identificador con el que Migo te va a hablar en los callbacks, no tuexternalId.
→ Todos los campos y sus reglas en Link de pago de suscripción.
Paso 3 — Recibe el callback
Tu cliente abre la URL, paga con su tarjeta y Migo crea la suscripción sola. Tú te enteras por
el callback, no por el redirect del navegador.
Implementa tu endpoint antes de hacer el primer pago de prueba, para que el primer aviso tenga dónde aterrizar. Recibirás dos avisos por el primer cobro:
| Aviso | Qué significa | Cómo lo distingues |
|---|---|---|
| Callback de pago | El cobro se aprobó | No trae subscriptionId |
subsCallback active | La suscripción quedó creada | Trae subscriptionId y nextRenewalDate |
Reglas que no puedes saltarte:
- Idempotencia obligatoria. El mismo aviso puede llegar más de una vez; procesarlo dos veces no puede cambiar tu estado.
- Actúa solo sobre
approved. El callback también se dispara en pagos denegados. - Verifica el secreto en cada request antes de leer el cuerpo.
→ Payload, cabeceras y ejemplos de replay en Callback de suscripciones.
Paso 4 — Deja que Migo cobre
No hay paso 4 de tu lado: ya terminaste. En cada vencimiento Migo toma la tarjeta guardada,
cobra y te manda otro subsCallback. Si el cobro falla, reintenta según el plan; si se agotan los
reintentos, la suscripción pasa a inactive y te avisa.
Lo único que te queda es reaccionar al callback: dar o quitar acceso.
→ Cadencia, reintentos e historial en Cobros.
Verificación
Considera la integración terminada cuando:
- Creaste un plan y guardaste su uid.
POST /transactionsconcustomKeys.plan.uiddevuelve201y unaURL.- Tu endpoint de callback rechaza un request con secreto inválido.
- Tu endpoint es idempotente: el mismo aviso dos veces no duplica nada.
- Completaste un pago real en sandbox y recibiste el
subsCallbackactive. GET /api/v1/subscriptions/detail/{subUid}devuelve esa suscripción comoactive.- Un
subsCallbackinactiverevoca el acceso en tu app.
Pasar a producción
Cambia sb-mw.migopayments.com por mw.migopayments.com, usa el token de producción y registra la
URL de callback productiva con Migo. Los planes de sandbox no se migran: vuelve a crearlos.