Suscripciones

Una Subscription asocia un plan con un usuario/cliente y un método de pago por defecto.

Cómo se crea una suscripción

No existe un endpoint público POST /v1/subscriptions. Una suscripción se crea internamente durante la verificación de tarjeta, ligada a una transacción existente.

Para crear una suscripción llamas POST /v1/subscriptions/verify-card con shouldCreateSubscription: true (y un planUid). El flujo verify-card tokeniza la tarjeta, la preautoriza contra la transacción existente, revierte esa autorización y — cuando shouldCreateSubscription está activo — crea la suscripción como parte del mismo flujo.

curl -X POST https://mw.migopayments.com/v1/subscriptions/verify-card \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "<transaction-uid>",
    "processor": "<processor-slug>",
    "cardInfo": { "...": "card data tokenized by the processor" },
    "shouldCreateSubscription": true,
    "planUid": "<plan-uid>"
  }'

Ver Métodos de pago → Verificar una tarjeta para el contrato completo de verify-card.

La función interna createSubscription (invocada por el flujo verify-card, no expuesta como ruta HTTP) recibe:

Campo	Notas
client	Nombre del cliente / tenant
clientId	Identificador del cliente
planUid	Plan al que se va a suscribir
currency	Moneda de la suscripción
trxUid	UID de la transacción de origen
trxId	Id de la transacción de origen
userId	Id de usuario del tarjetahabiente
notificationEmail	Opcional — email para las notificaciones de la suscripción

No existen los campos planId, cardholderId, cardId, externalId, metadata, trialOverrideDays ni startAt.

Estados de la suscripción

Una suscripción tiene exactamente cuatro estados:

Estado	Significado
active	Pagada y al día
cancelled	Cancelada por ti o por el tarjetahabiente
expired	Suscripción de plazo fijo que llegó a su fin
inactive	Se agotaron los reintentos de cobro — la facturación se detuvo

No existe el estado trialing, past_due, unpaid ni paused. Cuando se agotan los reintentos de cobro, la suscripción pasa a inactive.

Obtener una suscripción

curl https://mw.migopayments.com/v1/subscriptions/detail/sub_01HAAA \
  -H "Authorization: Bearer <middleware-jwt>"

Listar suscripciones

GET /v1/subscriptions requiere ambos parámetros de query userId y clientId (devuelve 400 si falta cualquiera). La respuesta es un arreglo sin paginación.

curl "https://mw.migopayments.com/v1/subscriptions?userId=<userId>&clientId=<clientId>" \
  -H "Authorization: Bearer <middleware-jwt>"

Respuesta:

{
  "success": true,
  "message": "subscriptions found",
  "data": [
    { "planName": "Pro Monthly", "uid": "sub_01HAAA", "URL": "https://.../subscriptions/sub_01HAAA" }
  ]
}

No existen filtros status, planId, cardholderId, createdAfter ni createdBefore, ni paginación page / limit.

Actualizar una suscripción

PUT /v1/subscriptions solo actualiza el email de notificación de la suscripción. No cambia el plan, el estado ni el método de pago por defecto.

curl -X PUT https://mw.migopayments.com/v1/subscriptions \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "subUid": "sub_01HAAA",
    "email": "billing@example.com"
  }'

Pausar/reanudar, cambiar de plan y prorratear no están soportados por la API actual.

Cambiar el método de pago por defecto

Usa Métodos de pago → Definir por defecto.

Cancelar una suscripción

curl -X DELETE https://mw.migopayments.com/v1/subscriptions/sub_01HAAA \
  -H "Authorization: Bearer <middleware-jwt>"

La cancelación es inmediata: el estado de la suscripción se define en cancelled. No existen las opciones cancelAt, immediate ni period_end.

Notificaciones

El flujo de suscripción envía notificaciones por email (vía el mecanismo notifyEvent del middleware) y un callback al comercio (subsCallback); no emite un contrato público de webhook saliente con eventos subscription.*.

Los tipos de notificación por email que emiten los flujos de suscripción/cron incluyen: addPaymentMethod, deletePaymentMethod, cancelSubscription, subPayProblem, subscriptionSuspended y notifyCardExpiration.

Eventos como subscription.created, subscription.updated, subscription.trial_ending, subscription.paused, subscription.payment_succeeded y subscription.payment_failed no existen en el código.