Skip to content
iSmartPayDevelopers
Esc
↑↓navigate↵open⌘Jpreview
On this page

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"
}
  • reference is 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 is 409 idempotency_key_reused.
  • priceData.interval is day, week or month. A weekly subscription charges on the weekday of startDate. A monthly one charges on that day of the month, and on the last day of shorter months.
  • paymentMethod is mobile_money or wallet. For mobile money, customer.network is mtn or telecel. For a wallet, leave it out; customer.phone is the number verified on the customer’s iSmartPay account, and wallets charge in GHS only.
  • startDate is the day of the first charge. It must be in the future.
  • endDate and maxCycles both stop the subscription. Use either or both.
  • retry.afterDays is [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.
  • pastDueBehavior is what happens when every retry of a cycle has failed: cancel (the default), pause or keep_charging.
  • description is 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.

Was this page helpful?