Recurring Payments Overview

Migo's recurring engine is built around three entities:

┌─────────┐  subscribes  ┌──────────────┐  charges  ┌──────────┐
│  Plan   │─────────────►│ Subscription │──────────►│  Charge  │
│         │              │              │           │          │
│ amount  │              │ client       │           │ amount   │
│ period  │              │ cardId       │           │ state    │
│ trial   │              │ status       │           │          │
└─────────┘              └──────────────┘           └──────────┘

• A Plan defines the money: how much, how often, with or without a trial.
• A Subscription binds a plan to a client (cardholder) and a default payment method.
• A Charge is a single billing event — automatic (scheduled) or manual (on-demand).

What gets charged when

Event	Triggered by	Endpoint
Subscription creation	POST /v1/subscriptions/verify-card with shouldCreateSubscription: true (tied to an existing transaction)	Internal
Scheduled charge	Migo crons at the plan's cadence	Automatic
On-demand charge	You call POST /v1/subscriptions/charges (batch intake)	Manual, async
Bulk charges	You call POST /v1/subscriptions/charges/upload-csv	Manual, async

All Middleware API endpoints

Endpoint	Purpose
POST /v1/plans	Create a plan
PUT /v1/plans	Update a plan
GET /v1/plans/list	List plans
GET /v1/plans/{planId}/client/{client}/detail	Plan details for a specific client
PUT /v1/subscriptions	Update a subscription's notification email
GET /v1/subscriptions	List subscriptions (requires userId + clientId)
GET /v1/subscriptions/detail/{subUid}	Detail by subscription id
DELETE /v1/subscriptions/{subUid}	Cancel a subscription
POST /v1/subscriptions/payment-methods	Add a payment method
DELETE /v1/subscriptions/payment-methods	Remove a payment method
PUT /v1/subscriptions/payment-methods/set-default	Change default card
POST /v1/subscriptions/verify-card	Verify a card (and optionally create a subscription)
GET /v1/subscriptions/payment-history	Charge history
POST /v1/subscriptions/charges	On-demand charge (batch intake)
POST /v1/subscriptions/charges/upload-csv	Bulk charges

All calls require Authorization: Bearer <middleware-jwt> — see Authentication.