Place an escrow hold
Holds money from one of your wallets for a beneficiary: another of your wallets, another iSmartPay business by handle, or a mobile money number or bank account (external). For an external beneficiary the payout fee is priced now and held with the amount (fee, totalHeld), and the destination is checked as a payout’s is: a provider that cannot be used is 422 or 503 provider_unavailable, and an account that is not found or not active is 422 destination_invalid. The money leaves your wallet when the hold is placed, and placing it counts toward your outgoing limits. It stays held until you pay it out, it is returned to the wallet it came from, or it expires and onExpiry decides. Retrying is safe with the same reference: a new reference is a new hold. A hold that cannot be placed is refused and nothing is held: a balance that is too low is 422 insufficient_funds, a business that cannot receive money right now is 422 beneficiary_unavailable, a wallet that is frozen is 422 wallet_frozen, any other refusal is 400 hold_refused, holds switched off in this environment are 503 escrow_unavailable, and the limit refusals apply. Sends hold.status_changed. Requires the holds.write permission. Escrow holds are available in the sandbox only for now; on the live API every holds route answers 403 holds_not_available.
/v1/holdsAuthorizationBearer token (JWT) · headerrequiredA token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.
Idempotency-KeystringrequiredA 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.
application/jsonreferencestringrequiredYour own identifier for this hold, unique for each hold. Sending the same reference and body again does not place a second hold.
amountstringrequiredA decimal string in major units, above zero.
currencystringrequiredreasonstringrequiredWhat the money is held for. The beneficiary sees it.
walletIdstring<uuid>The wallet to hold the money from. Your primary wallet when left out.
beneficiaryHoldBeneficiaryRequestrequiredWho the money is held for: {type: "sub_account", walletId} for another of your wallets, {type: "business", handle} for another iSmartPay business, paid into its primary wallet, or {type: "external", provider, destination} for a mobile money number or bank account, paid out as a payout.
Show propertiesHide properties
typestringrequiredsub_accountbusinessexternalwalletIdstring<uuid>With sub_account only.
handlestringWith business only. Your own handle is refused with 400 own_handle.
providerstringWith external only. The provider the payout goes through, as in POST /v1/payouts.
destinationobjectWith external only. A card is not accepted.
Show propertiesHide properties
typestringrequiredmsisdnaccountvaluestringrequiredThe mobile money number or bank account number.
expiresInintegerSeconds until the hold expires, from 60 to 90 days.
onExpirystringWhat happens at expiry if nobody decided first.
returnpay_outThe hold, held.
idstring<uuid>The hold's id. A beneficiary business reads and returns the hold with it.
referencestringrequiredThe placing business's reference.
statusstringrequiredheld until someone decides. paying_out while a payout to an external beneficiary is on the rail; if it fails, the hold is held again. paid_out and returned are final.
heldpaying_outpaid_outreturnedamountstringrequiredA decimal string in major units.
currencystringrequiredfeestringOn an external hold, the payout fee in major units, priced when the hold is placed. The beneficiary still receives the full amount.
totalHeldstringOn an external hold, amount plus fee: what left your wallet, and what a return gives back.
reasonstringwalletIdstring<uuid>For the placing business, the wallet the money is held from. For the beneficiary, the wallet it would land in.
beneficiaryHoldPartyShown to the placing business. A business beneficiary carries businessName, never an id.
Show propertiesHide properties
typestringsub_accountbusinessexternalwalletIdstring<uuid>businessNamestringThe business's display name, when known.
providerstringOn an external beneficiary.
destinationobjectOn an external beneficiary.
Show propertiesHide properties
typestringrequiredmsisdnaccountvaluestringrequiredThe mobile money number or bank account number.
accountNamestringOn an external beneficiary, the account name the provider returned when the hold was placed. Absent where the rail cannot look names up, as with banks.
payoutobjectOn an external hold once a pay-out has been asked for: the latest payout attempt.
Show propertiesHide properties
attemptintegerstatusstringfailureReasonstringplacedByHoldPartyShown to the beneficiary business instead of beneficiary.
Show propertiesHide properties
typestringsub_accountbusinessexternalwalletIdstring<uuid>businessNamestringThe business's display name, when known.
providerstringOn an external beneficiary.
destinationobjectOn an external beneficiary.
Show propertiesHide properties
typestringrequiredmsisdnaccountvaluestringrequiredThe mobile money number or bank account number.
accountNamestringOn an external beneficiary, the account name the provider returned when the hold was placed. Absent where the rail cannot look names up, as with banks.
expiresAtstring<date-time>onExpirystringreturnpay_outdecidedBystringWho decided a final hold. ismartpay is a decision by iSmartPay support.
payerbeneficiaryexpiryismartpaydecidedAtstring<date-time>createdAtstring<date-time>The request is not valid. message says which field.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The token is missing, expired or not valid. Get a new one from the token endpoint.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Nothing was found with that reference or number. For utilities, product_not_found means no product has that productId.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
idempotency_key_reused: the key was used before with a different body. request_in_flight: a request with this key is still being processed, so retry shortly. duplicate_reference: the reference is already used by a different request, so choose a new one; sending the same body again under a new key replays the first answer.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The purchase cannot be made as asked: product_not_sellable (the product is not on sale now), amount_out_of_range (outside the product's price, min or max), currency_not_supported (only GHS is sold), beneficiary_invalid (the product cannot be sold to this number) or fee_unpriceable (the fee cannot be worked out right now; retry later).
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
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.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA 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.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.