Rinne API Documentation

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. Requests with both fields (or neither) are rejected with a 400 validation error. The primary flag 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) 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).

Merchant
Organization

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
  }'

curl -X POST https://api-sandbox.rinne.com.br/core/v1/companies/me/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.

Merchant
Organization

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

curl -X POST https://api-sandbox.rinne.com.br/core/v1/companies/me/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:

Field	Required	Notes
`request_id`	Yes	Client reference for the cashout
`origin_bank_account_id`	Yes	UUID of the account to debit
`amount`	Yes	Amount in cents
`method`	Yes	Must be `PIX`
`destination_bank_account_id`	One of destination pair	Omit when using a PIX key destination
`destination_pix_key_id`	One of destination pair	Omit when using a bank account destination
`currency`	No	Defaults to `BRL`
`metadata`	No	Arbitrary key-value object

Send exactly one destination field. If the request contains both destination_bank_account_id and destination_pix_key_id, or neither, the API returns 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.

Destination: external bank account

Merchant
Organization

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

curl -X POST https://api-sandbox.rinne.com.br/core/v1/banking/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"
  }'

Destination: external PIX key

Omit destination_bank_account_id and send destination_pix_key_id (the UUID returned from POST …/pix-keys).

Merchant
Organization

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

curl -X POST https://api-sandbox.rinne.com.br/core/v1/banking/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

Merchant
Organization

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"

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

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

curl "https://api-sandbox.rinne.com.br/core/v1/banking/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

Scope	Cashouts	External bank accounts	External 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`

Getting started

Core concepts

Guides

Cashouts

Before you start

1) Register an external PIX key destination

2) Register an external bank account destination

3) Create a cashout

Destination: external bank account

Destination: external PIX key

4) List, get details, and receipt

Cashout status values

Webhooks

Reference endpoints

​Before you start

​1) Register an external PIX key destination

​2) Register an external bank account destination

​3) Create a cashout

​Destination: external bank account

​Destination: external PIX key

​4) List, get details, and receipt

​Cashout status values

​Webhooks

​Reference endpoints

Before you start

1) Register an external PIX key destination

2) Register an external bank account destination

3) Create a cashout

Destination: external bank account

Destination: external PIX key

4) List, get details, and receipt

Cashout status values

Webhooks

Reference endpoints