These routes pay out client redemptions through the bank in booked or delegate mode, read and decide cash-outs, and handle bank hours and returned payouts. Relative connection paths sit under /api/v2/bank-rail. See Bank rail API for connections, token links, and clients.
Pay out a cash-out
A cash-out instructs the bank to pay a client's active bank account, then burns the held tokens once the bank reports settlement. Rejected or expired payouts release tokens back to the client. Each instruction uses the cash-out id as its instruction id so FIX resends stay idempotent.
Booked mode
The client requests a redemption on the token, holding units on a redemption line. A manager lists open lines via GET /connections/ and records the cash-out via POST /connections/ (lineId, clientAccountId). A participant records their own via POST /api/ (connectionId, lineId, clientAccountId).
Repeating the same lineId and clientAccountId returns the existing cash-out. Using a different clientAccountId for the same line returns 409 bank.
In both supply modes, cash-outs return 409 bank (data.) if the client's strictest wallet status in the token link's organisation is suspended, closed, terminated, or restricted with withdrawals. Checker approvals are refused the same way (reject still works). Cash-outs approved before a restriction release as participant-restricted before bank instruction or token locking.
Delegate mode
Because a delegate token has no redemption lines, an escrow holds the client's tokens:
- Create escrow: A bank rail manager with the escrow manager role calls
POST /connections/(with wallet verification on session calls, missing role returns{connection Id}/ token- links/ {token Link Id}/ escrow escrow-manager-missing). Returns200(ready) withinPrefer: wait, or202(creating) withLocationpointing toGET /connections/. The rail wallet controls exactly one escrow per link.{connection Id}/ token- links/ {token Link Id}/ escrow - Check transferable balance: The client calls
GET /api/on the token's network (returning live balance minus frozen and held units, orv2/ users/ me/ bank- links/ {client Link Id}/ transferable- balance 404 Bank).Client Link Unavailable - Approve escrow: From the linked wallet, the client approves the escrow for the exact cash-out amount (any other allowance, even larger, is rejected).
- Record cash-out: The client calls
POST /api/withv2/ users/ me/ bank- cash- outs connectionId,amount,clientAccountId, and a requiredIdempotency-Key. Managers cannot create delegate cash-outs for clients. - Lock tokens: The rail deposits and locks the tokens until the payout deadline, refreshing the lock deadline after checker approval.
The response returns while the cash-out is locking, then advances to awaiting-checker or approved. Follow its stream (Follow a cash-out) to watch transitions.
On bank settlement, the rail transfers the lock to the rail wallet and burns it via the supply delegate. Otherwise it unlocks the tokens for client withdrawal.
Requests return data. if live transferable balance is too low or the escrow allowance does not exactly match amount, and data. while another delegate cash-out on the same wallet is still locking. If balance or allowance drops before the rail deposits the tokens, the cash-out releases as not-locked with an operations case.
Read and decide
GET /connections/lists cash-outs with{connection Id}/ cash- outs filterandpage, andGET /connections/reads one.{connection Id}/ cash- outs/ {cash Out Id} GET /api/lists a participant's own cash-outs.v2/ users/ me/ bank- cash- outs - Cash-outs over the threshold enter
awaiting-checkerwith anapprovalId. A different manager sendsPOST /connections/with{connection Id}/ cash- outs/ {cash Out Id}/ decisions {"action": "approve", "approval(sends the bank instruction) orId": "... "} "reject"(cancels the line or unlocks escrow tokens).
Follow a cash-out
GET /connections/ streams Server-Sent Events under the same role and error rules as the read route. It sends the current state first, then every state change.
The stream closes after reaching a resting state (paid, released, returned, or unbooked with no recovered units left to burn), or after 180 idle seconds. Open a new stream if you need to follow a late settlement, bank return, or recovery. The SDK exposes this as bankRail.cashOutStream.
Bank hours and value dates
Connections carry holidayCalendarId (default adgm, null makes every day a business day), paymentTimeZone (default Asia/Dubai), and paymentCutOffTime (default null for full day, while 00:00 is refused). Unknown calendars return 422 bank.
Each cash-out preserves the settings active at creation and returns paymentCutOffTime, paymentTimeZone, expectedValueDate, and releaseAt. Approvals at or after cut-off (or on closed days) stay approved until releaseAt at the next opening. deadlineAt counts business time from releaseAt (capped at one year), and added holidays that shorten remaining time below the settlement window release the cash-out as expired.
Once built, the FIX session may resend stored instructions on any day with the possible-duplicate flag. GET /api/ returns payoutTiming for the current value date, and reconciliation reports report.businessDay and suspense.
Returned payouts
If a bank returns a settled payout (for example, a closed destination account), the rail records it in returns (returnId, amount, valueDate, creditId). The cash-out shows returning until every return creates a re-credit, then returned.
Each re-credit appears on GET /connections/ with bankTxId set to return:<cash and returnedCashOutId populated. It always waits in awaiting-mint-approval for manager approval regardless of amount or approval-family settings (Approve a credit before it mints). Parked re-credits cannot be returned to payer.
Returns arriving before settlement (instructed, releasing, or released) wait in returns with a warning case until late settlement books. Unmatched, wrong-currency, or over-amount returns open a critical case.
If a released cash-out settles late, webhook status stays released during recovery, emits bank-rail.cash-out.paid once fully recovered and burnt, and follows with bank- when any pending re-credit is admitted.