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

> Understand outbound PIX transfers—origins and destinations, how they map to the API, lifecycle states, and reconciliation

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.

<Info>
  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](/concepts/banking) and [PIX Payments](/guides/pix-payments#pix-key-management-for-receiving-payments).
</Info>

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

```mermaid theme={null}
graph LR
    M[Merchant or company] -->|owns| OBA[Origin bank accounts]
    OBA -->|linked to| A[Affiliation]
    M -->|registers for recipients| EB[External bank account records]
    M -->|registers for recipients| PK[External PIX keys]
    OBA -->|debited by| CO[Cashout]
    EB -->|or| CO
    PK -->|or| CO
    CO -->|executed via| PR[Provider]
    CO -->|notifies via| WH[Webhooks]

    style M fill:#7B89FF,color:#fff
    style OBA fill:#5B68EB,color:#fff
    style A fill:#4A56D9,color:#fff
    style EB fill:#4A56D9,color:#fff
    style PK fill:#7B89FF,color:#fff
    style CO fill:#5B68EB,color:#fff
    style PR fill:#4A56D9,color:#fff
    style WH fill:#7B89FF,color:#fff
```

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

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

<Note>
  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](/api-reference/introduction).
</Note>

## 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](/concepts/banking); the difference is how you use the returned `id` in the cashout payload.

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

<Note>
  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.
</Note>

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

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

### PIX key destination

Send `destination_pix_key_id` (the `id` from `POST …/pix-keys`) instead of `destination_bank_account_id`.

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

A typical immediate response establishes the cashout resource; exact fields follow the `POST …/cashouts` schema in the API reference:

```json theme={null}
{
  "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).

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

<Note>
  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`).
</Note>

## Lifecycle and returns

Statuses move asynchronously: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, plus post-settlement reversal states `PARTIALLY_RETURNED` and `RETURNED`.

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> PROCESSING
    PROCESSING --> COMPLETED
    PROCESSING --> FAILED
    COMPLETED --> PARTIALLY_RETURNED
    COMPLETED --> RETURNED
    PARTIALLY_RETURNED --> 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.

<Warning>
  Do not treat `COMPLETED` alone as immutable financial closure. Continue listening for status changes until you know reconciliation is settled.
</Warning>

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

<Tip>
  Delivery is at-least-once. Use the event `id` for idempotency so you do not apply the same transition twice.
</Tip>

For endpoint setup, Svix signature verification, retries, and handler examples, see [Webhooks](/guides/webhooks). Payload field definitions for each event live in the API reference under **Webhooks → Events** (`cashout.created`, `cashout.status-changed`).

## Next steps

<CardGroup cols={2}>
  <Card title="Cashouts guide" icon="book-open" href="/guides/cashouts">
    Step-by-step registration, payloads, and organization vs merchant paths
  </Card>

  <Card title="Banking" icon="building-columns" href="/concepts/banking">
    Balances, statements, affiliation keys, internal transfers
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Event-driven lifecycle handling
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Exact request and response schemas for each cashout and destination endpoint
  </Card>
</CardGroup>