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

> 从您的 USDT 余额扣款，向本地银行账户发送法币

出金（payout）会以当地货币向目的国的银行账户汇出资金。金额按**您账户的
汇率**（即 `GET /v1/rates` 返回的汇率）从当地货币折算为 USDT，并从您的
余额中扣除 `usdt_amount + fee`（如已配置固定费用）。

以下是完整的生命周期，包括每一步中您的余额发生的变化：

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    autonumber
    participant App as 您的应用
    participant CB as CBPay
    participant Rail as 本地银行通道
    App->>CB: POST /v1/payouts (idempotency_key)
    CB->>CB: 按您的汇率折算并扣除<br/>usdt_amount + fee（available → held）
    CB-->>App: 202 processing (fx_rate, total_debit)
    CB->>Rail: 以当地货币发放
    alt 资金到账
        Rail-->>CB: 已确认
        CB->>CB: 消耗冻结金额 — 最终状态
        CB-->>App: Webhook payout_status_changed (completed)
    else 通道拒绝
        Rail-->>CB: 已拒绝
        CB->>CB: 将全部扣款退回 available
        CB-->>App: Webhook payout_status_changed (failed + status_code)
    end
```

## 1. 查询可用通道

国家、货币和方式由 CBPay 定义。请始终查询目录：

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

可用的通道和方式：

| 国家   | 货币        | 方式                                                 |
| ---- | --------- | -------------------------------------------------- |
| 智利   | CLP       | `bank_transfer`                                    |
| 秘鲁   | PEN       | `bank_transfer`、`yape`                             |
| 墨西哥  | MXN       | `bank_transfer`（SPEI：CLABE 或借记卡）                   |
| 委内瑞拉 | VES       | `bank_transfer`、`pago_movil`                       |
| 玻利维亚 | BOB / USD | `bank_transfer`、`qr`（参见 [QR 出金](#qr-出金)）           |
| 巴西   | BRL       | `pix`（按密钥或到账户）、`qr`（PIX 二维码 —— 参见 [QR 出金](#qr-出金)） |
| 厄瓜多尔 | USD       | `bank_transfer`、`deuna`、`cash_pickup`、`cnb`        |
| 巴拉圭  | PYG       | `bank_transfer`                                    |

可用性可能变化；目录（`GET /v1/payouts/methods`）始终是唯一可信来源。
如果某个国家只有一种方式，`method` 为可选。每种方式的计费方式相同：
您的汇率 + 固定费用。

对于银行转账，您还需要银行目录（收款人的 `bank_code` 即来自这里）：

```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. 创建出金

```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": "Maria Lopez",
      "account_type": "clabe",
      "account_number": "012180001234567895"
    },
    "description": "Invoice 8841",
    "idempotency_key": "invoice-8841"
  }'
```

<Warning>
  `beneficiary` 是一个键/值对象，其必填字段取决于具体通道（智利需要 RUT
  和银行，墨西哥需要 CLABE，秘鲁需要 CCI，巴西需要 PIX 密钥等）。方式目录
  对每个通道都有说明。
</Warning>

<Note>
  每笔出金都会自动将收款人保存为[联系人](/zh/guides/contacts)
  （发送 `"save_contact": false` 可跳过）。若要再次向其付款而无需重新输入
  资料，请发送 `"beneficiary_contact_id"` 代替 `beneficiary` —— 系统将使用
  其在该国家和方式下最近保存的收款人信息（若不存在则返回
  `422 no_saved_destination`）。
</Note>

响应 `202 Accepted`：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "payout_id": "0d4f…",
  "account_id": "…",
  "idempotency_key": "invoice-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"
}
```

此时您的余额已反映该笔扣款：`total_debit` 已从 `available` 转入
`held`（在 `settlement_asset` 对应的余额上）。

### 从其他余额支付（`settlement_asset`）

默认情况下，扣款来自您的默认结算资产（除非您通过 `PUT /v1/settlement`
更改，否则为 USDT）。若要让单笔操作从其他余额支付，请在请求中加入
`settlement_asset`。示例：一笔 100,000 CLP 的出金从 BTC 余额支付，会经过
四次转换，全部记录在响应中：

1. **CLP → USDT**，按您的汇率：`100000 / 950.25 = 105.235465 USDT`。
2. **+ 固定费用**：`105.235465 + 0.30 = 105.535465 USDT`（`total_debit`）。
3. **USDT → BTC**，按实际结算价格（`settlement_rate`
   `109029.34070000`）：`105.535465 / 109029.3407 = 0.00096795 BTC`
   （向上取整到聪）。
4. **以 BTC 扣款并冻结**：`settlement_amount` `0.00096795` 从您的 BTC
   余额中扣除；收款人照常收到其 100,000 CLP，分毫不差。

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

如果出金失败，将向您的 BTC 余额退回精确的 `settlement_amount` ——
绝不重新报价。如果当时 BTC/GOLD 的执行价格不可用，您会收到
`503 pricing_unavailable`；波动性资产还有单笔操作限额
（`422 settlement_limit_exceeded`；可在 `GET /v1/settlement` 中查询）。

## 3. 接收最终状态

订阅 `payout_status_changed` 事件（[webhooks](/zh/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`**：资金已到账；冻结金额被消耗。
* **`failed`**：全部扣款自动退回（在您的账本中记为
  `payout_refund`）。

您也可以随时查询：

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

### 出金状态

| 状态           | 含义           | 您的余额                |
| ------------ | ------------ | ------------------- |
| `processing` | 已受理，正在本地通道执行 | 扣款冻结在 `held` 中      |
| `completed`  | 资金已到达收款人     | 冻结金额被消耗 —— 最终状态     |
| `failed`     | 通道拒绝或执行失败    | **自动全额退款**（金额 + 费用） |

## 查询与历史记录

每笔出金都可以单独读取，列表接口支持筛选：

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

# History with filters: dates, status and pagination
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` 使用 `YYYY-MM-DD`（UTC，两端均含）；日期无效时返回
`400 invalid_range`。

## 各国示例

每条通道均附有其精确的 `beneficiary`、完整的请求和真实的响应。汇率
（`fx_rate`）仅供参考 —— 实际始终采用 `GET /v1/rates` 返回的您账户的
汇率；扣款为 `usdt_amount + fee`（固定费用，如已配置；此处为 `0.30`）。

### 各通道的收款人字段

| 国家 | 方式                    | `beneficiary` 字段                                                                                          |
| -- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| CL | `bank_transfer`       | `name`、`tax_id`（RUT）、`bank_code`、`account_type`、`account_number`                                          |
| PE | `bank_transfer`       | `name`、`account_number`（20 位 CCI）                                                                         |
| PE | `yape`                | `name`、`phone`（`51XXXXXXXXX`）                                                                             |
| MX | `bank_transfer`       | `name`、`account_type`（`clabe`/`debit_card`）、`account_number`（银行卡还需 `bank_code`）                           |
| VE | `pago_movil`          | `phone`、`bank_code`（SUDEBAN）、`document_value`                                                             |
| VE | `bank_transfer`       | `name`、`account_number`（20 位）、`document_value`                                                            |
| BO | `bank_transfer`       | `name`、`tax_id`、`bank_code`、`account_number`                                                              |
| BR | `pix`                 | `name`、`tax_id` +（`pix_key` 和 `pix_key_type`）或（`bank_code` ISPB、`branch_code`、`account_number`）           |
| EC | `bank_transfer`       | `name`、`document_value`（身份证 cédula）、`sender_name`、`account_number`（转到其他银行还需 `bank_code` 和 `account_type`） |
| EC | `deuna`               | `name`、`document_value`、`sender_name`、`phone`（钱包手机号）                                                      |
| EC | `cash_pickup` / `cnb` | `name`、`document_value`、`sender_name` — 收款人凭证件领取现金                                                        |
| PY | `bank_transfer`       | `name`（最多 35 个字符）、`tax_id`、`bank_code`、`account_number`                                                   |

<Tabs>
  <Tab title="智利">
    以 CLP 进行银行转账。需要 RUT、银行和账户：

    ```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": "Supplier payment",
        "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"
    }
    ```

    银行目录（`GET /v1/payouts/banks?country=CL`）列出当前有效的
    `bank_code` 值。
  </Tab>

  <Tab title="秘鲁">
    两种方式：银行转账（跨行 CCI）和 **Yape**（转到手机号码）。

    <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 Alvarez Diaz",
            "account_number": "00219300123456789012"
          },
          "idempotency_key": "pe-cci-3310"
        }'
      ```

      ```bash yape (phone) 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"
    }
    ```

    对于 `yape`，手机号码使用 `51XXXXXXXXX` 格式（含国家代码共 11 位）。
    结果通常是同步返回的。
  </Tab>

  <Tab title="墨西哥">
    以 MXN 进行 SPEI 转账，转到 CLABE（18 位）或借记卡：

    <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": "Maria Lopez",
            "account_type": "clabe",
            "account_number": "012180001234567895"
          },
          "idempotency_key": "mx-clabe-8841"
        }'
      ```

      ```bash Debit card 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"
    }
    ```

    使用 CLABE 时，目标银行由其前几位数字推导；使用银行卡时，必须提供
    `bank_code`。
  </Tab>

  <Tab title="委内瑞拉">
    两种方式：**Pago Móvil**（手机号 + 银行 + 证件）和银行转账
    （20 位账户）：

    <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` 使用 SUDEBAN 代码；对于 `bank_transfer`，可由账号的前 4 位
    数字推导。
  </Tab>

  <Tab title="玻利维亚">
    以 BOB 或 USD 进行 ACH 转账（此外还有 [QR](#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"
    }
    ```

    如需 USD，请发送 `currency: "USD"`，结构相同。
  </Tab>

  <Tab title="巴西">
    按密钥进行 PIX 转账（此外还有 [PIX QR](#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` 或 `evp`（随机密钥）。

    **PIX 转账到账户（无密钥）** —— 当收款人没有（或不愿提供）PIX 密钥时，
    可发送其银行账户信息；到账同样迅速（同一 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` 是目标银行的 **ISPB**（8 位），`branch_code` 是分行号，
      `account_type` 是账户类型（`CACC` 活期 —— 默认 ——、`SVGS` 储蓄、
      `TRAN` 支付账户、`SLRY` 工资账户）。
    * 最终状态通过 `payout_status_changed` webhook 送达（与通道持续对账）；
      也可随时使用 `GET /v1/payouts/{id}` 查询。
  </Tab>

  <Tab title="厄瓜多尔">
    以 **USD** 汇出汇款（每笔 1 至 10,000，最多 2 位小数），支持四种方式：
    银行转账、**DE UNA** 钱包（按手机号）、**柜台取现**（`cash_pickup`）和
    **非银行代理点取现**（`cnb`）。这是一个汇款通道：除收款人外，通道还
    要求提供**汇款人**（付款发起方）的信息，以 `sender_*` 前缀平铺在同一个
    `beneficiary` 对象中。

    <CodeGroup>
      ```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": "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（钱包） 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（柜台） 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（代理点） 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"
    }
    ```

    * 厄瓜多尔为美元化经济体：当地货币就是美元（`fx_rate: "1"`）。
    * `document_value` 为收款人的身份证号（cédula）；`document_type` 接受
      `IDCD`（身份证，默认）、`CCPT`（护照）或 `TXID`（RUC）。
    * 在 `bank_transfer` 中，省略 `bank_code` 表示账户属于通道的发卡银行；
      转到**其他银行**时需发送目录中的 `bank_code`
      （`GET /v1/payouts/banks?country=EC`）以及 `account_type`
      （`checking` 或 `savings`）。
    * 可选的结构化姓名字段（`given_name`、`middle_name`、`first_surname`、
      `second_surname` 及其 `sender_*` 对应字段）：如有请发送 —— 它们优先
      于对 `name` 的自动拆分。
    * 最终状态通过 `payout_status_changed` webhook 送达（并有周期性对账
      作为兜底）。
  </Tab>

  <Tab title="巴拉圭">
    以 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": "Sofia Benitez",
          "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` 最多接受 35 个字符。
  </Tab>
</Tabs>

## QR 出金

在玻利维亚（本地互操作 QR 标准）和巴西（**PIX 二维码**，包括
"copia e cola" 代码），您还可以分两步**支付收款二维码**：扫码与确认。
扫码**免费**；只在确认时收费，与普通出金完全相同（您的汇率 + 固定
费用）。如未提供 `country`/`currency`，默认按玻利维亚（BOB）处理；
巴西请发送 `country: "BR"` 和 `currency: "BRL"`。

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    scan["1. POST qr/scan<br/>（免费）"] --> data["收款方信息<br/>+ provider_reference"]
    data --> userConfirms{"用户是否<br/>确认？"}
    userConfirms -->|"是"| confirm["2. POST qr/confirm<br/>（收费：您的汇率 + 固定费用）"]
    userConfirms -->|"否"| done["未产生任何费用"]
    confirm --> result{"同步<br/>结果"}
    result -->|"completed"| paid["已支付 — 扣款被消耗"]
    result -->|"failed"| refund["自动<br/>全额退款"]
```

### 1. 扫描二维码（免费）

<Tabs>
  <Tab title="玻利维亚">
    ```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": "<QR content>",
        "currency": "BOB"
      }'
    ```

    返回收款方的信息，以便用户确认付款对象：

    ```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="巴西（PIX 二维码）">
    `qr_payload` 接受 PIX 二维码的原始内容（EMV BR Code）**或
    "copia e cola" 代码** —— 二者是同一个字符串：

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

    扫描会在本地解码 BR Code（校验其校验和），返回目标 PIX 密钥、商户
    名称，以及二维码携带固定金额时的金额：

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

    * `amount` 为空表示**开放金额**二维码：由您在确认步骤决定支付多少。
      固定金额时，确认必须发送完全一致的金额。
    * 支持**静态** PIX 二维码（印刷/可重复使用、密钥内嵌的那种）。
      **动态**二维码（payload 携带 PSP 的 URL 而非密钥）会返回 `400`
      和 `dynamic pix qr codes are not supported yet` —— 请向收款方索取其
      PIX 密钥并使用 [`pix`](#各国示例) 方法。
    * 被篡改或截断的 payload 会返回 `400`（CRC 校验和无效）。
  </Tab>
</Tabs>

### 2. 确认支付（此步收费）

<Tabs>
  <Tab title="玻利维亚">
    ```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": "<from the scan>",
        "amount": "700.00",
        "currency": "BOB",
        "description": "QR lunch payment",
        "idempotency_key": "qr-2026-07-07-a"
      }'
    ```
  </Tab>

  <Tab title="巴西（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": "<from the scan>",
        "amount": "75.00",
        "description": "Order 4231",
        "idempotency_key": "qr-br-2026-07-16-a"
      }'
    ```

    * `amount` 始终必填：固定金额二维码必须完全一致 —— 否则返回 `422`，
      出金处于 `status: failed`（`status_message: "amount mismatch: the qr
      requires exactly 75.00 BRL"`），且**退款已自动完成**；修正金额后用
      新的键重试。开放金额二维码则按您发送的金额支付。
    * **静态 PIX 二维码天生可复用**（商户打印的二维码会被支付多次）：
      可以用不同的 `idempotency_key` 再次支付。失败的尝试**不会作废该
      二维码**。
    * 付款走与 `pix` 方法相同的 PIX 通道（24/7）；二维码中的 `txid`
      会随付款传递，便于商户自动对账。
  </Tab>
</Tabs>

* 按**您的汇率**扣除 `usdt_amount + 固定费用`，与 `bank_transfer`
  完全一致。
* 结果为**同步**返回：响应中已包含最终状态（`completed`，或 `failed`
  并自动退款）—— 无需等待。
* 使用相同 `idempotency_key` 重试会返回原始出金。玻利维亚的扫码引用
  为一次性（已扫描的二维码只能支付一次）；巴西的静态 PIX 二维码可
  复用，每笔支付携带自己的键。

## 常见错误

| HTTP | `error`                        | 应对方式                                                                |
| ---- | ------------------------------ | ------------------------------------------------------------------- |
| 400  | `idempotency_key_required`     | 在请求体或请求头中发送该键                                                       |
| 400  | `beneficiary_required`         | 包含 `beneficiary` 对象                                                 |
| 402  | `insufficient_funds`           | 为账户充值；该出金未被创建                                                       |
| 403  | `account_blocked`              | 账户未处于激活状态；请联系 CBPay 团队                                              |
| 403  | `service_disabled`             | 您的账户未启用出金服务 —— 参见[服务](/zh/concepts/services)                        |
| 403  | `compliance_hold`              | 该出金被平台的合规控制拦截，未被创建（未扣款）。按政策不披露具体原因 —— 请携带时间戳联系支持；参见[错误](/zh/errors) |
| 422  | `currency_not_supported`       | 该货币没有可用的外汇汇率                                                        |
| 422  | （出金处于 `status: failed`）        | 通道拒绝了该数据；扣款已退回 —— 修正 `beneficiary` 后使用新的键重试                         |
| 503  | `channel_unavailable`          | 出金通道暂时不可用；请稍后使用**相同的** `idempotency_key` 重试                         |
| 503  | `compliance_check_unavailable` | 合规校验暂时无法完成；该出金未被创建 —— 请使用**相同的** `idempotency_key` 重试               |

## 立即拒绝与后续失败

如果处理方在创建时就拒绝了出金，您会收到 `422`，对象处于
`status: failed`，且退款已经完成。如果之后才失败（例如目标账户不存在），
webhook 会以 `status: failed` 送达，自动退款也在那一刻发生。

### 解读失败出金的 `status_code`

| `status_code`         | 含义                           | 处理方式                                           |
| --------------------- | ---------------------------- | ---------------------------------------------- |
| `core_rejected`       | 处理方在创建时拒绝了该操作（收款人数据无效、通道不可用） | 阅读 `status_message`，修正数据后使用新的键创建新出金            |
| `channel_unavailable` | 出金通道暂时不可用                    | 稍后重试；退款（如已扣款）已经完成                              |
| *其他代码*                | 银行通道在后续阶段拒绝（例如目标账户已注销）       | 同上：修正数据后创建新的操作                                 |
| *（空）*                 | 通道的一般性失败                     | 检查 `status_message`；如仍不清楚，请携带 `payout_id` 联系支持 |

无论哪种情况，退款均已完成 —— 可通过
[账户流水](/zh/concepts/movements-reconciliation)中的 `payout_refund`
条目进行核实。

<Note>
  处于 `processing` 状态的出金无法通过 API 取消：通道已经在处理它。请通过
  webhook 或 `GET` 等待最终状态 —— 它一定会到达，失败时会自动退款。
</Note>