# Holds

A **maturity hold** delays when settled funds can leave a wallet. The funds appear in the wallet balance, but the payout engine cannot draw them until they mature. A maturity hold does not create or schedule a payout.

## How maturity works

For Live accounts, settlement credits and split allocations create maturity lots. Each split destination has its own lot, held independently, and so does the part of a split that stays in the seller's main wallet (its remainder or rounding residual). A lot becomes withdrawable **T+N business days** after the payment was captured (or created, if it was never captured separately), counted on the currency's settlement calendar — not from the day it settled or split. `N` is the account's `payoutHoldDays`: the default is **3 business days**, with a supported range of **1–30**.

The hold days are set by Fynex through a backoffice control. There is no seller REST operation to read or change `payoutHoldDays`. Early release of a lot is also backoffice-only: a Fynex administrator can expedite it, and there is no REST path for it.

Once a lot's maturity time passes, its funds are withdrawable. No money moves and no payout is created: your platform must still request a payout, or use an automatic payout configured for your account.

Maturity holds are on in production for every Live account. Demo accounts have no maturity hold: settled Demo funds are withdrawable as soon as they post.

## Read the wallet balances

Use `GET /payments-api/v1/wallets` or `GET /payments-api/v1/wallets/{wallet_id}`. The relevant fields are:

| Field | Meaning |
|---|---|
| `availableBalanceMinor` | Settled value available within the wallet, including funds still maturing. |
| `maturingBalanceMinor` | The part of available balance still under maturity hold. This is an amount, not a maturity date. |
| `withdrawableBalanceMinor` | The amount a payout can draw now, after maturity holds. |
| `heldBalanceMinor` | Funds reserved against an in-flight payout. This is a different hold; it is released if that payout fails. |

There is no seller-visible maturity date or REST endpoint for listing individual maturity lots. Use `withdrawableBalanceMinor` to decide whether a payout can be requested; do not infer a release date from the aggregate `maturingBalanceMinor`.

**Example** (EUR, two decimal places, `payoutHoldDays` 3). A payee's wallet already holds EUR 50.00 that has matured. A payment captured on Monday settles the same day, and its split credits the payee EUR 100.00:

| | `availableBalanceMinor` | `maturingBalanceMinor` | `withdrawableBalanceMinor` |
|---|---|---|---|
| Before the split | 5000 | 0 | 5000 |
| Monday, after the split | 15000 | 10000 | 15000 − 10000 = 5000 |
| Thursday, after the lot matures | 15000 | 0 | 15000 |

On Monday the balance is EUR 150.00 but a payout can draw only EUR 50.00; a payout for EUR 150.00 is refused with `409` `insufficient_balance`. Three business days later the EUR 100.00 lot matures and all EUR 150.00 is withdrawable — but nothing is paid out until the platform requests a payout.

`heldBalanceMinor` is separate. For example, after a payout reserves EUR 25.00, that reservation is represented as an in-flight payout hold; it is not the maturity hold described above.

## See also

- [Wallets](https://docs.fynex.ai/payments-api/v2/docs#tag/wallets) — wallet balance fields and ledger.
- [Payouts](https://docs.fynex.ai/payments-api/v2/docs#tag/payouts) — request a payout and handle insufficient withdrawable balance.
- [Splits](https://docs.fynex.ai/payments-api/v2/docs#tag/splits) — settlement allocations and split destinations.