Skip to main content

Pay out a bank rail cash-out

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 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/{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

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) 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

  • 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

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

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

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). 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.

Was this page helpful?