Create a hosted checkout

Creates a payment link your customer opens to pay you by mobile money. Use amountType fixed with amount, or open with optional minAmount, maxAmount and up to four suggestedAmounts. usage single closes after one payment; reusable stays open. Share the returned url: it carries a secret, so send it only to the payer. The checkout becomes paid only when the payment succeeds. Hosted checkout must be turned on by a business owner first and needs verification tier 2. Send a required Idempotency-Key header. Requires the collections.write permission.

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

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

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

amountTypestring

default: "fixed"

Allowed:fixedopen

amountstring | null

Required for fixed amount checkouts and omitted or null for open amount checkouts.

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

minAmountstring | null

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

maxAmountstring | null

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

suggestedAmountsstring[]

min items 0 · max items 4

usagestring

default: "single"

Allowed:singlereusable

currencystringrequired

descriptionstring

max length 140

environmentstring

Optional test or live. Omit it to use this API's environment; a different one returns 422 environment_mismatch.

Allowed:testlive

successUrlstring<uri>

max length 2048

cancelUrlstring<uri>

max length 2048

expiresInMinutesinteger | null

For single checkouts, 5 to 10080, default 60, and null is rejected. For reusable checkouts, 5 to 525600 or null/omitted for no expiry.

Show properties

One of:

integer

integer

null

null

Responses

201

The 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}$

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

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

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

messagestringrequired

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

409

checkout_not_enabled (an owner has not turned on hosted checkout), checkout_not_open, checkout_reference_taken or idempotency_key_reused.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

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

422

environment_mismatch: the environment you sent is not this API's.

errorobjectrequired

Show properties

codestringrequired

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

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

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

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

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

messagestringrequired

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

Request

curl -X POST 'https://api.example.com/v1/checkouts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "reference": "string",
  "amountType": "open",
  "amount": "string",
  "minAmount": "string",
  "maxAmount": "string",
  "suggestedAmounts": [
    "string"
  ],
  "usage": "single",
  "currency": "GHS",
  "description": "string",
  "environment": "test",
  "successUrl": "http://example.com",
  "cancelUrl": "http://example.com",
  "expiresInMinutes": 5
}'

const response = await fetch("https://api.example.com/v1/checkouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: "{\n  \"reference\": \"string\",\n  \"amountType\": \"open\",\n  \"amount\": \"string\",\n  \"minAmount\": \"string\",\n  \"maxAmount\": \"string\",\n  \"suggestedAmounts\": [\n    \"string\"\n  ],\n  \"usage\": \"single\",\n  \"currency\": \"GHS\",\n  \"description\": \"string\",\n  \"environment\": \"test\",\n  \"successUrl\": \"http://example.com\",\n  \"cancelUrl\": \"http://example.com\",\n  \"expiresInMinutes\": 5\n}"
});

import requests

response = requests.post(
    "https://api.example.com/v1/checkouts",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    data="{\n  \"reference\": \"string\",\n  \"amountType\": \"open\",\n  \"amount\": \"string\",\n  \"minAmount\": \"string\",\n  \"maxAmount\": \"string\",\n  \"suggestedAmounts\": [\n    \"string\"\n  ],\n  \"usage\": \"single\",\n  \"currency\": \"GHS\",\n  \"description\": \"string\",\n  \"environment\": \"test\",\n  \"successUrl\": \"http://example.com\",\n  \"cancelUrl\": \"http://example.com\",\n  \"expiresInMinutes\": 5\n}",
)

Response

{
  "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"
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}