Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt

Use this file to discover all available pages before exploring further.

Cashouts are outbound transfers from one of your bank accounts at the provider (the origin) to exactly one registered external recipient: either an external bank account record or an external PIX key record. The API creates one cashout resource per attempt; execution and status updates happen asynchronously through providers and events.
Affiliation PIX keys (/pix/keys) are not the same as external PIX key destinations under /pix-keys. The latter exists only for cashout recipients. See Banking and PIX Payments.

​
Origins and destinations

The origin is always identified by origin_bank_account_id: an account UUID that corresponds to a Bank Account from an Affiliation with available balance. The destination is either destination_bank_account_id or destination_pix_key_id, never both. Register destinations before you create the cashout.

​
Entity relationships

​
Operational rules

  • One destination type per cashout: use a bank-account ID or a PIX-key ID exclusively.
  • Balance: funds must be available on the origin.
  • Identifiers: request_id is required—use it for idempotency and to correlate your orders with ours.
  • DICT: PIX key destinations are validated with the network; responses may expose masked holder data per BACEN rules.
  • PIX key destinations require an active Affiliation as it is required for DICT lookup

​
External PIX keys

Create a /pix-keys record per recipient key your integration will route cashouts through. Resolution runs against DICT; creation responses include dict_key_information (sometimes masked). 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/pix-keys \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "[email protected]",
    "primary": false
  }'
In a company context, use /v1/companies/me/pix-keys (create, read, update, delete) instead of /v1/merchants/{merchantId}/pix-keys. Full field lists and behavior are documented on those /pix-keys paths in the API reference.

​
External bank accounts

Register recipient settlement details with POST …/bank-accounts. Accounts used as cashout destinations reuse the same merchant (or company) bank-account resources described in Banking; the difference is how you use the returned id in the cashout payload. 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/bank-accounts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_number": "0001",
    "account_number": "12345678",
    "account_type": "CHECKING",
    "account_holder_name": "Recipient Legal Name",
    "account_holder_document_number": "12345678901",
    "ispb": "18236120"
  }'
Use digits only for branch_number and account_number (no dashes or spaces). Full field lists and validation errors are documented on POST /v1/merchants/{merchantId}/bank-accounts (and /v1/companies/me/bank-accounts) in the API reference.

​
Creating a cashout

Each cashout POST debits origin_bank_account_id, transfers amount (in cents), and uses method: PIX. Omit one destination field entirely when you use the other.

​
Bank account destination

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "cashout-order-789",
    "origin_bank_account_id": "223e4567-e89b-12d3-a456-426614174000",
    "destination_bank_account_id": "334e4567-e89b-12d3-a456-426614174001",
    "amount": 50000,
    "currency": "BRL",
    "method": "PIX"
  }'

​
PIX key destination

Send destination_pix_key_id (the id from POST …/pix-keys) instead of destination_bank_account_id. 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "cashout-order-790",
    "origin_bank_account_id": "223e4567-e89b-12d3-a456-426614174000",
    "destination_pix_key_id": "445e4567-e89b-12d3-a456-426614174002",
    "amount": 25000,
    "method": "PIX"
  }'
A typical immediate response establishes the cashout resource; exact fields follow the POST …/cashouts schema in the API reference: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "request_id": "cashout-order-789",
  "status": "PENDING",
  "amount": 50000,
  "method": "PIX"
}

​
Listing, status, and receipts

You confirm outcomes by polling identifiers and subscribing to webhooks (preferred for production). 
curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts/CASHOUT_ID" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts/CASHOUT_ID/receipt" \
  -H "x-api-key: YOUR_API_KEY"
Receipts are only available for eligible finalized states, may require operational context such as end-to-end IDs, and are documented under GET /v1/merchants/{merchantId}/cashouts/{id}/receipt (organization: GET /v1/banking/cashouts/{id}/receipt).

​
Lifecycle and returns

Statuses move asynchronously: PENDING, PROCESSING, COMPLETED, FAILED, plus post-settlement reversal states PARTIALLY_RETURNED and RETURNED.
  • COMPLETED: the outbound leg succeeded from the provider’s perspective.
  • PARTIALLY_RETURNED / RETURNED: subsequent reversal events alter what you reconcile—treat each transition as its own ledger event.
Do not treat COMPLETED alone as immutable financial closure. Continue listening for status changes until you know reconciliation is settled.

​
Webhooks

Cashouts finish asynchronously after the API accepts POST …/cashouts: the provider executes the PIX leg and may emit returns later. Treat webhooks as the primary signal for lifecycle updates in production (use listing and GET …/cashouts/{id} when you need to backfill or audit). Rinne sends two banking events for cashouts:
  • cashout.created: Emitted when the cashout resource is created successfully.
  • cashout.status-changed: Emitted when status changes—covering progress (PENDING, PROCESSING), terminal outcomes (COMPLETED, FAILED), and post-settlement reversals (PARTIALLY_RETURNED, RETURNED).
Payloads include identifiers and transition fields (for example cashout_id, old_status, new_status, and error_message when a failure occurs). Event envelopes also carry standard metadata such as id, timestamp, company_id, and correlation_id; see the Webhooks guide for the shared shape.
Delivery is at-least-once. Use the event id for idempotency so you do not apply the same transition twice.
For endpoint setup, Svix signature verification, retries, and handler examples, see Webhooks. Payload field definitions for each event live in the API reference under Webhooks → Events (cashout.created, cashout.status-changed).

​
Next steps

Cashouts guide

Step-by-step registration, payloads, and organization vs merchant paths

Banking

Balances, statements, affiliation keys, internal transfers

Webhooks

Event-driven lifecycle handling

API reference

Exact request and response schemas for each cashout and destination endpoint