Pay out settlement money (books first, transfer follows)
Draws the merchant's settlement money to the tenant treasury and records the payout; the external transfer is executed off-platform, so this call moves the books, not the bank.
/v1/clients/{clientId}/payoutsDraws the merchant's settlement money to the tenant treasury and records the payout; the external transfer is executed off-platform, so this call moves the books, not the bank. Omit amount to pay out the whole settlement balance. Requires an Idempotency-Key, and the payout id is derived from it, so key on the payout period rather than the moment: a retry after a timeout pays once. Needs authority over the client — membership of its organization, an API key bound to this client, or tenant staff holding clients:manage; anything else is refused not_client_member or insufficient_scope (403), and an unknown client client_not_found (404). Refuses invalid_request (400) for a negative amount, nothing_to_pay (422) when there is no settlement balance, insufficient_funds (422) when the amount exceeds it, and idempotency_key_reuse (409) when the key comes back with a different body.
Authorization
bearerAuth A tenant API key (sk_{env}_{id}_{secret}), a wallet user token, or an IdP access token. Which principal the credential resolves to decides the scopes it carries; see the authentication guide.
In: header
Path Parameters
uuidHeader Parameters
1 <= length <= 200Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
# An empty body pays out the full settlement balance. Key on the payout# PERIOD, not the moment, so a retry after a timeout pays once.curl -sS -X POST "$WALLETD_API/v1/clients/$CLIENT_ID/payouts" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: payout-2026-08-11-$CLIENT_ID" \ -d '{}'{ "id": "0191c2de-2f70-7e18-b604-5da93c17be82", "merchant_id": "0191c2d6-1a44-7b09-8e73-2c5f9a08d641", "amount": 41250, "fee": 0, "txn_id": "0191c2de-2f70-7f03-9a17-6ec84b205fd1", "rail": "manual", "status": "completed", "created_at": "2026-09-20T11:00:09Z"}The client's payout statement, newest first
The client's payout statement, newest first, each row with the amount that left settlement, the fee the wallet kept, the rail and the ledger transaction behind it.
Delivery attempt log (admin)
Every delivery attempt with its attempt number, HTTP response code and error, newest first — the log to read when a receiver is not seeing events.