Saltar al contenido principal
Migo Docs

Planes

Un Plan es una configuración de precios reutilizable a lo largo de varias suscripciones. Créalo una vez y suscribe a muchos tarjetahabientes a él.

Tipos de plan (enum type)​

El middleware de Migo modela la recurrencia con cuatro valores de type — ellos deciden cómo Migo calcula la siguiente fecha de cobro. Envía el valor en camelCase y minúsculas (el ejemplo del spec muestra la llave del enum en mayúsculas, pero el runtime solo acepta los valores que se muestran abajo):

Llave del enumValor de la API (type)SignificadoCuándo usarlo
INTERVAL"interval"Cobra cada N días desde la fecha ancla de la suscripciónEl más común — semanal, cada 30 días, cada 90 días
FIXED_DAY"fixedDay"Cobra en un día específico del mesFacturación "el 1 del mes" o "el 15 de cada mes"
ANNIVERSARY"anniversary"Cobra el mismo día del calendario en cada ciclo (maneja la diferencia en la duración de los meses)Suscripciones anuales, facturación por aniversario
AUTOMATIC"automatic"Migo delega el cálculo del siguiente cobro al procesador (legacy/manual)Raro; solo para procesadores con su propio scheduler

Fuente de verdad: libs/mongo-database/src/lib/enums/plan.enum.ts.

Crear un plan​

curl -X POST https://mw.migopayments.com/v1/plans \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": {
      "name": "Pro Monthly",
      "amount": 29.99,
      "currency": "USD",
      "type": "interval",
      "frequency": {
        "frequency": 30,
        "day": 1,
        "shortDescription": "Monthly",
        "longDescription": "Charged every 30 days"
      },
      "methods": ["fac-2", "visa-cybersource"],
      "installments": [1],
      "autoRenewal": true,
      "dailyAttempts": 3,
      "daysNotifyExpiringCard": 7
    },
    "client": "client_abc123"
  }'
CampoTipoRequeridoNotas
plan.namestring✅Aparece en los estados de cuenta del tarjetahabiente
plan.amountnumber✅Decimal, hasta 4 posiciones
plan.currencyISO 4217✅GTQ, USD, etc.
plan.typeenum—"interval" | "fixedDay" | "anniversary" | "automatic". No requerido por la validación; fixedDay solo exige frequency > 30
plan.frequency.frequencyinteger✅Días entre cobros (lo usa interval); 0 para fixedDay
plan.frequency.day1–28—Día del mes, solo relevante para planes fixedDay; no requerido por la validación
plan.frequency.shortDescriptionstring✅Etiqueta de cadencia de una palabra (p. ej. Monthly)
plan.frequency.longDescriptionstring✅Descripción completa de la cadencia
plan.methodsstring[]✅Procesadores permitidos para los cobros
plan.installmentsnumber[]✅Números de cuotas permitidas ([1] para pago único)
plan.autoRenewalboolean✅Si Migo programa el siguiente cobro automáticamente
plan.dailyAttemptsinteger✅Reintentos por día en cobros fallidos
plan.daysNotifyExpiringCardinteger✅Días previos al vencimiento de la tarjeta para notificar al tarjetahabiente
clientstring✅Slug del cliente del comercio

Los campos interval/intervalCount que usan otras plataformas de facturación no aplican aquí — Migo deriva la cadencia de type + frequency.frequency + frequency.day.

Listar planes​

curl "https://mw.migopayments.com/v1/plans/list?client=client_abc123" \
  -H "Authorization: Bearer <middleware-jwt>"

Obtener detalle del plan para un cliente específico​

curl "https://mw.migopayments.com/v1/plans/{planId}/client/{client}/detail" \
  -H "Authorization: Bearer <middleware-jwt>"

Devuelve el plan más los overrides específicos del cliente (conversión de moneda, nombre localizado, etc.) y la próxima fecha de cobro calculada contra el timezone del comercio.

Actualizar un plan​

curl -X PUT https://mw.migopayments.com/v1/plans \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "client_abc123",
    "planId": "pln_01HXXX",
    "plan": {
      "name": "Pro Monthly",
      "amount": 34.99
    }
  }'

Los campos a actualizar deben anidarse bajo un objeto plan, y ese objeto debe llevar el name del plan (el handler lee body.plan.name). Enviar amount en el nivel superior no tiene efecto.

aviso

Actualizar el amount o la frequency de un plan no modifica las suscripciones existentes — siguen con su precio/cadencia original. La API no soporta cambiar el plan de una suscripción, por lo que migrar las suscripciones existentes al nuevo precio requiere crear nuevas suscripciones (vía el flujo verify-card).

Versionado​

No puedes eliminar un plan que tenga suscripciones activas. En su lugar, crea un nuevo plan y migra las suscripciones. Esto preserva la precisión histórica de la facturación.

Relacionado​