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

> Cash out via PIX using an origin account and an external destination

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.

<Note>
  For **receiving** PIX (`/pix/keys`), balances, and statements, see <a href="/concepts/banking">Banking</a>. For **external** destinations, cashout lifecycle, returns, and receipts, see <a href="/concepts/cashouts">Cashouts</a> (Core concepts).
</Note>

## 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).

<Tabs>
  <Tab title="Merchant">
    ```bash theme={null}
    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": "recipient@example.com",
        "primary": false
      }'
    ```
  </Tab>

  <Tab title="Organization">
    ```bash theme={null}
    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": "recipient@example.com",
        "primary": false
      }'
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="Merchant">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Organization">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

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

### Destination: external bank account

<Tabs>
  <Tab title="Merchant">
    ```bash theme={null}
    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"
        }
      }'
    ```
  </Tab>

  <Tab title="Organization">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

### Destination: external PIX key

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

<Tabs>
  <Tab title="Merchant">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Organization">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

## 4) List, get details, and receipt

<Tabs>
  <Tab title="Merchant">
    ```bash theme={null}
    curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```bash theme={null}
    curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts/CASHOUT_ID" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```bash theme={null}
    curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/cashouts/CASHOUT_ID/receipt" \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Organization">
    ```bash theme={null}
    curl "https://api-sandbox.rinne.com.br/core/v1/banking/cashouts" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```bash theme={null}
    curl "https://api-sandbox.rinne.com.br/core/v1/banking/cashouts/CASHOUT_ID" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```bash theme={null}
    curl "https://api-sandbox.rinne.com.br/core/v1/banking/cashouts/CASHOUT_ID/receipt" \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

<Note>
  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 <a href="/concepts/cashouts">Cashouts</a> or the cashout receipt endpoints in the API reference.
</Note>

## 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 <a href="/guides/webhooks">Webhooks</a> 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`           |