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.
POST /api/v1/subscriptionsLa 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.
Crear el link
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": []
}'
BearerEn esta ruta el token se envía crudo: Authorization: <token>. Las rutas /v1/* (planes,
suscripciones) sí llevan Authorization: Bearer <token>.
Campos
| Campo | Requerido | Notas |
|---|---|---|
amount | Sí | 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. |
currency | No | GTQ (por defecto) o USD. Envíalo explícito; si lo omites, Migo toma la primera moneda configurada para tu comercio. |
userId | Sí | Identificador de tu cliente final, normalmente su email. Debe ser estable: la suscripción queda atada a este valor. |
channel | Sí | wa | sms | email | web | app |
client | Sí | Tu slug de comercio |
externalId | No | Tu id de orden. Vuelve en los callbacks: es como concilias. Usa uno único por venta. |
customKeys.plan.uid | Sí (suscripción) | La clave que dispara la creación de la suscripción. Omítela por completo para un cobro único. |
customKeys.emailTo | No | Email para el comprobante de pago |
customKeys.automaticRedirect | No | URLs de retorno del navegador por estado. Si la envías, pisa la configurada en tu cuenta. Es solo UX — no sustituye al callback. |
ads | Sí | Envía siempre [] |
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"
}
| Campo | Para qué |
|---|---|
URL | El checkout. En mayúsculas — response.URL, nunca response.url. |
uid | El identificador de la transacción del lado de Migo. Guárdalo: es el que aparece en los callbacks. |
reference | Referencia legible del cobro |
uid que devuelve MigoLos 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.
Un uso por link
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
| HTTP | error.code | Causa | Qué hacer |
|---|---|---|---|
401 | — | Token inválido o ausente | Verifica que sea el token del entorno correcto y que vaya sin Bearer |
409 | 5000 | Falta un campo requerido o tiene el tipo equivocado | Revisa amount, userId, channel, client |
409 | 5004 | El client no existe | Confirma tu slug; pide a Migo que lo active en sandbox |
409 | 2003 | amount fuera del mínimo/máximo configurado | Ajusta el importe |
400 | 2004 / 2005 / 2006 | Cliente final bloqueado, suspendido o excluido | Usa otro userId |
Catálogo completo en Catálogo de errores.
Relacionado
- Callback de suscripciones — cómo te enteras del resultado
- Planes — de dónde sale el
uiddel plan - Webview hospedado — cómo personalizar el checkout