List subscriptions
Your business’s subscriptions, newest first. Pass nextAfter as after to read the next page. Requires the mandates.read permission.
/v1/subscriptionsAuthorizationBearer token (JWT) · headerrequiredA token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.
statusstringOnly subscriptions in this state. A trialing subscription is listed under active, and an unpaid one under past_due.
incompleteincomplete_expiredactivepast_duepausedcanceledcompletedlimitintegerHow many to return, 1 to 100. Defaults to 50.
afterstringThe nextAfter of the previous page.
A page of subscriptions.
itemsSubscription[]requiredShow propertiesHide properties
Subscriptionidstringrequiredreferencestringrequiredstatusstringrequiredincomplete: 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.
incompleteincomplete_expiredtrialingactivepast_dueunpaidpausedcanceledcompletedcustomerobjectrequiredShow propertiesHide properties
phonestringrequirednetworkstringmtntelecelpaymentMethodstringrequiredmobile_moneywalletpriceDataobjectrequiredShow propertiesHide properties
amountstringrequiredA decimal string in major units.
currencystringrequiredintervalstringrequireddayweekmonthintervalCountintegerrequired1feestringrequiredThe fee the customer pays on each charge, fixed when the subscription was created. A decimal string in major units.
totalAmountstringrequiredWhat the customer pays on each charge: priceData.amount plus fee.
startDatestring<date>requiredendDatestring<date>maxCyclesintegerbillingTimestringrequiredtimezonestringrequiredretryobjectrequiredShow propertiesHide properties
afterDaysinteger[]pastDueBehaviorstringrequiredcancelpausekeep_chargingdescriptionstringconsentobjectrequiredHow the customer agrees.
Show propertiesHide properties
channelstringrequirednetwork: 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.
networkfirst_chargepinexpiresAtstring<date-time>When the request lapses if the customer has not answered.
consentedAtstring<date-time>nextChargeAtstring<date-time> | nullrequiredWhen the next charge is due, or null when none is.
cyclesChargedintegerrequiredHow many cycles have been paid.
cancelAtPeriodEndbooleanrequiredcancelAtstring<date-time>When a subscription set to end at its period end will end.
cancelReasonstringPresent when canceled: you canceled it, the customer canceled the agreement with their network, or iSmartPay did.
businessnetworkplatformdeclineReasonstringPresent when incomplete_expired.
declinedno_responsepausedBystringPresent when paused. platform means iSmartPay stopped charging; contact support.
businessplatformcreatedAtstring<date-time>requiredupdatedAtstring<date-time>requirednextAfterstringPass as after to read the next page. Absent on the last page.
The request is not valid. message says which field.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The token is missing, expired or not valid. Get a new one from the token endpoint.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.