Visión general de Pagos Recurrentes
El motor de recurrencia de Migo se construye alrededor de tres entidades:
┌─────────┐ subscribes ┌──────────────┐ charges ┌──────────┐
│ Plan │─────────────►│ Subscription │──────────►│ Charge │
│ │ │ │ │ │
│ amount │ │ client │ │ amount │
│ period │ │ cardId │ │ state │
│ trial │ │ status │ │ │
└─────────┘ └──────────────┘ └──────────┘
- Un Plan define el dinero: cuánto, cada cuánto, con o sin prueba.
- Una Subscription asocia un plan con un cliente (tarjetahabiente) y un método de pago por defecto.
- Un Charge es un evento de facturación individual — automático (programado) o manual (bajo demanda).
Qué se cobra y cuándo
| Evento | Disparado por | Endpoint |
|---|---|---|
| Creación de suscripción | POST /v1/subscriptions/verify-card con shouldCreateSubscription: true (ligado a una transacción existente) | Interno |
| Cobro programado | Crons de Migo según la cadencia del plan | Automático |
| Cobro bajo demanda | Tú llamas POST /v1/subscriptions/charges (ingesta por lote) | Manual, asíncrono |
| Cobros masivos | Tú llamas POST /v1/subscriptions/charges/upload-csv | Manual, asíncrono |
Todos los endpoints de la Middleware API
| Endpoint | Propósito |
|---|---|
POST /v1/plans | Crea un plan |
PUT /v1/plans | Actualiza un plan |
GET /v1/plans/list | Lista planes |
GET /v1/plans/{planId}/client/{client}/detail | Detalle del plan para un cliente específico |
PUT /v1/subscriptions | Actualiza el email de notificación de una suscripción |
GET /v1/subscriptions | Lista suscripciones (requiere userId + clientId) |
GET /v1/subscriptions/detail/{subUid} | Detalle por id de suscripción |
DELETE /v1/subscriptions/{subUid} | Cancela una suscripción |
POST /v1/subscriptions/payment-methods | Agrega un método de pago |
DELETE /v1/subscriptions/payment-methods | Elimina un método de pago |
PUT /v1/subscriptions/payment-methods/set-default | Cambia la tarjeta por defecto |
POST /v1/subscriptions/verify-card | Verifica una tarjeta (y opcionalmente crea una suscripción) |
GET /v1/subscriptions/payment-history | Historial de cobros |
POST /v1/subscriptions/charges | Cobro bajo demanda (ingesta por lote) |
POST /v1/subscriptions/charges/upload-csv | Cobros masivos |
Todas las llamadas requieren Authorization: Bearer <middleware-jwt> — consulta Autenticación.