Saltar al contenido principal
Migo Docs

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.

Integración asistida por IA

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>"
El token va crudo

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.


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 URL en mayúsculas. const { url } = response devuelve undefined — 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 tu externalId.

→ 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:

AvisoQué significaCómo lo distingues
Callback de pagoEl cobro se aprobóNo trae subscriptionId
subsCallback activeLa suscripción quedó creadaTrae 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 /transactions con customKeys.plan.uid devuelve 201 y una URL.
  • 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 subsCallback active.
  • GET /api/v1/subscriptions/detail/{subUid} devuelve esa suscripción como active.
  • Un subsCallback inactive revoca 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.