Fetch one payout by id
The payout in its CURRENT state, whatever that is — including a terminal failure, reported here as the object rather than as an error, and a return (RETURNED, with the re-credit) after settlement. This is the fetch half of the thin webhook payloads (a payout.* event carries only a resource pointer) and the poll surface the money errors point at. A payout you made for a sub-client is fetched by sending the same x-on-behalf-of header; its webhook carries that sub-client id so you know which one.
The payout in its CURRENT state, whatever that is — including a terminal failure, reported here as the object rather than as an error, and a return (RETURNED, with the re-credit) after settlement. This is the fetch half of the thin webhook payloads (a payout.* event carries only a resource pointer) and the poll surface the money errors point at. A payout you made for a sub-client is fetched by sending the same x-on-behalf-of header; its webhook carries that sub-client id so you know which one.
Authorization
bearer In: header
Path Parameters
The payoutId returned when you created it, or carried by the event's resource pointer.
Header Parameters
Act on behalf of one of your sub-clients. The value is that sub-client id, and the request then reads and writes that sub-client's own accounts and registry rows rather than yours. Omit it to act as yourself. A route that does not accept the header refuses it with 400 ON_BEHALF_OF_NOT_ALLOWED_HERE rather than ignoring it — that includes every vault route (deposits, withdrawals, conversions, sub-accounts, positions), the webhook registry, and POST /sub-clients, since a sub-client never has sub-clients of its own. An id that is not one of your sub-clients answers 404 ON_BEHALF_OF_NOT_FOUND; a closed one answers 409 ON_BEHALF_OF_SUB_CLIENT_CLOSED; and a key restricted to a subset of your sub-clients answers 403 ON_BEHALF_OF_NOT_ALLOWED_FOR_KEY for any node outside it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/partner/v1/payouts/a1c4e7f0-2b5d-4e8a-9c3f-6d1b0e4a7c29"{ "data": { "amount": "1250.00", "compensation": { "outcome": "REFUNDED" }, "currency": "EUR", "destination": { "currency": {}, "kind": "FIAT_BANK", "last4": {}, "rail": {} }, "disclosure": { "items": [ "ENVIRONMENT_IS_TESTNET: The environment is a testnet (Arbitrum Sepolia). No mainnet deployment exists.", "YIELD_IS_SIMULATED: The vault rate is set administratively and the interest it produces is minted as fresh underlying, not earned. It does not represent a return generated by deployed capital.", "FIAT_RAILS_ARE_MOCKED: No real fiat movement occurs. Balances are ledger entries against a sandbox provider.", "CONVERSION_RATES_ARE_MARKET_QUOTED_OR_REFUSED: A conversion is priced only by an external venue that quotes independently of TCB. When no such venue can price the pair, the conversion is refused rather than priced from an internal table. Read rate.pricingModel on every conversion: MARKET is a venue quote; any other value is not a market rate and must not be presented as one.", "CONTRACTS_ARE_UNAUDITED: No audit has been performed. Mainnet is gated on a two-firm audit that has not been commissioned.", "CUSTODY_IS_TCB_SUBACCOUNT: Everything held for the client — its vault shares, and the tcbUSD it holds between the steps of the tokenised deposit chain — is held in TCB custody, in the one TCB wallet assigned to the client. The client holds no keys and moves those tokens only through this API; each sub-account's shares and tcbUSD are book entries against what that wallet holds.", "INTEGRATION_AGREEMENT_ONLY: Fees as published on the rate card; no yield share, no return commitment." ], "summary": "This is a pilot integration on a testnet. Nothing in this system earns anything: the yield is simulated and the fiat rails are mocked.", "version": "2026-10-27" }, "endToEndId": {}, "failedAt": {}, "fee": { "amount": "25", "currency": "EUR" }, "return": { "reasonCode": {} }, "returnedAt": {}, "settledAt": {}, "sourceAccountId": {}, "status": "PENDING", "submittedAt": {} }, "success": true, "timestamp": "2026-09-02T10:15:30.000Z"}Quote a payout before making it POST
Prices the payout you are about to make, without making it: the Sending fee for the rail it will travel, and what leaves your account in total. Nothing is charged and no idempotency key is needed. The request is checked exactly as the payout would be (your money caps, your balance against amount plus fee, the destination's current state, the rail), so a refusal here is the refusal the payout would get. The quote is held for 60 seconds (expiresAt). Name its quoteId on POST /payouts to be charged the quoted fee; the payout must repeat the quoted request (instrumentId, currency, amount, sourceAccountId and the x-on-behalf-of header) and can use the quote once. Quoting first is optional and recommended: it is how you see the fee before you commit. A quote reserves nothing: your balance, caps and the destination are checked again when you pay. Send x-on-behalf-of to quote a payout of one of your sub-clients' money.
List settlements GET
Settlements the ACTING node sent or received, newest first, cursor-paginated. Scoped the way GET /accounts is: to read a sub-client's settlements, act as that sub-client.