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

Cancel a hosted checkout

Cancels an open checkout that has no payment in progress; otherwise 409 checkout_not_open. Send a required Idempotency-Key header. Requires the collections.write permission.

POST/v1/checkouts/{checkoutId}/cancel
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
checkoutIdstringrequired

The checkout's id.

matches ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
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
Responses
200

The cancelled 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

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.

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

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 POST 'https://api.example.com/v1/checkouts/string/cancel' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string'
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"
}