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

​
1. 查询可用通道

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

​
2. 创建出金

beneficiary 是一个键/值对象，其必填字段取决于具体通道（智利需要 RUT 和银行，墨西哥需要 CLABE，秘鲁需要 CCI，巴西需要 PIX 密钥等）。方式目录 对每个通道都有说明。
每笔出金都会自动将收款人保存为联系人 （发送 "save_contact": false 可跳过）。若要再次向其付款而无需重新输入 资料，请发送 "beneficiary_contact_id" 代替 beneficiary —— 系统将使用 其在该国家和方式下最近保存的收款人信息（若不存在则返回 422 no_saved_destination）。
响应 202 Accepted：
此时您的余额已反映该笔扣款：total_debit 已从 available 转入 held（在 settlement_asset 对应的余额上）。
bank_reference —— 银行为该笔转账分配的交易编号。 US ACH/wire/SWIFT 在创建时立即返回 CBF（payout 保持 processing 直至银行确认）；其他通道在完成前为空（""）； 当出金状态变为 completed 时，它会带上目的地银行/通道分配的交易编号。收款人可使用该编号 与自己的银行核对付款。该字段同时出现在 payout_status_changed Webhook、PDF 回执、 出金 CSV 导出以及对账单中。

​
银行 tracking 标识与实时跟进

Payout 响应和 payout_status_changed 会包含两个新增且不绑定具体提供 商的字段：
  • uetr 是 UETR/SWIFT gpi 标识，仅在银行为 SWIFT 转账报告该值时出现。
  • imad 是国内 wire/ACH 标识，仅在银行报告该值时出现。
  • 两个字段在可用前均为 ""。CBPay 不会推导或编造这些值。
相同字段也会出现在 payout CSV 和 payout PDF 回执中。公共 交易 tracker 显示当前公共状态并链接到同一份回执； 它不会公开内部的 manual_dispatch 术语或合规细节。

​
从其他余额支付（settlement_asset）

扣款默认来自 USD；使用 PUT /v1/settlement 更改。若要让单笔操作从其他余额支付，请在请求中加入 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，分毫不差。
如果出金失败，将向您的 BTC 余额退回精确的 settlement_amount —— 绝不重新报价。如果当时 BTC/GOLD/SILVER/PLATINUM 的执行价格不可用，您会收到 503 pricing_unavailable；波动性资产还有单笔操作限额 （422 settlement_limit_exceeded；可在 GET /v1/settlement 中查询）。 有关 BOB、MXN 和 ARS 同币种法币 settlement 的 request/response 示例、 校验错误以及 rates 中的 same_currency_only 字段，请参阅 法币 payout 结算。

​
技术筛查可能处于 pending

CBPay 会在扣款或调用 core 之前筛查收款人。如果筛查服务暂时不可用，但 技术筛查队列可用，payout 会先持久化，创建请求返回 202 Accepted， 资源状态为 pending：
等待期间不会扣款、创建 hold 或账本分录，也不会调用 core，更不会生成 receipt_url。使用相同幂等键 replay 会返回同一个 payout，并带有 idempotency_hit: true；绝不会创建第二笔。worker 收到 process 后， 原 payout 才进入正常扣款和派发流程。有效的 hold 会进入交易防火墙； 之后如果结果是 rejected，该 payout 会在不扣款的情况下变为 failed。 收到 process 后，同一个 payout 仍可能保持 status: "pending"，同时 持久化协调扣款和派发。API 与 payout_status_changed webhook 会暴露以下 持久化转换码：
  • compliance_dispatch_pending：筛查通过，扣款/hold 已存在，因此 funds_debited: true；core 派发尚未完成。
  • compliance_dispatching：派发声明已取得，正在执行。
  • core_unreachable：派发或本地结算结果不明确，等待协调；不要创建第二笔 payout。
这些转换不是新操作。保留相同的 idempotency_key，重新读取 payout 并 等待下一个状态事件。payout 进入终态后，completed 消耗 hold， failed 退回精确扣款；终态事件使用持久化路径并携带正常的回执字段。 当 payout 无法写入 pending 队列，或流程本身没有该队列时，仍使用 compliance_check_unavailable 等现有技术错误。现有的校验、安全和 compliance_hold 合约不变。

​
扣款前失败不是退款

如果筛查或硬性合规控制在扣款路径开始前失败，同一 payout 可以以 failed 结束，并带有 predebit_failure: true 和 funds_debited: false。响应及其 payout_status_changed 事件不包含 receipt_url，因为没有可撤销的扣款、hold 或回执。这不同于扣款后的 failed payout，后者会在终态事件前退回准确的扣款金额。 有关汇率来源和 FIFO 指示性报价，请参阅 Payout 汇率来源与 FIFO 指示性报价。

​
3. 接收最终状态

订阅 payout_status_changed 事件（webhooks）：
  • completed：资金已到账；冻结金额被消耗。
  • failed：全部扣款自动退回（在您的账本中记为 payout_refund）。
status_message 是与 status_code 一起返回的可选规范化详情； 核心没有额外消息时该字段可以为空。 您也可以随时查询：

​
出金状态

​
查询与历史记录

每笔出金都可以单独读取，列表接口支持筛选：
from/to 使用 YYYY-MM-DD（组织时区，两端均含）；日期无效时返回 400 invalid_range。method 按实时 payout 目录过滤，search 会对 payout ID、 银行参考号或幂等键进行不区分大小写的部分匹配。

​
各国示例

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

​
各通道的收款人字段

以 CLP 进行银行转账。需要 RUT、银行和账户：智利比索没有小数单位，因此 CLP payout 金额必须为整数（例如 30000 或 30000.00）。
银行目录（GET /v1/payouts/banks?country=CL）列出当前有效的 bank_code 值。对于 CL/CLP/bank_transfer，payout 可能在约五分钟 的短窗口内批量派发；POST /v1/payouts 仍返回 202 与 status: "processing"，每笔 payout 仍保留自己的最终状态和 payout_status_changed webhook。

​
QR 出金

支付收款二维码（玻利维亚、巴西 PIX）现已拥有独立指南：

QR 出金

免费扫描二维码，向用户展示收款人信息，再通过第二次调用确认支付 — 按普通出金计费。

​
常见错误

​
立即拒绝与后续失败

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

​
解读失败出金的 status_code

无论哪种情况，退款均已完成 —— 可通过 账户流水中的 payout_refund 条目进行核实。
处于 processing 状态的出金无法通过 API 取消：通道已经在处理它。请通过 webhook 或 GET 等待最终状态 —— 它一定会到达，失败时会自动退款。

​
常见问题

创建时：payout 立即扣款并冻结资金。如果 payout 失败，精确的扣款金额 （含手续费）会自动退回。
不可以 —— 一旦派发到通道，它会自行解析为 completed 或 failed。订阅 payout_status_changed 获取最终状态。
创建时报价的汇率（以 fx_rate 返回），对该笔操作冻结。你约定的点差 已包含在汇率中。
可以 —— 设置账户级默认值（PUT /v1/settlement）或按笔用 settlement_asset 覆盖（USDC、BTC、GOLD）。退款返回精确的结算金额， 绝不重新报价。
收款人筛查暂时不可用，但 CBPay 已将 payout 持久化到技术筛查队列。 没有扣款、hold 或账本分录，core 尚未被调用，也没有 receipt_url。使用相同 幂等键 replay 会返回同一个资源。等待 payout_status_changed 或查询 payout；结果为 process 时继续，hold 时进入防火墙，rejected 时 在不扣款的情况下变为 failed。
受益人未通过合规筛查：payout 未被创建，你的 idempotency_key 也未 被消耗。请核对受益人信息或联系你的 CBPay 团队。
用相同的 idempotency_key 重试：会返回原始 payout （idempotency_hit: true）—— 绝不会重复。新的 key 是一笔全新的独立 payout。
创建时就已经返回 bank_reference（CBF）。payout 保持 processing，直到银行确认人工付款。 监听 payout_status_changed 以获得 completed 或 failed（已退款）。该通道没有额外的收款人 AML hold。
出金限额错误见公开错误参考。

​
目的地拒绝保护

部分银行通道会在银行近期拒绝某个目的地后保护该目的地。API 会在创建 payout、扣除余额或消耗幂等键之前返回 422 destination_recently_rejected。明确重试使用新幂等键和 options.destination_retry_ack；完全相同的请求使用原幂等键重放。目的地 会被规范化，因此改变格式不能绕过保护。 详见目的地拒绝保护与安全重试， 其中包含完整请求、响应、状态和恢复顺序。

​
US/USD 付款用途与校验

对于 US/USD 银行通道出金（ach、wire 和 swift）， options.purpose 为必填。API 不区分大小写，接受下列可见标签或对应代码： 只有当 purpose 为 Other 时才必须提供 options.purpose_detail，最长 140 个字符；其他用途提供该字段会被拒绝。创建请求缺少 purpose 现在返回 400 purpose_required，这是相对于过去默认 Invoice_Payment 的不兼容变更。 beneficiary.account_type 对 ach 和 wire 都是必填，值必须为 checking 或 savings（不区分大小写）；swift 不使用此字段。 wire 和 swift 低于 USD 25 时返回 422 amount_below_minimum。 收款人或银行位于附录 B 国家（CU、IR、KP、SY）时返回 422 prohibited_country。这些校验都在扣款前完成。 规范化错误包括 invalid_beneficiary、invalid_amount、 amount_below_minimum、prohibited_country、purpose_required、 invalid_options 和 supporting_document_required。请按 message 修正具体字段；拒绝请求不要原样重试，timeout 或 5xx 时使用相同幂等键。 OTC 派发路径仍在内部使用 Invoice_Payment，公共 payout 合约不变。
最后修改于 2026年10月17日