Skip to content
iSmartPay Developers
Esc
↑↓navigate↵open⌘Jpreview

List hosted checkouts

Returns your checkouts in this environment, newest first. Pass nextCursor back unchanged as cursor for the next page. Requires the collections.read permission.

GET/v1/checkouts
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.

Query parameters
statusstring

Only checkouts with this status.

Allowed:openpaidexpiredcancelled
limitinteger

How many to return, 1 to 50. Defaults to 20.

min 1 · max 50
cursorstring

The nextCursor of the previous page.

Responses
200

A page of checkouts.

itemsCheckout[]required
Show properties
Array of Checkout
idstring<uuid>required
referencestringrequired
amountstring | nullrequired
matches ^\d+\.\d{2}$
currencystringrequired
descriptionstring
environmentstringrequired
Allowed:testlive
statusstringrequired

Reusable checkouts stay open after settlement and never have paid status.

Allowed:openpaidexpiredcancelled
urlstring<uri>required

Contains the public bearer token for this checkout.

successUrlstring<uri>
cancelUrlstring<uri>
expiresAtstring<date-time> | nullrequired
paidAtstring<date-time> | nullrequired
collectionReferencestring | nullrequired
attemptsCheckoutAttempt[]

Present only on the single-checkout read.

Show properties
Array of CheckoutAttempt
collectionReferencestringrequired
providerstringrequired
payerstringrequired

Masked phone number.

statusstringrequired
Allowed:pendingsucceededfailed
failureReasonstring
createdAtstring<date-time>required
amountstringrequired
matches ^\d+\.\d{2}$
createdAtstring<date-time>required
amountTypestringrequired
Allowed:fixedopen
minAmountstring | nullrequired
matches ^\d+\.\d{2}$
maxAmountstring | nullrequired
matches ^\d+\.\d{2}$
suggestedAmountsstring[]required
usagestringrequired
Allowed:singlereusable
paymentsCountintegerrequired
min 0
totalCollectedstringrequired

Settled payments only.

matches ^\d+\.\d{2}$
nextCursorstringrequired

Opaque cursor; empty when there is no next page.

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, 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, 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); 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, 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, 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, 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, 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, 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, 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, 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://api.example.com/v1/checkouts' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "reference": "string",
      "amount": "string",
      "currency": "GHS",
      "description": "string",
      "environment": "test",
      "status": "open",
      "url": "http://example.com",
      "successUrl": "http://example.com",
      "cancelUrl": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "paidAt": "2019-08-24T14:15:22Z",
      "collectionReference": "string",
      "attempts": [
        {
          "collectionReference": "string",
          "provider": "string",
          "payer": "string",
          "status": "pending",
          "failureReason": "string",
          "createdAt": "2019-08-24T14:15:22Z",
          "amount": "string"
        }
      ],
      "createdAt": "2019-08-24T14:15:22Z",
      "amountType": "fixed",
      "minAmount": "string",
      "maxAmount": "string",
      "suggestedAmounts": [
        "string"
      ],
      "usage": "single",
      "paymentsCount": 0,
      "totalCollected": "string"
    }
  ],
  "nextCursor": "string"
}