跳转到主要内容
破坏性变更 — 2026-11-13。 BOB、MXN、ARS 和 CLP 余额以及 BANK_* 镜像仅属于 Banking。平台 payout、swap、内部转账、银行卡、checkout、POS 和手续费拒绝法币结算并返回 HTTP 400。已有账户保留明确设置的 USDT 默认值;新账户使用 USD 作为主余额。法币操作请使用 Banking。

常见错误

立即拒绝与后续失败

如果处理方在创建时因可修正的业务原因拒绝了出金,您会收到 422, 对象处于 status: failed,且退款已经完成。修正收款人或请求数据后, 使用新的 key 创建新的 payout。临时的通道或资金库资金不足则不同: 平台可以将 payout 保持在 in_review,而不是立即失败,因此在知道审核 结果前不要创建新的 payout。 当 payout 处于 in_review 时,账户看到的消息会保持通用:正在审核, 释放后会自动完成。不要因为这个状态修改收款人数据。如果审核通过但 原始派发 key 已被消耗,审批会返回 reissue_required;只有这时才可 使用新的 idempotency_key 创建新的 payout。CBPay 不会自动重新发起 这笔资金操作。

解读失败出金的 status_code

对于已终止的 failed payout,账户消息会说明操作未能完成且资金已经退回。 可通过账户流水中的 payout_refund 条目核实。仍处于 in_review 的 payout 尚未终止;请等待 审核结果,不要假定已经退款或重新派发。
处于 processing 状态的出金无法通过 API 取消:通道已经在处理它。处于 in_review 的 payout 也不是客户端取消流程;请等待审核结果。两种状态 都应通过 webhook 或 GET 等待最终状态。终止失败会退回资金;审批若返回 reissue_required,则必须由客户端使用新 key 创建新的操作。

常见问题

创建时: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 也未被消耗。门户会显示可复制的引用行,其中包含 UTC 时间、错误代码和短请求 ID。 联系支持团队时请提供该引用;不会披露具体的合规原因。
payout 正在审核,账户看到的消息会保持通用:释放后会自动完成。当通道或其 资金库暂时不可用时,平台可能用此状态保护 payout。处于审核期间不要修改 收款人,也不要创建第二笔 payout。如果审批返回 reissue_required,请使用 新的幂等键创建新的 payout;CBPay 不会自动重新发起。
部分临时通道状况并非由收款人数据造成。直接收到 503 时,请使用相同的 幂等键重放。如果 payout 已进入 in_review,请等待审核结果;只有明确的 reissue_required 才表示可以使用新的 key 创建新的 payout。
用相同的 idempotency_key 重试:会返回原始 payout (idempotency_hit: true)—— 绝不会重复。新的 key 是一笔全新的独立 payout。
创建时就已经返回 bank_reference(CBF)。payout 保持 processing,直到银行确认人工付款。 预计 ACH 为 24–48 个工作小时,wire/Fedwire 为同一工作日(最长 24 小时), SWIFT 为 24–48 个工作小时且可能因收款银行而延长。监听 payout_status_changed 以获得 completed 或 failed(已退款)。该通道没有额外的收款人 AML/CFT 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年11月14日