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

Create a subscription

Asks a customer to agree once to be charged priceData.amount every priceData.interval, starting on startDate. The subscription starts as incomplete: the customer approves on their phone and it becomes active, or they decline or never answer and it becomes incomplete_expired after 7 days. The first charge must fall in the future. The customer pays the fee on every charge, so fee and totalAmount are fixed when the subscription is created and stay the same for its whole life. The reply is the same whether or not the customer’s number has an iSmartPay account, so it never tells you. Retrying is safe with the same reference and body: you get the same subscription back. The same reference with a different body is 409 idempotency_key_reused. At most 60 are created a minute, and at most 3 open and 10 a day for one customer. Sends subscription.created. Requires the mandates.write permission. Subscriptions are charged on a schedule only once your business is switched on for them; until then this answers 503 provider_unavailable.

POST/v1/subscriptions
Authorization
AuthorizationBearer token (JWT) · headerrequired

A token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.

Header parameters
Idempotency-Keystringrequired

A unique value you generate for this attempt, at most 255 characters. Send the same value when you retry the same request: it is answered once, however many times you send it. Reusing a value with a different body is refused with 409 idempotency_key_reused.

min length 1 · max length 255
Request body
requiredapplication/json
referencestringrequired

Your reference for this subscription. Creating again with the same reference and body returns the same subscription.

matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$
priceDataobjectrequired
Show properties
amountstringrequired

A decimal string in major units, charged every cycle before the fee.

currencystringrequired
intervalstringrequired

How often to charge. A weekly subscription charges on the weekday of startDate. A monthly one charges on its day of the month, and on the last day of shorter months.

Allowed:dayweekmonth
intervalCountinteger

Only 1 is offered: one charge per interval.

default: 1
Allowed:1
customerobjectrequired
Show properties
phonestringrequired

The customer's Ghanaian mobile number, like 0244123456. For a wallet subscription it is the number verified on their iSmartPay account.

networkstring

The customer's network. Required for mobile_money, and not allowed for wallet.

Allowed:mtntelecel
paymentMethodstringrequired

mobile_money charges the customer's mobile money number under an agreement their network holds. wallet charges their iSmartPay wallet, in GHS only.

Allowed:mobile_moneywallet
startDatestring<date>required

The day of the first charge. It must fall in the future.

endDatestring<date>

No charge after this day.

maxCyclesinteger

Stop after this many paid charges.

min 1
billingTimestring

The time of day to charge.

matches ^([01][0-9]|2[0-3]):[0-5][0-9]$ · default: "09:00"
timezonestring
default: "Africa/Accra"
Allowed:Africa/AccraUTC
retryobject
Show properties
afterDaysinteger[]

Days after the due date to try a failed charge again. Only [1], [1, 3], [1, 3, 7] and [] (no retries) are offered. Left out, it is [1, 3, 7].

pastDueBehaviorstring

What happens when every retry of a cycle has failed.

default: "cancel"
Allowed:cancelpausekeep_charging
descriptionstring

Shown to the customer when they approve.

max length 60
Responses
202

The subscription, usually incomplete.

idstringrequired
matches ^sub_[0-9a-f]{32}$
referencestringrequired
statusstringrequired

incomplete: waiting for the customer. incomplete_expired: they declined or never answered; see declineReason. trialing: approved, with the first charge 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 keep_charging. paused: no charges. canceled: see cancelReason. completed: reached endDate or maxCycles.

Allowed:incompleteincomplete_expiredtrialingactivepast_dueunpaidpausedcanceledcompleted
customerobjectrequired
Show properties
phonestringrequired
networkstring
Allowed:mtntelecel
paymentMethodstringrequired
Allowed:mobile_moneywallet
priceDataobjectrequired
Show properties
amountstringrequired

A decimal string in major units.

currencystringrequired
intervalstringrequired
Allowed:dayweekmonth
intervalCountintegerrequired
Allowed:1
feestringrequired

The fee the customer pays on each charge, fixed when the subscription was created. A decimal string in major units.

totalAmountstringrequired

What the customer pays on each charge: priceData.amount plus fee.

startDatestring<date>required
endDatestring<date>
maxCyclesinteger
billingTimestringrequired
timezonestringrequired
retryobjectrequired
Show properties
afterDaysinteger[]
pastDueBehaviorstringrequired
Allowed:cancelpausekeep_charging
descriptionstring
consentobjectrequired

How the customer agrees.

Show properties
channelstringrequired

network: their network asks them to approve. first_charge: the first charge's prompt is the agreement. pin: they approve with their PIN in the iSmartPay app.

Allowed:networkfirst_chargepin
expiresAtstring<date-time>

When the request lapses if the customer has not answered.

consentedAtstring<date-time>
nextChargeAtstring<date-time> | nullrequired

When the next charge is due, or null when none is.

cyclesChargedintegerrequired

How many cycles have been paid.

cancelAtPeriodEndbooleanrequired
cancelAtstring<date-time>

When a subscription set to end at its period end will end.

cancelReasonstring

Present when canceled: you canceled it, the customer canceled the agreement with their network, or iSmartPay did.

Allowed:businessnetworkplatform
declineReasonstring

Present when incomplete_expired.

Allowed:declinedno_response
pausedBystring

Present when paused. platform means iSmartPay stopped charging; contact support.

Allowed:businessplatform
createdAtstring<date-time>required
updatedAtstring<date-time>required
400

The request is not valid. message says which field.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

401

The token is missing, expired or not valid. Get a new one from the token endpoint.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

403

The request was understood and refused. Common causes: the token is not an API credential's (forbidden); the credential is for the other environment (environment_mismatch); it does not have the permission this operation needs (forbidden); a limit was reached (limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit); or iSmartPay has suspended or deactivated the business (business_suspended, business_deactivated). A suspended business's API credentials stop exchanging for tokens, so a request made with a token issued just before the suspension is refused with business_suspended.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

409

idempotency_key_reused: the key was used before with a different body. request_in_flight: a request with this key is still being processed, so retry shortly. duplicate_reference: the reference is already used by a different request, so choose a new one; sending the same body again under a new key replays the first answer.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

422

The purchase cannot be made as asked: product_not_sellable (the product is not on sale now), amount_out_of_range (outside the product's price, min or max), currency_not_supported (only GHS is sold), beneficiary_invalid (the product cannot be sold to this number) or fee_unpriceable (the fee cannot be worked out right now; retry later).

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

429

Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

500

Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

502

A service behind the API did not answer usably. If the request was a POST, retry with the same Idempotency-Key and body. A party lookup the provider rejects is provider_error.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

503

The API is temporarily unable to tell which environment it serves (environment_unknown), utility purchases are not available right now (utilities_unavailable), a settlement destination could not be name-checked just now (destination_verification_unavailable; retry the same request), or hosted checkout is not set up on this deployment (checkout_unavailable). Retry shortly, except for checkout_unavailable, which lasts until the deployment is configured.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

504

The request took too long. If it was a POST, its outcome is unknown: retry with the same Idempotency-Key and body, or read it back by reference. A party lookup the provider does not answer is provider_timeout: check again before relying on it.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

Request
curl -X POST 'https://stgdeveloper-api.ismartghana.com/v1/subscriptions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "reference": "gym-ama-2026-12",
  "priceData": {
    "amount": "150.00",
    "currency": "GHS",
    "interval": "day",
    "intervalCount": 1
  },
  "customer": {
    "phone": "0244123456",
    "network": "mtn"
  },
  "paymentMethod": "mobile_money",
  "startDate": "2026-12-01",
  "endDate": "2019-08-24",
  "maxCycles": 1,
  "billingTime": "09:00",
  "timezone": "Africa/Accra",
  "retry": {
    "afterDays": [
      1,
      3,
      7
    ]
  },
  "pastDueBehavior": "cancel",
  "description": "Gym membership"
}'
Response
{
  "id": "sub_0f1d6a3c7b114a549a3b6f1c2f0e8f6e",
  "reference": "string",
  "status": "incomplete",
  "customer": {
    "phone": "string",
    "network": "mtn"
  },
  "paymentMethod": "mobile_money",
  "priceData": {
    "amount": "150.00",
    "currency": "GHS",
    "interval": "day",
    "intervalCount": 1
  },
  "fee": "2.25",
  "totalAmount": "152.25",
  "startDate": "2019-08-24",
  "endDate": "2019-08-24",
  "maxCycles": 0,
  "billingTime": "09:00",
  "timezone": "Africa/Accra",
  "retry": {
    "afterDays": [
      0
    ]
  },
  "pastDueBehavior": "cancel",
  "description": "string",
  "consent": {
    "channel": "network",
    "expiresAt": "2019-08-24T14:15:22Z",
    "consentedAt": "2019-08-24T14:15:22Z"
  },
  "nextChargeAt": "2019-08-24T14:15:22Z",
  "cyclesCharged": 0,
  "cancelAtPeriodEnd": true,
  "cancelAt": "2019-08-24T14:15:22Z",
  "cancelReason": "business",
  "declineReason": "declined",
  "pausedBy": "business",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}