Saltar al contenido principal
Migo Docs

Link de pago de suscripción

Un link de pago de suscripción es una transacción normal con un plan adentro. Migo devuelve una URL de checkout hospedada que puedes enviar por email, WhatsApp o SMS, o incrustar en tu app.

Cuando tu cliente paga en esa URL y el pago se aprueba, Migo crea la suscripción automáticamente y guarda la tarjeta para los cobros siguientes.

No existe un POST /api/v1/subscriptions

La suscripción no se crea con una llamada propia: nace del pago. La única diferencia entre un cobro único y una suscripción es la presencia de customKeys.plan.uid en la transacción.

curl -X POST https://sb-mw.migopayments.com/transactions \
-H "Authorization: <tu-token-de-comercio>" \
-H "Content-Type: application/json" \
-d '{
"amount": 99.00,
"currency": "GTQ",
"userId": "cliente@ejemplo.com",
"channel": "web",
"client": "<tu-client-slug>",
"externalId": "tu-orden-0001",
"customKeys": {
"emailTo": "cliente@ejemplo.com",
"plan": { "uid": "<uid-del-plan>" },
"automaticRedirect": {
"approved": { "url": "https://tu-app.example.com/checkout?estado=aprobado" },
"denied": { "url": "https://tu-app.example.com/checkout?estado=denegado" },
"expired": { "url": "https://tu-app.example.com/checkout?estado=expirado" },
"cancelled": { "url": "https://tu-app.example.com/checkout?estado=cancelado" }
}
},
"ads": []
}'
El token va sin Bearer

En esta ruta el token se envía crudo: Authorization: <token>. Las rutas /v1/* (planes, suscripciones) sí llevan Authorization: Bearer <token>.

Campos​

CampoRequeridoNotas
amountSíImporte real en unidades mayores, como número JSON — 99 o 99.50. No multipliques por 100. Es el primer cobro; las renovaciones usan el importe del plan.
currencyNoGTQ (por defecto) o USD. Envíalo explícito; si lo omites, Migo toma la primera moneda configurada para tu comercio.
userIdSíIdentificador de tu cliente final, normalmente su email. Debe ser estable: la suscripción queda atada a este valor.
channelSíwa | sms | email | web | app
clientSíTu slug de comercio
externalIdNoTu id de orden. Vuelve en los callbacks: es como concilias. Usa uno único por venta.
customKeys.plan.uidSí (suscripción)La clave que dispara la creación de la suscripción. Omítela por completo para un cobro único.
customKeys.emailToNoEmail para el comprobante de pago
customKeys.automaticRedirectNoURLs de retorno del navegador por estado. Si la envías, pisa la configurada en tu cuenta. Es solo UX — no sustituye al callback.
adsSíEnvía siempre []
Ruta exacta de la clave

Es customKeys.plan.uid. No subscriptionData, no planUid en el nivel superior. Una clave mal ubicada produce un cobro único perfectamente válido y ninguna suscripción — sin ningún error.

Respuesta​

201 Created (trata cualquier 2xx como éxito):

{
"uid": "Ypo5z2zTpLqWoe3eVvZMH",
"reference": "REF000123",
"URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}
CampoPara qué
URLEl checkout. En mayúsculas — response.URL, nunca response.url.
uidEl identificador de la transacción del lado de Migo. Guárdalo: es el que aparece en los callbacks.
referenceReferencia legible del cobro
Guarda el uid que devuelve Migo

Los callbacks llegan con este uid, no con tu externalId. Si buscas en tu base por tu propio id interno, no vas a encontrar nada y ninguna suscripción se dará de alta — aunque todo lo demás funcione.

Sobre el importe del primer cobro​

El amount que mandas aquí es lo que se cobra ahora. Las renovaciones siguientes usan el importe del plan, no este. Eso te permite cobrar una primera cuota distinta (promoción, prorrateo manual) sin tocar el plan.

Cada transacción es una intención de pago individual y de un solo uso: se paga, expira o se cancela. Para suscribir a otro cliente, crea otra transacción. No es una URL compartible reutilizable.

Errores​

HTTPerror.codeCausaQué hacer
401—Token inválido o ausenteVerifica que sea el token del entorno correcto y que vaya sin Bearer
4095000Falta un campo requerido o tiene el tipo equivocadoRevisa amount, userId, channel, client
4095004El client no existeConfirma tu slug; pide a Migo que lo active en sandbox
4092003amount fuera del mínimo/máximo configuradoAjusta el importe
4002004 / 2005 / 2006Cliente final bloqueado, suspendido o excluidoUsa otro userId

Catálogo completo en Catálogo de errores.

Relacionado​