---
title: Escrow holds
description: Set money aside for someone, then pay it to them or give it back.
---

:::note[In a nutshell]
An escrow hold sets money aside for someone. Later you either pay it to them or give it back. You choose who it is for when you place the hold, the same way you choose a destination for a payout.
:::

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

```text
                  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

```http
POST /v1/holds
Idempotency-Key: hold-order-2210
```

```json
{
  "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](/guides/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`:

```json
{
  "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`.

```json
{
  "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

```http
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:

```json
{ "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

```http
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.

```json
{
  "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](/guides/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](/guides/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](#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](/guides/errors).
