出金（Payouts）

出金（payout）会以当地货币向目的国的银行账户汇出资金。金额按您账户的汇率（即 GET /v1/rates 返回的汇率）从当地货币折算为 USDT，并从您的余额中扣除 usdt_amount + fee（如已配置固定费用）。以下是完整的生命周期，包括每一步中您的余额发生的变化：

1. 查询可用通道

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

curl https://api.qbank.cl/platform/v1/payouts/methods \
  -H "Authorization: Bearer <token>"

{
  "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 出金）
巴西	BRL	`pix`（按密钥或到账户）、`qr`（PIX 二维码 —— 参见 QR 出金）
厄瓜多尔	USD	`bank_transfer`、`deuna`、`cash_pickup`、`cnb`
巴拉圭	PYG	`bank_transfer`

可用性可能变化；目录（GET /v1/payouts/methods）始终是唯一可信来源。如果某个国家只有一种方式，method 为可选。每种方式的计费方式相同：您的汇率 + 固定费用。对于银行转账，您还需要银行目录（收款人的 bank_code 即来自这里）：

curl "https://api.qbank.cl/platform/v1/payouts/banks?country=CL" \
  -H "Authorization: Bearer <token>"

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

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

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

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

响应 202 Accepted：

{
  "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 余额支付，会经过四次转换，全部记录在响应中：

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

{
  "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）：

{
  "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）。

您也可以随时查询：

curl https://api.qbank.cl/platform/v1/payouts/0d4f… \
  -H "Authorization: Bearer <token>"

出金状态

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

查询与历史记录

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

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

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

以 CLP 进行银行转账。需要 RUT、银行和账户：

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

{
  "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 值。

两种方式：银行转账（跨行 CCI）和 Yape（转到手机号码）。

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

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

{
  "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 位）。结果通常是同步返回的。

以 MXN 进行 SPEI 转账，转到 CLABE（18 位）或借记卡：

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

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

{
  "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。

两种方式：Pago Móvil（手机号 + 银行 + 证件）和银行转账（20 位账户）：

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

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

{
  "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 位数字推导。

以 BOB 或 USD 进行 ACH 转账（此外还有 QR）：

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

{
  "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"，结构相同。

按密钥进行 PIX 转账（此外还有 PIX QR）：

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

{
  "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 全天候）：

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} 查询。

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

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

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

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

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

{
  "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 送达（并有周期性对账作为兜底）。

以 PYG 进行银行转账：

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

{
  "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 个字符。

QR 出金

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

1. 扫描二维码（免费）

玻利维亚
巴西（PIX 二维码）

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

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

{
  "scan_id": "…",
  "provider_reference": "…",
  "beneficiary_name": "Juan Quispe",
  "destination_account": "…",
  "amount": "700.00",
  "currency": "BOB",
  "glosa": "",
  "status": "…"
}

qr_payload 接受 PIX 二维码的原始内容（EMV BR Code）或 “copia e cola” 代码 —— 二者是同一个字符串：

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 密钥、商户名称，以及二维码携带固定金额时的金额：

{
  "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 校验和无效）。

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

玻利维亚
巴西（PIX 二维码）

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

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 会随付款传递，便于商户自动对账。

按您的汇率扣除 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`	您的账户未启用出金服务 —— 参见服务
403	`compliance_hold`	该出金被平台的合规控制拦截，未被创建（未扣款）。按政策不披露具体原因 —— 请携带时间戳联系支持；参见错误
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` 联系支持

无论哪种情况，退款均已完成 —— 可通过账户流水中的 payout_refund 条目进行核实。

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

开始使用

核心概念

集成流程

产品

集成

资源

出金（Payouts）

1. 查询可用通道

2. 创建出金

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

3. 接收最终状态

出金状态

查询与历史记录

各国示例

各通道的收款人字段

QR 出金

1. 扫描二维码（免费）

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

常见错误

立即拒绝与后续失败

解读失败出金的 `status_code`

​1. 查询可用通道

​2. 创建出金

​从其他余额支付（settlement_asset）

​3. 接收最终状态

​出金状态

​查询与历史记录

​各国示例

​各通道的收款人字段

​QR 出金

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

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

​常见错误

​立即拒绝与后续失败

​解读失败出金的 status_code

1. 查询可用通道

2. 创建出金

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

3. 接收最终状态

出金状态

查询与历史记录

各国示例

各通道的收款人字段

QR 出金

1. 扫描二维码（免费）

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

常见错误

立即拒绝与后续失败

解读失败出金的 `status_code`