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

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, provider and destination work like they do on POST /v1/payouts. destination.type is msisdn or account. 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"
}
  • reference is 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.
  • amount must be above zero. reason is 1 to 200 characters.
  • walletId is optional: the wallet the money is held from. The default is your primary wallet. See Wallets and sub-accounts.
  • expiresIn is whole seconds, 60 to 7,776,000 (90 days). The default is 86,400 (24 hours).
  • onExpiry is return (the default) or pay_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"
}
  • totalHeld is what left your wallet. A return gives all of it back.
  • accountName is 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.

  1. The buyer pays the marketplace with a collection or a hosted checkout.
  2. The marketplace holds 250.00 for kofi-foods for a week. Kofi Foods gets a hold.status_changed webhook with status held and ships the order.
  3. The buyer gets the goods. The marketplace pays out, and 250.00 lands in Kofi Foods’ primary wallet.
  4. 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"
  }
}
  • data is the hold as the receiving business would read it. The example is the beneficiary’s view. The placing business sees beneficiary instead of placedBy.
  • The placing business’s copy has no id, decidedAt or createdAt, and the beneficiary’s has no createdAt. 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/events with a key that has holds.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.

Was this page helpful?