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

Get a subscription

One subscription with its current status. Another business’s subscription is the same 404 as one that does not exist. Requires the mandates.read permission.

GET/v1/subscriptions/{id}
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.

Path parameters
idstringrequired

The subscription's id, like sub_0f1d6a3c7b114a549a3b6f1c2f0e8f6e.

matches ^sub_[0-9a-f]{32}$
Responses
200

The subscription.

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
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.

404

Nothing was found with that reference or number. For utilities, product_not_found means no product has that productId.

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 GET 'https://stgdeveloper-api.ismartghana.com/v1/subscriptions/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
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"
}