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 move money from an origin bank account (your balance with the provider) to exactly one destination: either a registered external bank account (/bank-accounts) or a registered external PIX key (/pix-keys). Request and response fields for those 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).

​
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: Register either a Company bank account or a Company PIX key (paths under /bank-accounts or /pix-keys). In the cashout body you send destination_bank_account_id or destination_pix_key_id—never both.
  • Idempotency / tracking: request_id is required; use a unique string per cashout attempt (for example a UUID or your internal reference).

​
1) Register an external PIX key destination

POST accepts key (required) and optional primary. The API resolves the key via DICT; the create response can include dict_key_information (often masked per BACEN rules). 
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
  }'

​
2) Register an external bank account destination

Required fields: branch_number, account_number, account_type, account_holder_name, account_holder_document_number, ispb. Use digits only for branch and account numbers. 
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"
  }'

​
3) Create a cashout

Request body includes:
FieldRequiredNotes
request_idYesClient reference for the cashout
origin_bank_account_idYesUUID of the account to debit
amountYesAmount in cents
methodYesMust be PIX
destination_bank_account_idOne of destination pairOmit when using a PIX key destination
destination_pix_key_idOne of destination pairOmit when using a bank account destination
currencyNoDefaults to BRL
metadataNoArbitrary key-value object

​
Destination: external bank account

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",
    "metadata": {
      "order_id": "order-789"
    }
  }'

​
Destination: external PIX key

Omit destination_bank_account_id and send destination_pix_key_id (the UUID returned from POST …/pix-keys). 
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"
  }'

​
4) List, get details, and receipt

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

ScopeCashoutsExternal bank accountsExternal PIX keys
Merchant/v1/merchants/{merchantId}/cashouts/v1/merchants/{merchantId}/bank-accounts/v1/merchants/{merchantId}/pix-keys
Organization/v1/banking/cashouts/v1/companies/me/bank-accounts/v1/companies/me/pix-keys