> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cbpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

> Dispersa fiat a cuentas bancarias locales debitando tu saldo USDT

Un payout envía dinero en moneda local a una cuenta bancaria del país
destino. El monto se convierte de moneda local a USDT con **la tasa de tu
cuenta** (la de `GET /v1/rates`) y se debita `usdt_amount + fee` (el fijo,
si está configurado) de tu saldo.

Así se ve el ciclo completo, incluido qué pasa con tu saldo en cada paso:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    autonumber
    participant App as Tu app
    participant CB as CBPay
    participant Rail as Rail bancario local
    App->>CB: POST /v1/payouts (idempotency_key)
    CB->>CB: Convierte a tu tasa y debita<br/>usdt_amount + fee (available → held)
    CB-->>App: 202 processing (fx_rate, total_debit)
    CB->>Rail: Dispersa en moneda local
    alt El dinero llega
        Rail-->>CB: Confirmado
        CB->>CB: Consume el hold — final
        CB-->>App: Webhook payout_status_changed (completed)
    else El rail rechaza
        Rail-->>CB: Rechazado
        CB->>CB: Reembolsa el débito completo a available
        CB-->>App: Webhook payout_status_changed (failed + status_code)
    end
```

## 1. Descubre los corredores disponibles

Los países, monedas y métodos disponibles los define CBPay.
Consúltalos siempre por catálogo:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.qbank.cl/platform/v1/payouts/methods \
  -H "Authorization: Bearer <token>"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    { "country": "CL", "currency": "CLP", "method": "bank_transfer" },
    { "country": "PE", "currency": "PEN", "method": "bank_transfer" },
    { "country": "PE", "currency": "PEN", "method": "yape" },
    { "country": "BO", "currency": "BOB", "method": "qr" }
  ],
  "meta": { "retrieved": 4 }
}
```

Corredores y métodos disponibles:

| País      | Moneda    | Métodos                                                                   |
| --------- | --------- | ------------------------------------------------------------------------- |
| Chile     | CLP       | `bank_transfer`                                                           |
| Perú      | PEN       | `bank_transfer`, `yape`                                                   |
| México    | MXN       | `bank_transfer` (SPEI: CLABE o tarjeta de débito)                         |
| Venezuela | VES       | `bank_transfer`, `pago_movil`                                             |
| Bolivia   | BOB / USD | `bank_transfer`, `qr` (ver [Payout QR](#payout-qr))                       |
| Brasil    | BRL       | `pix` (por llave o a cuenta), `qr` (QR PIX — ver [Payout QR](#payout-qr)) |
| Ecuador   | USD       | `bank_transfer`, `deuna`, `cash_pickup`, `cnb`                            |
| Paraguay  | PYG       | `bank_transfer`                                                           |

La disponibilidad puede variar; el catálogo (`GET /v1/payouts/methods`) es
siempre la fuente de verdad. Si un país tiene un solo método, `method` es
opcional. Todos los métodos se cobran igual: tu tasa + fijo.

Para transferencias bancarias necesitas además el catálogo de bancos (de
ahí sale el `bank_code` del beneficiario):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.qbank.cl/platform/v1/payouts/banks?country=CL" \
  -H "Authorization: Bearer <token>"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    { "code": "001", "name": "Banco de Chile" },
    { "code": "012", "name": "Banco del Estado de Chile" },
    { "code": "016", "name": "Banco de Crédito e Inversiones" }
  ],
  "meta": { "retrieved": 3 }
}
```

## 2. Crea el payout

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "MX",
    "currency": "MXN",
    "method": "bank_transfer",
    "amount": "1500.00",
    "beneficiary": {
      "name": "María López",
      "account_type": "clabe",
      "account_number": "012180001234567895"
    },
    "description": "Pago factura 8841",
    "idempotency_key": "factura-8841"
  }'
```

<Warning>
  `beneficiary` es un objeto de pares clave/valor cuyos campos requeridos
  dependen del corredor (RUT y banco en Chile, CLABE en México, CCI en Perú,
  llave PIX en Brasil, etc.). El catálogo de métodos documenta los campos de
  cada uno.
</Warning>

<Note>
  Cada payout guarda al beneficiario como [contacto](/es/guias/contactos)
  automáticamente (`"save_contact": false` para no guardarlo). Para repetirle
  un pago sin re-tipear sus datos, envía `"beneficiary_contact_id"` en vez de
  `beneficiary` — se usa su beneficiario guardado más reciente para ese país
  y método (`422 no_saved_destination` si no tiene).
</Note>

Respuesta `202 Accepted`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "payout_id": "0d4f…",
  "account_id": "…",
  "idempotency_key": "factura-8841",
  "country": "MX",
  "currency": "MXN",
  "method": "bank_transfer",
  "local_amount": "1500.00",
  "fx_rate": "17.50",
  "usdt_amount": "85.714286",
  "fee": "0.300000",
  "total_debit": "86.014286",
  "settlement_asset": "USDT",
  "settlement_amount": "86.014286",
  "settlement_rate": "1",
  "status": "processing",
  "created_at": "2026-07-06T20:00:00Z"
}
```

En ese momento tu saldo ya refleja el débito: `total_debit` pasó de
`available` a `held` (en el saldo del `settlement_asset`).

### Pagar desde otro saldo (`settlement_asset`)

Por defecto el débito sale de tu asset de settlement predeterminado (USDT
salvo que lo cambies con `PUT /v1/settlement`). Para pagar una operación
puntual desde otro saldo, agrega `settlement_asset` al request. Ejemplo:
un payout de 100.000 CLP pagado desde el saldo BTC pasa por cuatro
transformaciones, todas registradas en la respuesta:

1. **CLP → USDT** a tu tasa: `100000 / 950.25 = 105.235465 USDT`.
2. **+ comisión fija**: `105.235465 + 0.30 = 105.535465 USDT` (`total_debit`).
3. **USDT → BTC** al precio efectivo de settlement (`settlement_rate`
   `109029.34070000`): `105.535465 / 109029.3407 = 0.00096795 BTC`
   (redondeo hacia arriba al satoshi).
4. **Débito y hold en BTC**: `settlement_amount` `0.00096795` sale de tu
   saldo BTC; el beneficiario recibe sus 100.000 CLP igual que siempre.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "country": "CL",
  "currency": "CLP",
  "local_amount": "100000",
  "fx_rate": "950.25",
  "usdt_amount": "105.235465",
  "fee": "0.300000",
  "total_debit": "105.535465",
  "settlement_asset": "BTC",
  "settlement_amount": "0.00096795",
  "settlement_rate": "109029.34070000",
  "status": "processing"
}
```

Si el payout falla, se reembolsa el `settlement_amount` exacto a tu saldo
BTC — nunca se re-cotiza. Si el precio de ejecución de BTC/GOLD no está
disponible en ese momento recibirás `503 pricing_unavailable`, y los
assets volátiles tienen un límite por operación
(`422 settlement_limit_exceeded`; consúltalo en `GET /v1/settlement`).

## 3. Recibe el estado final

Suscríbete al evento `payout_status_changed` ([webhooks](/es/webhooks)):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "payout_id": "0d4f…",
  "account_id": "…",
  "country": "MX",
  "currency": "MXN",
  "local_amount": "1500.00",
  "usdt_amount": "85.714286",
  "total_debit": "86.014286",
  "status": "completed",
  "status_code": ""
}
```

* **`completed`**: el dinero llegó; el hold se consume.
* **`failed`**: se reembolsa el débito completo automáticamente
  (`payout_refund` en tu ledger).

También puedes consultar en cualquier momento:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.qbank.cl/platform/v1/payouts/0d4f… \
  -H "Authorization: Bearer <token>"
```

### Estados del payout

| Estado       | Significado                              | ¿Tu saldo?                                           |
| ------------ | ---------------------------------------- | ---------------------------------------------------- |
| `processing` | Aceptado y en ejecución en el rail local | Débito retenido en `held`                            |
| `completed`  | El dinero llegó al beneficiario          | Hold consumido — final                               |
| `failed`     | El corredor lo rechazó o falló           | **Reembolso automático completo** (monto + comisión) |

## Consulta e historial

Cada payout se puede leer individualmente y el listado acepta filtros:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Un payout
curl https://api.qbank.cl/platform/v1/payouts/0d4f… \
  -H "Authorization: Bearer <token>"

# Historial con filtros: fechas, estado, país y paginación
curl "https://api.qbank.cl/platform/v1/payouts?from=2026-07-01&to=2026-07-08&status=failed&country=MX&page=1&page_size=50" \
  -H "Authorization: Bearer <token>"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "page": 1,
  "page_size": 50,
  "payouts": [
    {
      "payout_id": "0d4f…",
      "country": "MX",
      "currency": "MXN",
      "method": "bank_transfer",
      "local_amount": "1500.00",
      "fx_rate": "17.50",
      "usdt_amount": "85.714286",
      "fee": "0.300000",
      "total_debit": "86.014286",
      "status": "failed",
      "status_code": "core_rejected",
      "status_message": "beneficiary account does not exist",
      "created_at": "2026-07-06T20:00:00Z"
    }
  ]
}
```

`from`/`to` van en `YYYY-MM-DD` (UTC, ambos inclusive); una fecha inválida
responde `400 invalid_range`.

## Ejemplos por país

Cada corredor con su `beneficiary` exacto, el request completo y la
respuesta real. Las tasas (`fx_rate`) son ilustrativas — siempre aplican
las de tu cuenta en `GET /v1/rates`; el débito es `usdt_amount + fee`
(fijo, si está configurado; aquí `0.30`).

### Campos del beneficiary por corredor

| País | Método                | Campos del `beneficiary`                                                                                               |
| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| CL   | `bank_transfer`       | `name`, `tax_id` (RUT), `bank_code`, `account_type`, `account_number`                                                  |
| PE   | `bank_transfer`       | `name`, `account_number` (CCI de 20 dígitos)                                                                           |
| PE   | `yape`                | `name`, `phone` (`51XXXXXXXXX`)                                                                                        |
| MX   | `bank_transfer`       | `name`, `account_type` (`clabe`/`debit_card`), `account_number` (+ `bank_code` si es tarjeta)                          |
| VE   | `pago_movil`          | `phone`, `bank_code` (SUDEBAN), `document_value`                                                                       |
| VE   | `bank_transfer`       | `name`, `account_number` (20 dígitos), `document_value`                                                                |
| BO   | `bank_transfer`       | `name`, `tax_id`, `bank_code`, `account_number`                                                                        |
| BR   | `pix`                 | `name`, `tax_id` + (`pix_key` y `pix_key_type`) o (`bank_code` ISPB, `branch_code`, `account_number`)                  |
| EC   | `bank_transfer`       | `name`, `document_value` (cédula), `sender_name`, `account_number` (+ `bank_code` y `account_type` si es a otro banco) |
| EC   | `deuna`               | `name`, `document_value`, `sender_name`, `phone` (celular de la billetera)                                             |
| EC   | `cash_pickup` / `cnb` | `name`, `document_value`, `sender_name` — el beneficiario retira con su documento                                      |
| PY   | `bank_transfer`       | `name` (≤35), `tax_id`, `bank_code`, `account_number`                                                                  |

<Tabs>
  <Tab title="Chile">
    Transferencia bancaria en CLP. Requiere RUT, banco y cuenta:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "country": "CL",
        "currency": "CLP",
        "method": "bank_transfer",
        "amount": "100000",
        "beneficiary": {
          "name": "Pedro Soto Fuentes",
          "tax_id": "12.345.678-5",
          "bank_code": "012",
          "account_type": "checking",
          "account_number": "123456789"
        },
        "description": "Pago proveedor",
        "idempotency_key": "cl-prov-0091"
      }'
    ```

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "b3e1…",
      "country": "CL",
      "currency": "CLP",
      "method": "bank_transfer",
      "local_amount": "100000",
      "fx_rate": "925.69",
      "usdt_amount": "108.027528",
      "fee": "0.300000",
      "total_debit": "108.327528",
      "status": "processing"
    }
    ```

    El catálogo de bancos (`GET /v1/payouts/banks?country=CL`) da los
    `bank_code` vigentes.
  </Tab>

  <Tab title="Perú">
    Dos métodos: transferencia bancaria (CCI interbancario) y **Yape** (al
    número de teléfono).

    <CodeGroup>
      ```bash bank_transfer (CCI) theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "PE",
          "currency": "PEN",
          "method": "bank_transfer",
          "amount": "1000.00",
          "beneficiary": {
            "name": "Rosa Álvarez Díaz",
            "account_number": "00219300123456789012"
          },
          "idempotency_key": "pe-cci-3310"
        }'
      ```

      ```bash yape (teléfono) theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "PE",
          "currency": "PEN",
          "method": "yape",
          "amount": "150.00",
          "beneficiary": {
            "name": "Luis Ramos Vega",
            "phone": "51987654321"
          },
          "idempotency_key": "pe-yape-8874"
        }'
      ```
    </CodeGroup>

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "c7a2…",
      "country": "PE",
      "currency": "PEN",
      "method": "yape",
      "local_amount": "150.00",
      "fx_rate": "3.40",
      "usdt_amount": "44.117648",
      "fee": "0.300000",
      "total_debit": "44.417648",
      "status": "completed"
    }
    ```

    En `yape` el teléfono va en formato `51XXXXXXXXX` (11 dígitos con código de
    país). El resultado suele ser síncrono.
  </Tab>

  <Tab title="México">
    SPEI en MXN, a CLABE (18 dígitos) o a tarjeta de débito:

    <CodeGroup>
      ```bash CLABE theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "MX",
          "currency": "MXN",
          "method": "bank_transfer",
          "amount": "1500.00",
          "beneficiary": {
            "name": "María López",
            "account_type": "clabe",
            "account_number": "012180001234567895"
          },
          "idempotency_key": "mx-clabe-8841"
        }'
      ```

      ```bash Tarjeta de débito theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "MX",
          "currency": "MXN",
          "method": "bank_transfer",
          "amount": "800.00",
          "beneficiary": {
            "name": "Jorge Herrera",
            "account_type": "debit_card",
            "account_number": "4152313412341234",
            "bank_code": "40012"
          },
          "idempotency_key": "mx-card-1102"
        }'
      ```
    </CodeGroup>

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "0d4f…",
      "country": "MX",
      "currency": "MXN",
      "method": "bank_transfer",
      "local_amount": "1500.00",
      "fx_rate": "17.50",
      "usdt_amount": "85.714286",
      "fee": "0.300000",
      "total_debit": "86.014286",
      "status": "processing"
    }
    ```

    Con CLABE el banco destino se deriva de los primeros dígitos; con tarjeta
    es obligatorio `bank_code`.
  </Tab>

  <Tab title="Venezuela">
    Dos métodos: **Pago Móvil** (teléfono + banco + cédula) y transferencia
    bancaria (cuenta de 20 dígitos):

    <CodeGroup>
      ```bash pago_movil theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "VE",
          "currency": "VES",
          "method": "pago_movil",
          "amount": "2000.00",
          "beneficiary": {
            "phone": "04141234567",
            "bank_code": "0102",
            "document_value": "V12345678"
          },
          "idempotency_key": "ve-pm-5567"
        }'
      ```

      ```bash bank_transfer theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "VE",
          "currency": "VES",
          "method": "bank_transfer",
          "amount": "5000.00",
          "beneficiary": {
            "name": "Carmen Delgado",
            "account_number": "01020123456789012345",
            "document_value": "V87654321"
          },
          "idempotency_key": "ve-bank-7810"
        }'
      ```
    </CodeGroup>

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "e9b4…",
      "country": "VE",
      "currency": "VES",
      "method": "pago_movil",
      "local_amount": "2000.00",
      "fx_rate": "666.00",
      "usdt_amount": "3.003004",
      "fee": "0.300000",
      "total_debit": "3.303004",
      "status": "completed"
    }
    ```

    `bank_code` usa códigos SUDEBAN; en `bank_transfer` puede derivarse de los
    primeros 4 dígitos de la cuenta.
  </Tab>

  <Tab title="Bolivia">
    Transferencia ACH en BOB o USD (además del
    [payout QR](#payout-qr)):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "country": "BO",
        "currency": "BOB",
        "method": "bank_transfer",
        "amount": "1382.00",
        "beneficiary": {
          "name": "Juan Quispe Mamani",
          "tax_id": "4567890",
          "bank_code": "1016",
          "account_number": "1234567890"
        },
        "idempotency_key": "bo-ach-2204"
      }'
    ```

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "f2c8…",
      "country": "BO",
      "currency": "BOB",
      "method": "bank_transfer",
      "local_amount": "1382.00",
      "fx_rate": "6.91",
      "usdt_amount": "200.000000",
      "fee": "0.300000",
      "total_debit": "200.300000",
      "status": "processing"
    }
    ```

    Para USD envía `currency: "USD"` con la misma estructura.
  </Tab>

  <Tab title="Brasil">
    PIX por llave (además del
    [QR PIX](#payout-qr)):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "country": "BR",
        "currency": "BRL",
        "method": "pix",
        "amount": "350.00",
        "beneficiary": {
          "name": "João da Silva",
          "tax_id": "123.456.789-09",
          "pix_key_type": "cpf",
          "pix_key": "12345678909"
        },
        "idempotency_key": "br-pix-3321"
      }'
    ```

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "a6d1…",
      "country": "BR",
      "currency": "BRL",
      "method": "pix",
      "local_amount": "350.00",
      "fx_rate": "5.13",
      "usdt_amount": "68.226121",
      "fee": "0.300000",
      "total_debit": "68.526121",
      "status": "processing"
    }
    ```

    `pix_key_type`: `cpf`, `cnpj`, `phone`, `email` o `evp` (llave aleatoria).

    **PIX a cuenta (sin llave)** — si el beneficiario no tiene o no entrega su
    llave PIX, envía sus datos bancarios; llega igual de rápido (mismo riel
    PIX, 24/7):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "country": "BR",
        "currency": "BRL",
        "method": "pix",
        "amount": "350.00",
        "beneficiary": {
          "name": "Empresa Exemplo Ltda",
          "tax_id": "19.385.062/0001-20",
          "bank_code": "45678923",
          "branch_code": "1",
          "account_number": "765432",
          "account_type": "CACC"
        },
        "idempotency_key": "br-pix-acct-3322"
      }'
    ```

    * `bank_code` es el **ISPB** del banco destino (8 dígitos), `branch_code`
      la agencia y `account_type` el tipo de cuenta (`CACC` corriente —
      default —, `SVGS` ahorro, `TRAN` cuenta de pago, `SLRY` salario).
    * El estado final llega por el webhook `payout_status_changed`
      (conciliación continua contra el rail); consulta puntual con
      `GET /v1/payouts/{id}`.
  </Tab>

  <Tab title="Ecuador">
    Remesas en **USD** (1 a 10.000 por operación, máx. 2 decimales) con cuatro
    métodos: transferencia bancaria, billetera **DE UNA** (por celular),
    retiro en **ventanilla** (`cash_pickup`) y retiro en **corresponsal no
    bancario** (`cnb`). Es un corredor de remesas: además del beneficiario, el
    rail exige los datos del **ordenante** (quien envía), que van planos
    dentro del mismo `beneficiary` con prefijo `sender_*`.

    <CodeGroup>
      ```bash bank_transfer (a cuenta) theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "EC",
          "currency": "USD",
          "method": "bank_transfer",
          "amount": "250.00",
          "beneficiary": {
            "name": "Carlos Andrade Vera",
            "document_value": "1712345678",
            "account_number": "2203456789",
            "sender_name": "Ana Torres Silva",
            "sender_document_value": "V23456789",
            "sender_country": "US"
          },
          "idempotency_key": "ec-bank-4471"
        }'
      ```

      ```bash deuna (billetera) theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "EC",
          "currency": "USD",
          "method": "deuna",
          "amount": "80.00",
          "beneficiary": {
            "name": "Lucia Paredes Mora",
            "document_value": "0923456781",
            "phone": "0998765432",
            "sender_name": "Ana Torres Silva"
          },
          "idempotency_key": "ec-deuna-5520"
        }'
      ```

      ```bash cash_pickup (ventanilla) theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "EC",
          "currency": "USD",
          "method": "cash_pickup",
          "amount": "120.00",
          "beneficiary": {
            "name": "Miguel Zambrano Loor",
            "document_value": "1309876543",
            "sender_name": "Ana Torres Silva"
          },
          "idempotency_key": "ec-cash-6612"
        }'
      ```

      ```bash cnb (corresponsal) theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.qbank.cl/platform/v1/payouts \
        -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "EC",
          "currency": "USD",
          "method": "cnb",
          "amount": "60.00",
          "beneficiary": {
            "name": "Rosa Cedeño Vera",
            "document_value": "0801234567",
            "sender_name": "Ana Torres Silva"
          },
          "idempotency_key": "ec-cnb-7703"
        }'
      ```
    </CodeGroup>

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "9f3a…",
      "country": "EC",
      "currency": "USD",
      "method": "bank_transfer",
      "local_amount": "250.00",
      "fx_rate": "1",
      "usdt_amount": "250.000000",
      "fee": "0.300000",
      "total_debit": "250.300000",
      "status": "processing"
    }
    ```

    * Ecuador está dolarizado: la moneda local ES el USD (`fx_rate: "1"`).
    * `document_value` es la cédula del beneficiario; `document_type` acepta
      `IDCD` (cédula, default), `CCPT` (pasaporte) o `TXID` (RUC).
    * En `bank_transfer`, si omites `bank_code` la cuenta es del banco emisor
      del corredor; para **otro banco** envía el `bank_code` del catálogo
      (`GET /v1/payouts/banks?country=EC`) más `account_type`
      (`checking` o `savings`).
    * Nombres estructurados opcionales (`given_name`, `middle_name`,
      `first_surname`, `second_surname` y sus pares `sender_*`): si los
      tienes, envíalos — mandan sobre la separación automática de `name`.
    * El estado final llega por webhook `payout_status_changed`
      (con conciliación periódica de respaldo).
  </Tab>

  <Tab title="Paraguay">
    Transferencia bancaria en PYG:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "country": "PY",
        "currency": "PYG",
        "method": "bank_transfer",
        "amount": "500000",
        "beneficiary": {
          "name": "Sofía Benítez",
          "tax_id": "4123456",
          "bank_code": "0011",
          "account_number": "600123456"
        },
        "idempotency_key": "py-bank-9917"
      }'
    ```

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "payout_id": "d4e7…",
      "country": "PY",
      "currency": "PYG",
      "method": "bank_transfer",
      "local_amount": "500000",
      "fx_rate": "6055.76",
      "usdt_amount": "82.566020",
      "fee": "0.300000",
      "total_debit": "82.866020",
      "status": "processing"
    }
    ```

    `name` acepta hasta 35 caracteres en este corredor.
  </Tab>
</Tabs>

## Payout QR

En Bolivia (QR interoperable local) y en Brasil (**QR PIX**, incluido el
código "copia e cola") también puedes **pagar a un QR de cobro** en dos
pasos: escanear y confirmar. El escaneo es **gratis**; solo se cobra al
confirmar, igual que un payout normal (tu tasa + fijo). Si no envías
`country`/`currency`, se asume Bolivia (BOB); para Brasil envía
`country: "BR"` y `currency: "BRL"`.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    scan["1. POST qr/scan<br/>(gratis)"] --> datos["Datos del destinatario<br/>+ provider_reference"]
    datos --> confirmaUsuario{"¿El usuario<br/>confirma?"}
    confirmaUsuario -->|"Sí"| confirm["2. POST qr/confirm<br/>(se cobra: tu tasa + fijo)"]
    confirmaUsuario -->|"No"| fin["Nada se cobró"]
    confirm --> resultado{"Resultado<br/>síncrono"}
    resultado -->|"completed"| pagado["Pagado — débito consumido"]
    resultado -->|"failed"| refund["Reembolso automático<br/>completo"]
```

### 1. Escanea el QR (gratis)

<Tabs>
  <Tab title="Bolivia">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/scan \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "qr_payload": "<contenido del QR>",
        "currency": "BOB"
      }'
    ```

    Devuelve los datos del destinatario para que el usuario confirme a quién le
    paga:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "scan_id": "…",
      "provider_reference": "…",
      "beneficiary_name": "Juan Quispe",
      "destination_account": "…",
      "amount": "700.00",
      "currency": "BOB",
      "glosa": "",
      "status": "…"
    }
    ```
  </Tab>

  <Tab title="Brasil (QR PIX)">
    `qr_payload` acepta el contenido crudo del QR PIX (BR Code EMV) **o el
    código "copia e cola"** — son el mismo string:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/scan \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "country": "BR",
        "currency": "BRL",
        "qr_payload": "00020126360014br.gov.bcb.pix0114+5511998765432520400005303986540575.005802BR5913LOJA DA MARIA6009SAO PAULO62110507PED423163040BF9"
      }'
    ```

    El escaneo decodifica el BR Code localmente (valida su checksum) y
    devuelve la llave PIX de destino, el nombre del comercio y el monto si el
    QR lo trae fijo:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "scan_id": "PIXSCAN-…",
      "provider_reference": "<el mismo payload EMV>",
      "beneficiary_name": "LOJA DA MARIA",
      "destination_account": "+5511998765432",
      "amount": "75.00",
      "currency": "BRL",
      "glosa": "",
      "status": "scanned"
    }
    ```

    * `amount` vacío = QR de **monto abierto**: tú decides cuánto pagar en el
      confirm. Con monto fijo, el confirm debe enviar exactamente ese monto.
    * Se soportan QR PIX **estáticos** (los impresos/reutilizables, con la
      llave embebida). Un QR **dinámico** (payload con URL del PSP en vez de
      llave) responde `400` con el mensaje
      `dynamic pix qr codes are not supported yet` —   pídele al beneficiario su
      llave PIX y usa el método [`pix`](#ejemplos-por-pais).
    * Un payload alterado o incompleto responde `400` (checksum CRC inválido).
  </Tab>
</Tabs>

### 2. Confirma el pago (se cobra aquí)

<Tabs>
  <Tab title="Bolivia">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/confirm \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "provider_reference": "<del scan>",
        "amount": "700.00",
        "currency": "BOB",
        "description": "Pago QR almuerzo",
        "idempotency_key": "qr-2026-07-07-a"
      }'
    ```
  </Tab>

  <Tab title="Brasil (QR PIX)">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/confirm \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "country": "BR",
        "currency": "BRL",
        "provider_reference": "<del scan>",
        "amount": "75.00",
        "description": "Pedido 4231",
        "idempotency_key": "qr-br-2026-07-16-a"
      }'
    ```

    * `amount` siempre es obligatorio: si el QR trae monto fijo debe coincidir
      exacto — si no, recibes `422` con el payout en `status: failed`
      (`status_message: "amount mismatch: the qr requires exactly 75.00 BRL"`)
      y el **reembolso ya aplicado**; corrige el monto y reintenta con clave
      nueva. Si es de monto abierto, el que envíes es el que se paga.
    * Un QR PIX **estático es reutilizable por diseño** (el QR impreso de un
      comercio se paga muchas veces): puedes pagarlo de nuevo con una
      `idempotency_key` distinta. Un intento fallido **no inutiliza el QR**.
    * El pago sale por el mismo riel PIX del método `pix` (24/7); el `txid`
      del QR viaja con el pago para que el comercio concilie automático.
  </Tab>
</Tabs>

* Se debita `usdt_amount + fijo` a **tu tasa**, igual que un
  `bank_transfer`.
* El resultado es **síncrono**: la respuesta ya trae el estado final
  (`completed` o `failed` con reembolso automático) — sin esperas.
* Reintentos con la misma `idempotency_key` devuelven el payout original.
  En Bolivia la referencia del scan es de un solo uso (un QR escaneado solo
  puede pagarse una vez); en Brasil el QR PIX estático es reutilizable y
  cada pago lleva su propia clave.

## Errores frecuentes

| HTTP | `error`                        | Qué hacer                                                                                                                                                                                                         |
| ---- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `idempotency_key_required`     | Envía la clave en body o header                                                                                                                                                                                   |
| 400  | `beneficiary_required`         | Incluye el objeto `beneficiary`                                                                                                                                                                                   |
| 402  | `insufficient_funds`           | Fondea la cuenta; el payout no se creó                                                                                                                                                                            |
| 403  | `account_blocked`              | La cuenta no está activa; contacta al equipo de CBPay                                                                                                                                                             |
| 403  | `service_disabled`             | Payouts no está habilitado para tu cuenta — ver [servicios](/es/conceptos/servicios)                                                                                                                              |
| 403  | `compliance_hold`              | El payout fue retenido por los controles de cumplimiento de la plataforma y NO se creó (sin débito). Por política no se informa la razón exacta — contacta a soporte con el timestamp; ver [errores](/es/errores) |
| 422  | `currency_not_supported`       | No hay tasa FX para esa moneda                                                                                                                                                                                    |
| 422  | (payout con `status: failed`)  | El corredor rechazó los datos; el débito ya fue reembolsado — corrige `beneficiary` y reintenta con clave nueva                                                                                                   |
| 503  | `channel_unavailable`          | El canal de pago está temporalmente no disponible; reintenta más tarde con la MISMA `idempotency_key`                                                                                                             |
| 503  | `compliance_check_unavailable` | La verificación de cumplimiento no se pudo evaluar; el payout NO se creó — reintenta con la MISMA `idempotency_key`                                                                                               |

## Rechazo inmediato vs fallo posterior

Si el procesador rechaza el payout al crearlo, recibes `422` con el objeto
en `status: failed` y el reembolso ya aplicado. Si falla después (por
ejemplo, cuenta destino inexistente detectada por el banco), te llega el
webhook con `status: failed` y el reembolso automático en ese momento.

### Cómo leer `status_code` en un payout fallido

| `status_code`         | Significado                                                                                              | Acción                                                                       |
| --------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `core_rejected`       | El procesador rechazó la operación al crearla (datos del beneficiario inválidos, corredor no disponible) | Lee `status_message`, corrige y crea un payout nuevo con clave nueva         |
| `channel_unavailable` | El canal de pago quedó temporalmente no disponible                                                       | Reintenta más tarde; el reembolso (si hubo débito) ya está aplicado          |
| *otro código*         | Rechazo posterior del riel bancario (p. ej. cuenta destino cerrada)                                      | Igual: corrige los datos y crea una operación nueva                          |
| *(vacío)*             | Fallo genérico del corredor                                                                              | Revisa `status_message`; si no es claro, contacta soporte con el `payout_id` |

En todos los casos el reembolso ya está aplicado — verifícalo con la
entrada `payout_refund` en
[movimientos](/es/conceptos/movimientos-y-conciliacion).

<Note>
  Un payout en `processing` no se puede cancelar por API: el rail ya lo tiene.
  Espera el estado final por webhook o `GET` — llega siempre, con reembolso
  automático si falla.
</Note>