# Bank rail cash-outs

Source: https://docs.settlemint.com/docs/api-reference/guides/bank-rail-cash-outs
Pay a client's account through the bank in booked or delegate mode, read and decide a cash-out, and handle bank hours and returned payouts.

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](https://docs.settlemint.com/docs/api-reference/guides/bank-rail) for connections, token links, and clients.

## Pay out a cash-out [#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 [#booked-mode]

The client requests a redemption on the token, holding units on a redemption line. A manager lists open lines via `GET /connections/{connectionId}/client-links/{clientLinkId}/redemption-requests` and records the cash-out via `POST /connections/{connectionId}/cash-outs` (`lineId`, `clientAccountId`). A participant records their own via `POST /api/v2/users/me/bank-cash-outs` (`connectionId`, `lineId`, `clientAccountId`).

Repeating the same `lineId` and `clientAccountId` returns the existing cash-out. Using a different `clientAccountId` for the same line returns `409 bankRail.cashOut.DUPLICATE`.

In both supply modes, cash-outs return `409 bankRail.cashOut.REFUSED` (`data.reason: "participant-restricted"`) 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 [#delegate-mode]

Because a delegate token has no redemption lines, an escrow holds the client's tokens:

1. **Create escrow:** A bank rail manager with the escrow manager role calls `POST /connections/{connectionId}/token-links/{tokenLinkId}/escrow` (with wallet verification on session calls, missing role returns `escrow-manager-missing`). Returns `200` (`ready`) within `Prefer: wait`, or `202` (`creating`) with `Location` pointing to `GET /connections/{connectionId}/token-links/{tokenLinkId}/escrow`. The rail wallet controls exactly one escrow per link.
2. **Check transferable balance:** The client calls `GET /api/v2/users/me/bank-links/{clientLinkId}/transferable-balance` on the token's network (returning live balance minus frozen and held units, or `404 BankClientLinkUnavailable`).
3. **Approve escrow:** From the linked wallet, the client approves the escrow for the exact cash-out amount (any other allowance, even larger, is rejected).
4. **Record cash-out:** The client calls `POST /api/v2/users/me/bank-cash-outs` with `connectionId`, `amount`, `clientAccountId`, and a required `Idempotency-Key`. Managers cannot create delegate cash-outs for clients.
5. **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](#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.reason: "allowance"` if live transferable balance is too low or the escrow allowance does not exactly match `amount`, and `data.reason: "state"` 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 [#read-and-decide]

- `GET /connections/{connectionId}/cash-outs` lists cash-outs with `filter` and `page`, and `GET /connections/{connectionId}/cash-outs/{cashOutId}` reads one.
- `GET /api/v2/users/me/bank-cash-outs` lists a participant's own cash-outs.
- Cash-outs over the threshold enter `awaiting-checker` with an `approvalId`. A different manager sends `POST /connections/{connectionId}/cash-outs/{cashOutId}/decisions` with `{"action": "approve", "approvalId": "..."}` (sends the bank instruction) or `"reject"` (cancels the line or unlocks escrow tokens).

### Follow a cash-out [#follow-a-cash-out]

`GET /connections/{connectionId}/cash-outs/{cashOutId}/stream` 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 [#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 bankRail.connection.CALENDAR_UNAVAILABLE`.

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/v2/users/me/bank-links` returns `payoutTiming` for the current value date, and reconciliation reports `report.businessDay` and `suspenseOldestAgeBusinessDays`.

### Returned payouts [#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/{connectionId}/credits` with `bankTxId` set to `return:<cashOutId>:<returnId>` 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](https://docs.settlemint.com/docs/api-reference/guides/bank-rail-credits#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-rail.cash-out.returned` when any pending re-credit is admitted.