Escrow holds
Set money aside for someone, then pay it to them or give it back.
A marketplace is the usual case. The buyer pays the marketplace. The marketplace holds the seller’s share until the goods arrive, then pays the seller.
Who a hold can be for
beneficiary |
The money goes to |
|---|---|
{"type": "sub_account", "walletId": "..."} |
Another wallet of your own business. |
{"type": "business", "handle": "kofi-foods"} |
Another iSmartPay business, into its primary wallet. |
{"type": "external", "provider": "mtn", "destination": {"type": "msisdn", "value": "233240000001"}} |
A mobile money number or bank account, sent as a payout. |
- For
external,provideranddestinationwork like they do onPOST /v1/payouts.destination.typeismsisdnoraccount. Cards are not accepted. - Your own handle is
400 own_handle.
How a hold moves
pay out
held ─────────────────────────────────────────► paid_out
│ ▲
│ pay out (external) │ delivered
└──────────────────► paying_out ─────────────────┘
▲ │
└─────── payout failed ───┘ (money is back, hold is held again)
held ── return (you or the beneficiary), or expiry ──► returned
| Status | Meaning |
|---|---|
held |
The money is set aside. Someone still has to decide. |
paying_out |
external only. The payout is on its way. |
paid_out |
The beneficiary has the full amount. Final. |
returned |
The money went back to the wallet it was held from. Final. |
A payout to a wallet inside iSmartPay finishes right away. A payout to mobile money or a bank goes through the normal payout flow. If that payout fails, the money comes back and the hold is held again. It does not retry by itself: pay out again, or return it.
Place a hold
POST /v1/holds
Idempotency-Key: hold-order-2210
{
"reference": "hold-order-2210",
"amount": "250.00",
"currency": "GHS",
"reason": "Order 2210, held until delivery",
"beneficiary": { "type": "business", "handle": "kofi-foods" },
"expiresIn": 604800,
"onExpiry": "return"
}
referenceis yours and unique for each hold. Send the same reference and body again after a timeout and no second hold is placed. A new reference is a new hold.amountmust be above zero.reasonis 1 to 200 characters.walletIdis optional: the wallet the money is held from. The default is your primary wallet. See Wallets and sub-accounts.expiresInis whole seconds, 60 to 7,776,000 (90 days). The default is 86,400 (24 hours).onExpiryisreturn(the default) orpay_out.
The money leaves your wallet’s available balance now, and the hold counts toward your outgoing limits. If the hold cannot be placed, you get an error and nothing is held.
The answer is 202:
{
"id": "a3c1e5f7-2b4d-4968-8a0c-1e3f5a7b9d2c",
"reference": "hold-order-2210",
"status": "held",
"amount": "250.00",
"currency": "GHS",
"reason": "Order 2210, held until delivery",
"beneficiary": { "type": "business", "businessName": "Kofi Foods" },
"expiresAt": "2026-11-09T10:00:00Z",
"onExpiry": "return",
"createdAt": "2026-11-02T10:00:00Z"
}
Holding for a mobile money number or bank account
The payout fee is priced when you place the hold and held with the amount. The beneficiary still gets the full amount.
{
"reference": "hold-order-2211",
"status": "held",
"amount": "250.00",
"fee": "1.50",
"totalHeld": "251.50",
"currency": "GHS",
"beneficiary": {
"type": "external",
"provider": "mtn",
"destination": { "type": "msisdn", "value": "233240000001" },
"accountName": "Ama Mensah"
},
"onExpiry": "return"
}
totalHeldis what left your wallet. A return gives all of it back.accountNameis the name the provider has for the number. Check it before you pay out. Banks don’t return names, so it can be missing.- The destination is checked when you place the hold. An account that is not found or not active is
422 destination_invalid, and nothing is held.
Pay out
POST /v1/holds/hold-order-2210/pay-out
Idempotency-Key: payout-hold-order-2210
Send no body. The full amount goes to the beneficiary. Only the business that placed the hold can pay it out.
For an external beneficiary, the answer is the hold paying_out, with the attempt:
{ "reference": "hold-order-2211", "status": "paying_out", "payout": { "attempt": 1, "status": "accepted" } }
Wait for the hold.status_changed webhook. It says paid_out when the payout is delivered, or held with payout.failureReason when it failed. To try again, call pay-out again with a new Idempotency-Key. That starts attempt 2.
You won’t get payout.* webhooks for a hold’s payout, and it doesn’t show on GET /v1/payouts. The hold is the record.
Return
POST /v1/holds/hold-order-2210/return
Idempotency-Key: return-hold-order-2210
The money goes back to the wallet it was held from. Either side can return a hold. You can’t return one while its payout is paying_out; wait for the result.
Who can do what
| Placing business | Beneficiary business | |
|---|---|---|
| Identifier | The reference it chose |
The hold’s id, from its webhook |
| Read | GET /v1/holds/{reference} |
GET /v1/holds/{id} |
| Pay out | Yes | No |
| Return | POST /v1/holds/{reference}/return |
POST /v1/holds/{id}/return |
A business beneficiary sees the hold with placedBy: { "businessName": "..." } in place of a beneficiary. Its walletId is the wallet the money would land in.
These routes only serve holds with a beneficiary. Any other hold of your business, such as one iSmartPay placed for its own reasons, is 404.
Expiry
When expiresAt passes and nobody has decided, the hold ends the way onExpiry says: return gives the money back, pay_out pays it to the beneficiary. decidedBy is then expiry. After a failed payout, expiry always returns the money.
Pick return unless you want delivery to be taken as agreed when time runs out.
A marketplace example
Kofi Foods sells through a marketplace and has the handle kofi-foods.
- The buyer pays the marketplace with a collection or a hosted checkout.
- The marketplace holds 250.00 for
kofi-foodsfor a week. Kofi Foods gets ahold.status_changedwebhook withstatusheldand ships the order. - The buyer gets the goods. The marketplace pays out, and 250.00 lands in Kofi Foods’ primary wallet.
- If the buyer disputes the order, the marketplace returns the hold instead and refunds the buyer.
If the seller isn’t on iSmartPay, step 2 uses an external beneficiary with the seller’s MoMo number. Step 3 then sends the money to that number.
Webhooks
hold.status_changed is sent each time a hold changes status. It goes to the business that placed the hold and, for a business beneficiary, to that business too.
{
"id": "evt_5c7a9e1b3d2f4a6c8e0b1d3f5a7c9e2b",
"type": "hold.status_changed",
"createdAt": "2026-11-04T14:00:00Z",
"data": {
"id": "a3c1e5f7-2b4d-4968-8a0c-1e3f5a7b9d2c",
"reference": "hold-order-2210",
"status": "paid_out",
"amount": "250.00",
"currency": "GHS",
"reason": "Order 2210, held until delivery",
"placedBy": { "businessName": "Acme Marketplace" },
"onExpiry": "return",
"decidedBy": "payer",
"decidedAt": "2026-11-04T14:00:00Z",
"createdAt": "2026-11-02T10:00:00Z"
}
}
datais the hold as the receiving business would read it. The example is the beneficiary’s view. The placing business seesbeneficiaryinstead ofplacedBy.- The placing business’s copy has no
id,decidedAtorcreatedAt, and the beneficiary’s has nocreatedAt. Read the hold when you need them. - Subscribe an endpoint to the event type in the console. See Webhooks. To catch up on missed events, use
GET /v1/eventswith a key that hasholds.read.
decidedBy says who ended a hold: payer (the business that placed it), beneficiary, expiry or ismartpay.
Permissions
| To | The key needs |
|---|---|
| Place a hold | holds.write |
| Pay out or return a hold | holds.write and holds.read |
| Read a hold | holds.read |
Pay out and return read the hold first, which is why they need holds.read too.
Errors
As well as the common errors:
| Status | Code | What to do |
|---|---|---|
| 400 | own_handle |
You can’t name your own handle as the beneficiary. |
| 400 | invalid_input |
A field is malformed, or expiresIn is outside 60 seconds to 90 days. Read message. |
| 400 | hold_refused |
The hold was refused for another reason. Nothing was held. |
| 403 | holds_not_available |
Holds are sandbox only for now. Use a sandbox key. |
| 403 | forbidden |
The key lacks a permission. See Permissions. |
| 409 | already_decided |
The hold is already paid out, returned or paying out. message says which. Read the hold; don’t retry. |
| 409 | hold_not_held |
The hold is no longer held. Read it to see how it ended. |
| 422 | insufficient_funds |
The wallet has less than the amount (plus the fee for external). Nothing was held. |
| 422 | destination_invalid |
The mobile money or bank account was not found or is not active. Nothing was held. |
| 422 | provider_unavailable |
That provider can’t be used right now. Nothing was held or paid. With 503, try again shortly. |
| 422 | payout_failed |
The payout was refused at once. The hold is held again; pay out again or return it. |
| 422 | beneficiary_unavailable |
The beneficiary can’t receive money right now. When placing, nothing was held. On pay out, the hold stays held. |
| 503 | escrow_unavailable |
Escrow holds are switched off in this environment. Contact support. |
The limit errors, such as daily_limit_exceeded, can also apply. See Errors.