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

Cancel a payment request

Withdraws a payment request that is still open. It ends failed with failureReason cancelled, and cancelling it again returns the same collection. A request that has already settled, been declined or expired is refused with 409 request_not_open, and a collection on any other provider with 409 not_a_payment_request. A reference that is not yours is 404. Send a required Idempotency-Key header. Requires the collections.write permission.

POST/v1/collections/{reference}/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
referencestringrequired

The reference you chose when you sent the request.

matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$
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 payment request.

referencestringrequired

The reference you chose.

amountstring

The requested amount. A decimal string in major units.

currencystring

Three-letter currency code.

matches ^[A-Z]{3}$
statusstringrequired

Where the request stands, reported as it is: accepted, dispatched, in_review, held, settled, failed or expired. Others can appear, so do not treat this list as closed. A payment request ends failed when the payer declines or you cancel it, and expired when nobody answers in time.

providerstring

The provider used.

feestring

The fee charged. Left out when none was recorded. A decimal string in major units.

feeBearerstring

Who pays the fee. initiator: the party who starts the request pays the amount plus the fee, and the recipient gets the full amount. non_initiator: the fee comes out of what the recipient gets.

Allowed:initiatornon_initiator
payerAmountstring

What the payer is charged. Left out when the fee bearer is not known. A decimal string in major units.

recipientAmountstring

What the recipient receives. Left out when the fee bearer is not known. A decimal string in major units.

notestring

The note you sent.

failureReasonstring

Why it failed. For a payment request: declined, cancelled or expired. For other providers, the provider's own reason when there is one. Left out otherwise.

createdAtstring<date-time>
completedAtstring<date-time>

When it reached its final status. Left out while it is still moving, and on older movements where the time was not recorded.

expiresAtstring<date-time>

Payment requests only. When an open request ends expired. Left out on other collections.

channelstring

How it was started. api is the only value today.

Allowed:api
settlementStatusstring

Where the money stands with settlement: not_eligible, eligible, claimed or settled.

Allowed:not_eligibleeligibleclaimedsettled
reconciliationReconciliation

What the platform's check against the provider concluded.

Show properties
statusstringrequired

unchecked (not checked yet), matched (the provider agrees) or mismatched (the provider disagrees; the platform is looking into it).

Allowed:uncheckedmatchedmismatched
checkedAtstring<date-time>

When it was last checked. Left out until it has been.

parentLineageLink

The movement this one undoes, when it is a reversal. Left out otherwise.

Show properties
typestringrequired

What kind of movement it is.

Allowed:collectionpayoutwallet_transfer
referencestringrequired

Its reference.

compensationLineageLink

The reversal recorded against this movement. Left out when there is none.

Show properties
typestringrequired

What kind of movement it is.

Allowed:collectionpayoutwallet_transfer
referencestringrequired

Its reference.

walletIdstring<uuid>

The wallet the money went into or came out of, when one was named.

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

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.

409

request_not_open (the request already settled, was declined or expired) or not_a_payment_request (the collection is not an ismartpay request).

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 POST 'https://stgdeveloper-api.ismartghana.com/v1/collections/string/cancel' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string'
Response
{
  "reference": "string",
  "amount": "120.00",
  "currency": "GHS",
  "status": "string",
  "provider": "string",
  "fee": "120.00",
  "feeBearer": "initiator",
  "payerAmount": "120.00",
  "recipientAmount": "120.00",
  "note": "string",
  "failureReason": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "completedAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z",
  "channel": "api",
  "settlementStatus": "not_eligible",
  "reconciliation": {
    "status": "unchecked",
    "checkedAt": "2019-08-24T14:15:22Z"
  },
  "parent": {
    "type": "collection",
    "reference": "string"
  },
  "compensation": {
    "type": "collection",
    "reference": "string"
  },
  "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480"
}