Métodos de Pago

Cada suscripción tiene un método de pago por defecto más cualquier número de métodos adicionales registrados. Los cobros programados intentan primero con el por defecto y caen a los otros métodos en caso de falla.

Verificar una tarjeta

Antes de adjuntar una tarjeta o crear una suscripción, la tarjeta se verifica contra una transacción existente.

POST /v1/subscriptions/verify-card requiere transactionUid, processor y cardInfo. Tokeniza la tarjeta a través del procesador, la preautoriza contra la transacción y luego revierte esa autorización. Opcionalmente, con shouldCreateSubscription: true (y planUid), también 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": false,
    "planUid": "<plan-uid>"
  }'

No existe un body { cardId, currency }, ni un auth-and-void fijo de $1, ni una forma de respuesta valid: true. El handler devuelve { success, message, data }.

Agregar un método de pago

POST /v1/subscriptions/payment-methods normalmente se invoca internamente después de verify-card. Su body anida los datos de la tarjeta bajo tokenizeData:

curl -X POST https://mw.migopayments.com/v1/subscriptions/payment-methods \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenizeData": {
      "userId": "<userId>",
      "clientId": "<clientId>",
      "processorId": "<processorId>",
      "cardId": "<cardId>",
      "alias": "Visa ending 4242"
    }
  }'

La respuesta es { success, message, data }. No existen entradas subUid ni isDefault, ni campos de respuesta cardLast4 / brand / addedAt.

Definir una tarjeta diferente como por defecto

curl -X PUT https://mw.migopayments.com/v1/subscriptions/payment-methods/set-default \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "<userId>",
    "clientId": "<clientId>",
    "subscriptionId": "sub_01HAAA",
    "paymentMethodId": "pm_01HBBB"
  }'

Los cuatro campos (userId, clientId, subscriptionId, paymentMethodId) son requeridos.

Eliminar un método de pago

DELETE /v1/subscriptions/payment-methods requiere ambos parámetros de query methodId y subId (devuelve 400 si falta cualquiera).

curl -X DELETE "https://mw.migopayments.com/v1/subscriptions/payment-methods?methodId=pm_01HBBB&subId=sub_01HAAA" \
  -H "Authorization: Bearer <middleware-jwt>"

aviso

No puedes eliminar el método de pago por defecto de una suscripción activa. Define primero un nuevo por defecto y luego elimina el anterior.

Comportamiento de failover

Cuando un cobro programado falla en el método por defecto:

1. Migo itera los demás métodos de pago registrados (en el orden que devuelve el almacén de métodos de pago) e intenta cada uno.
2. Gana el primer éxito; la suscripción se mantiene en active.
3. Si todos los métodos fallan y se agotan los reintentos, la suscripción pasa a inactive.

El comportamiento de reintentos se gobierna por plan mediante dailyAttempts / intervalAttempt (más graceDays opcional) — ver Cobros programados → Calendario de reintentos.

Notificaciones de tarjeta por vencer

No existe una integración con Account Updater en este código. El manejo del vencimiento de tarjetas se limita a una notificación por email: el cron de suscripciones emite un evento notifyCardExpiration antes del vencimiento de una tarjeta (la ventana se configura por plan vía daysNotifyExpiringCard). No existe rotación silenciosa de PAN/vencimiento ni un evento subscription.payment_method.updated.