Skip to main content
Cashouts move money from an origin bank account (your balance with the provider) to exactly one destination. In the cashout body you send one of four fields:
  • destination_pix_key — the PIX key value, given inline (recommended for PIX).
  • destination_bank_account — the recipient account fields, given inline (recommended for bank accounts).
  • destination_pix_key_id — the id of a PIX key you registered ahead of time under the caller.
  • destination_bank_account_id — the id of a bank account you registered ahead of time under the caller.
Request and response fields for the destination resources are documented on each endpoint in the API reference.
For receiving PIX (/pix/keys), balances, and statements, see Banking. For external destinations, cashout lifecycle, returns, and receipts, see Cashouts (Core concepts).

​
Prefer inline destinations

Register the destination inside the cashout request itself. Inline destinations cost less against your DICT quota and remove a whole class of setup work.
  • One DICT lookup instead of two for a first-time PIX key. Registering a PIX key up front with POST …/pix-keys and then paying to it later spends one DICT lookup at registration and a second one at cashout time. Passing destination_pix_key inline collapses both into a single lookup that the payment consumes directly. DICT throttles participants by lookup count (Brazilian banks call these fichas), so pre-registering every recipient you might ever pay can exhaust your quota and get lookups (and therefore cashouts) blocked before you ever debit an account.
  • No separate registration step. The service still persists the destination as a non-primary company record on first use — so the second cashout to the same recipient is free of DICT cost and behaves exactly like the registered-id path — but you never write the “register, then pay” sequence yourself. The 201 response carries the resulting destination_pix_key_id or destination_bank_account_id for later reference.
  • Retries reuse what the first attempt registered. Once an inline PIX key has been persisted for the caller, subsequent inline cashouts with the same key value match the active row before any DICT call and skip the lookup — so retrying an inline cashout, or paying the same recipient again inline, matches like a registered destination. A repeated inline bank account is matched on (account_number, ispb) and reused when the other banking fields agree.
Fall back to destination_pix_key_id / destination_bank_account_id when the destination is already registered (a supplier you pay every week, an automatic-cashout target) or when your integration keeps its own catalogue of recipient ids.

​
Before you start

  • Origin: origin_bank_account_id is the bank account debited for the cashout. It must be eligible per your setup (for example, an affiliated account with available balance). Use the id returned when you list bank accounts for the merchant or company.
  • Destination: Send exactly one of destination_pix_key, destination_bank_account, destination_pix_key_id or destination_bank_account_id. Requests that set more than one or none are rejected with a 400 validation error. The primary flag on registered records does not act as a fallback here: cashouts created through the API always use the destination you name in the request.
  • Idempotency / tracking: request_id is required; use a unique string per cashout attempt (for example a UUID or your internal reference).

​
1) Create a cashout with an inline destination

Request body:
Send exactly one destination field. Requests that set more than one of the four destination fields, or none, are rejected with a 400 validation error. For companies with automatic transfers enabled, Rinne creates cashouts on a schedule and picks the destination by priority — primary active bank account first, then primary active PIX key. If neither exists, that cycle is skipped. See Automatic cashouts.

​
Inline PIX key

Send destination_pix_key: { "key": "…" }. The service normalizes the key (documents to bare digits, phones to + and digits, emails to lowercase) and looks for the caller’s active PIX key with that value. A match is reused with no DICT cost; a miss triggers a single DICT lookup that persists the key as a non-primary company PIX key and is consumed by this cashout.
Expected 201 response — destination_pix_key_id is the id of the reused or newly registered PIX key. Store it if you plan to reference the same recipient again by id (it will match on retry either way):

​
Inline bank account

Send destination_bank_account with the full account payload (branch_number, account_number, account_type, account_holder_name, account_holder_document_number, ispb; optional nickname). The service reuses the caller’s active account with the same (account_number, ispb) when the other banking fields match. A match with different values is rejected with 409 CONFLICT_ERROR (details.differing_fields names the mismatched fields) rather than paying to the stored details. When nothing matches, the account is registered as a non-primary company bank account and the cashout pays to it.
Expected 201 response — destination_bank_account_id is the id of the reused or newly registered account, and destination_bank_account_nickname echoes the current label (see Banking → Nicknames):
If the payload’s (account_number, ispb) matches an existing active account of the caller but any of branch_number, account_type, account_holder_name or account_holder_document_number differs, the request is rejected with 409 CONFLICT_ERROR rather than paying to the stored details:
Update the payload to match the stored record, or edit the stored record first with PATCH …/bank-accounts/{id}, then retry the cashout with the same request_id.
Inline destinations only reuse or create records under the caller’s own merchant or company — they are never a way to pay to a third party’s stored account. The reuse/create decision runs after every origin, pricing and balance guard, so a request rejected before payment leaves nothing behind; a request rejected by the provider after payment starts leaves the new record as a valid, reusable destination.

​
2) Pay to a pre-registered destination

Use this path when the destination is already on file for the caller and you want to reference it by id. Registration itself spends one DICT lookup for a PIX key at POST …/pix-keys time, so register only the destinations you actually need to keep around.

​
Register a destination

Use /v1/companies/me/pix-keys for the organization scope.

​
Cashout to a registered PIX key

​
Cashout to a registered bank account

Use /v1/banking/cashouts for the organization scope on both paths.

​
3) List, get details, and receipt

For organization cashouts, CASHOUT_ID can be internal id or external request id per API docs. Receipts are only returned for certain completed states and require an end-to-end ID—see Cashouts or the cashout receipt endpoints in the API reference.

​
Cashout status values

Typical cashout statuses are PENDING, PROCESSING, COMPLETED, FAILED, PARTIALLY_RETURNED, and RETURNED.

​
Webhooks

Subscribe to:
  • cashout.created: emitted when the cashout is successfully created
  • cashout.status-changed: emitted when status updates
See Webhooks for handling events.

​
Reference endpoints