Subscriptions
Charge a customer the same amount on a schedule, after they agree once.
A gym, a newsletter or a loan repayment is the usual case. You create the subscription when the customer signs up. We take the money on each due date.
Why use subscriptions
- Ask once, charge every time. The customer agrees one time. After that, each charge needs nothing from them: no prompt to answer, and no reminder for you to send on the 1st.
- Their phone, their network. MTN and Telecel customers approve on their own network. Wallet customers approve with their PIN in the iSmartPay app.
- Failed charges try again. A charge that fails for a reason that can fix itself, like a low balance, is tried again after 1, 3 and 7 days. You choose how many tries, and what happens if every one fails.
- Paid like any other collection. A paid charge is your money. It shows in your wallet and settles on your usual schedule.
- Test months in minutes. The sandbox clock runs the next charge on demand, so you can watch a whole year of billing before you go live.
Your business has to be switched on for subscriptions. Until it is, creating one answers 503 provider_unavailable. Start in the sandbox. Keys need the mandates.write permission to change subscriptions and mandates.read to read them.
Create a subscription
POST /v1/subscriptions
Idempotency-Key: gym-ama-2026-12
{
"reference": "gym-ama-2026-12",
"priceData": { "amount": "150.00", "currency": "GHS", "interval": "month" },
"customer": { "phone": "0244123456", "network": "mtn" },
"paymentMethod": "mobile_money",
"startDate": "2026-12-01",
"billingTime": "09:00",
"maxCycles": 12,
"retry": { "afterDays": [1, 3, 7] },
"pastDueBehavior": "cancel",
"description": "Gym membership"
}
referenceis yours, and unique for each subscription. Send the same reference and body again after a timeout and you get the same subscription back. A different body with the same reference is409 idempotency_key_reused.priceData.intervalisday,weekormonth. A weekly subscription charges on the weekday ofstartDate. A monthly one charges on that day of the month, and on the last day of shorter months.paymentMethodismobile_moneyorwallet. For mobile money,customer.networkismtnortelecel. For a wallet, leave it out;customer.phoneis the number verified on the customer’s iSmartPay account, and wallets charge in GHS only.startDateis the day of the first charge. It must be in the future.endDateandmaxCyclesboth stop the subscription. Use either or both.retry.afterDaysis[1, 3, 7]by default. You can send a shorter list that starts the same way ([1],[1, 3]) or[]for no retries. Other days are not offered yet.pastDueBehavioris what happens when every retry of a cycle has failed:cancel(the default),pauseorkeep_charging.descriptionis shown to the customer when they approve, up to 60 characters.
The customer pays the fee on every charge. It is fixed when you create the subscription and never changes, so fee and totalAmount in the answer are what they pay each time.
The answer is 202:
{
"id": "sub_0f1d6a3c7b114a549a3b6f1c2f0e8f6e",
"reference": "gym-ama-2026-12",
"status": "incomplete",
"customer": { "phone": "0244123456", "network": "mtn" },
"paymentMethod": "mobile_money",
"priceData": { "amount": "150.00", "currency": "GHS", "interval": "month", "intervalCount": 1 },
"fee": "2.25",
"totalAmount": "152.25",
"consent": { "channel": "network", "expiresAt": "2026-11-23T09:00:00Z" },
"nextChargeAt": "2026-12-01T09:00:00Z",
"cyclesCharged": 0,
"cancelAtPeriodEnd": false
}
The values above only show the shape. The answer is the same whether or not the customer’s number has an iSmartPay account, so it never tells you.
How the customer agrees
| Payment method | The customer |
|---|---|
| MTN | Gets MTN’s own approval prompt with your business name, the amount and how often, and approves with their MoMo PIN. |
| Telecel | Pays the first charge as a normal Telecel prompt on startDate. Paying it is the agreement. |
| Wallet | Approves in the iSmartPay app with their PIN. |
A subscription nobody answers becomes incomplete_expired after 7 days. The customer can also decline. declineReason says which.
Statuses
status |
Meaning |
|---|---|
incomplete |
Waiting for the customer. |
incomplete_expired |
They declined or never answered. See declineReason. |
trialing |
Approved, and the first charge is still to come. |
active |
Charging on schedule. |
past_due |
Every retry of a cycle failed. pastDueBehavior says what happens next. |
unpaid |
Past due, with pastDueBehavior set to keep_charging. Only the GET shows unpaid; the webhook says past_due. |
paused |
No charges. pausedBy is platform when iSmartPay stopped them. Contact support. |
canceled |
Ended. cancelReason is business, network (the customer canceled with their network) or platform. |
completed |
Reached endDate or maxCycles. |
Read, pause, resume and cancel
GET /v1/subscriptions?status=active&limit=50
GET /v1/subscriptions/{id}
GET /v1/subscriptions/{id}/charges
POST /v1/subscriptions/{id}/pause
POST /v1/subscriptions/{id}/resume
POST /v1/subscriptions/{id}/cancel
Pause, resume and cancel need an Idempotency-Key. Pausing stops charging and leaves the customer’s agreement in place, so resuming needs nothing from them. Cancel ends it now. Send {"atPeriodEnd": true} to let it stay until the next cycle that is not already being charged, then end. It shows cancelAtPeriodEnd and cancelAt until then. A subscription that cannot make the change, such as pausing a canceled one, is 409 mandate_not_open.
GET .../charges lists every attempt with its cycle, status and, for a failed one, failureReason and nextAttemptAt. A charge is paid, failed (it will be tried again), uncollectible (no more tries this cycle), void or missed. A cycle that fell more than a day behind is skipped and shown as missed. We never charge twice to catch up.
Webhooks
| Event | When |
|---|---|
subscription.created |
A subscription was created and the customer has been asked. |
subscription.status_changed |
The status changed, or you set a cancel for the period end. It carries previousStatus. |
subscription.charge_upcoming |
A charge is due within three days. |
subscription.charge_succeeded |
A charge was paid. |
subscription.charge_failed |
An attempt failed. nextAttemptAt is null when the cycle has no more attempts. |
Keys need mandates.read to see them in GET /v1/events. An existing endpoint starts receiving them after you edit it once in the console. See Webhooks.
Test in the sandbox
POST /v1/test-helpers/subscriptions/{id}/advance with {"to": "next_charge"} runs the next reminder, charge or retry now, as if the time had come. Send a timestamp instead to run everything due by then. The sandbox outcome numbers decide whether the charge succeeds. On the live API this answers 404.
The console
The console lists your subscriptions, shows each one’s charges, and lets owners and admins pause, resume and cancel. It cannot create one; that is done with the API.