curl --request POST \
  --url https://api.qbank.cl/platform/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "供应商付款",
  "idempotency_key": "cl-prov-0091"
}
'

{
  "payout_id": "7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f",
  "account_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "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",
  "beneficiary": {
    "name": "Maria Lopez",
    "account_type": "clabe",
    "account_number": 12180001234567896
  },
  "description": "发票 8841",
  "status": "processing",
  "status_code": "",
  "status_message": "",
  "bank_reference": "",
  "created_at": "2026-07-07T12:00:00Z",
  "updated_at": "2026-07-07T12:00:00Z",
  "idempotency_hit": true
}

{
  "payout_id": "7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f",
  "account_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "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",
  "beneficiary": {
    "name": "Maria Lopez",
    "account_type": "clabe",
    "account_number": 12180001234567896
  },
  "description": "发票 8841",
  "status": "processing",
  "status_code": "",
  "status_message": "",
  "bank_reference": "",
  "created_at": "2026-07-07T12:00:00Z",
  "updated_at": "2026-07-07T12:00:00Z"
}

{
  "error": "invalid_json",
  "message": "request body is not valid JSON: unknown field"
}

{
  "error": "unauthorized",
  "message": "invalid or missing credentials"
}

{
  "error": "insufficient_funds",
  "message": "account balance is not enough for this operation"
}

{
  "error": "account_blocked",
  "message": "account is not active"
}

{
  "payout_id": "7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f",
  "account_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "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",
  "beneficiary": {
    "name": "Maria Lopez",
    "account_type": "clabe",
    "account_number": 12180001234567896
  },
  "description": "发票 8841",
  "status": "failed",
  "status_code": "core_rejected",
  "status_message": "beneficiary account is invalid",
  "bank_reference": "",
  "created_at": "2026-07-07T12:00:00Z",
  "updated_at": "2026-07-07T12:00:00Z"
}

{
  "error": "channel_unavailable",
  "message": "the payout channel is temporarily unavailable, please retry later"
}

创建 payout

向本地银行账户派发法币。本地金额按你账户的汇率(与 GET /v1/rates 返回的相同)转换为 USDT;扣除 usdt_amount 加固定费用(如有配置)并冻结,直到派发完成。若失败,全额退款。

从任意余额支付:默认从你账户的默认结算资产扣款(USDT,除非通过 PUT /v1/settlement 更改)。传 settlement_asset(USDT、USDC、BTC 或 GOLD)可让这笔操作从其他余额支付:USDT 总额按当时的有效结算价格转换为该资产(见 GET /v1/rates 的 settlement 块),扣款、冻结以及失败时的退款都在该资产中且金额完全一致。若 BTC/GOLD 的执行价格不可用,请求返回 503 pricing_unavailable;波动性资产还有单笔限额(422 settlement_limit_exceeded)。

必须提供幂等键(请求体字段或 Idempotency-Key 请求头)。使用相同键重试会返回原始 payout(200 且 idempotency_hit: true)。

POST

payouts

curl --request POST \
  --url https://api.qbank.cl/platform/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "供应商付款",
  "idempotency_key": "cl-prov-0091"
}
'

{
  "payout_id": "7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f",
  "account_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "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",
  "beneficiary": {
    "name": "Maria Lopez",
    "account_type": "clabe",
    "account_number": 12180001234567896
  },
  "description": "发票 8841",
  "status": "processing",
  "status_code": "",
  "status_message": "",
  "bank_reference": "",
  "created_at": "2026-07-07T12:00:00Z",
  "updated_at": "2026-07-07T12:00:00Z",
  "idempotency_hit": true
}

{
  "payout_id": "7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f",
  "account_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "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",
  "beneficiary": {
    "name": "Maria Lopez",
    "account_type": "clabe",
    "account_number": 12180001234567896
  },
  "description": "发票 8841",
  "status": "processing",
  "status_code": "",
  "status_message": "",
  "bank_reference": "",
  "created_at": "2026-07-07T12:00:00Z",
  "updated_at": "2026-07-07T12:00:00Z"
}

{
  "error": "invalid_json",
  "message": "request body is not valid JSON: unknown field"
}

{
  "error": "unauthorized",
  "message": "invalid or missing credentials"
}

{
  "error": "insufficient_funds",
  "message": "account balance is not enough for this operation"
}

{
  "error": "account_blocked",
  "message": "account is not active"
}

{
  "payout_id": "7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f",
  "account_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "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",
  "beneficiary": {
    "name": "Maria Lopez",
    "account_type": "clabe",
    "account_number": 12180001234567896
  },
  "description": "发票 8841",
  "status": "failed",
  "status_code": "core_rejected",
  "status_message": "beneficiary account is invalid",
  "bank_reference": "",
  "created_at": "2026-07-07T12:00:00Z",
  "updated_at": "2026-07-07T12:00:00Z"
}

{
  "error": "channel_unavailable",
  "message": "the payout channel is temporarily unavailable, please retry later"
}

授权

Authorization

string

header

必填

会话 JWT(来自注册/登录)或 API key(pk_...)。也接受 X-API-Key: <token> 作为替代请求头。

请求头

Idempotency-Key

string

idempotency_key 请求体字段的替代方式。

请求体

application/json

country

string

必填

ISO 3166-1 alpha-2 目标国家(例如 CL、PE、MX)。

currency

string

必填

本地货币(例如 CLP、PEN、MXN)。

amount

string

必填

本地货币金额,正数十进制字符串。

示例:

"50000.00"

method

string

来自 GET /v1/payouts/methods 的 payout 方式(例如 bank_transfer)。

beneficiary

object

目标账户详情。所需键取决于国家与方式;参见 GET /v1/payouts/methods 和 GET /v1/payouts/banks。示例:智利为 RUT + 银行,墨西哥为 CLABE,秘鲁为 CCI。巴西 PIX:pix_key + pix_key_type(cpf、 cnpj、phone、email、evp),或不用键的银行账户,使用 bank_code(ISPB)+ branch_code + account_number + tax_id。厄瓜多尔(汇款走廊):document_value(身份证号)加上在同一对象中平铺的汇款人数据(sender_name、 sender_document_value 等);可选的结构化姓名字段 (given_name、first_surname 等及其对应的 sender_* 字段) 优先于对 name 的自动拆分。阿根廷:tax_id(11 位 CUIT/CUIL)+ account_number (22 位 CBU 或 CVU;USD 仅支持 CBU)—— 无需 bank_code。美国(USD):每笔转账都需收款人完整的身份与邮政地址 —— name、 email、account_number、country_code、address、city、 postal_code、bank_name、bank_country 和 bank_code(ach/wire 用 ABA routing number,swift 用 SWIFT BIC);ach 还必须提供 account_type(CHECKING/SAVING)。收款人可居住在任何国家 (country_code 不限 —— 例如向居住德国的收款人的美国银行账户发起 ACH);仅当 country_code 为 US 时 state 为必填。ach/wire 的收款银行必须位于美国(bank_country: "US" —— 本地通道无法向美国以外的银行付款),并需完整银行地址块(bank_address、 bank_city、bank_postal_code,美国银行还需 bank_state); swift 的银行地址块为选填(通道可从 BIC 推导),bank_country 可为任意国家。附件 B 所列辖区(CU/IR/KP/SY)对收款人国家和银行国家仍然封锁(422 prohibited_country)。所有 USD 银行通道转账还须先通过 POST /v1/payouts/documents 上传支持文件(发票/收据) —— 详见 payouts 指南。

Show child attributes

beneficiary_contact_id

string<uuid>

使用联系人在该国家(及方式,若传入)最近保存的受益人,而无需再次输入 beneficiary。显式 beneficiary 始终优先;若联系人没有则返回 422 no_saved_destination。

save_contact

boolean

默认值:true

受益人会自动保存为联系人;传 false 可跳过。

description

string

settlement_asset

enum<string>

此操作要扣款的虚拟余额。省略则使用账户的默认结算资产(USDT,除非通过 PUT /v1/settlement 更改)。

可用选项:

USDT,

USDC,

BTC,

GOLD

idempotency_key

string

响应

既有 payout 的幂等重放。

payout_id

string<uuid>

account_id

string<uuid>

idempotency_key

string

country

string

currency

string

method

string

local_amount

string

fx_rate

string

执行时你账户的汇率(每 1 USDT 的本地单位数)。

usdt_amount

string

fee

string

total_debit

string

settlement_asset

enum<string>

该操作实际扣款的虚拟余额。

可用选项:

USDT,

USDC,

BTC,

GOLD

settlement_amount

string

从结算资产余额实际扣除的准确金额(以该资产单位表示)。当资产为 USDT 时等于 total_debit。若 payout 失败,退款即为该准确金额——绝不重新计价。

settlement_rate

string

用于转换 USDT 总额的结算资产有效 USD 单价(USDT/USDC 为 "1")。

beneficiary

object

description

string

status

enum<string>

可用选项:

pending,

processing,

completed,

failed

status_code

string

status_message

string

bank_reference

string

银行/支付渠道的交易参考号(受益人可用它与银行核对付款)。US ACH/wire/SWIFT 在创建时立即返回 CBF 参考号；其他通道在渠道报告之前为空。

created_at

string<date-time>

updated_at

string<date-time>

idempotency_hit

boolean

当响应为幂等重放时为 true。

最后修改于 2026年8月22日