Holds
Understand payout maturity holds, when settled funds become withdrawable, and which hold details the Payments API exposes.
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.