常见错误
立即拒绝与后续失败
如果处理方在创建时因可修正的业务原因拒绝了出金,您会收到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 失败,精确的扣款金额
(含手续费)会自动退回。
可以取消 processing 中的 payout 吗?
可以取消 processing 中的 payout 吗?
不可以 —— 一旦派发到通道,它会自行解析为
completed 或 failed。订阅
payout_status_changed 获取最终状态。我的 payout 使用哪个汇率?
我的 payout 使用哪个汇率?
创建时报价的汇率(以
fx_rate 返回),对该笔操作冻结。你约定的点差
已包含在汇率中。可以用 USDT 以外的余额付款吗?
可以用 USDT 以外的余额付款吗?
可以 —— 设置账户级默认值(
PUT /v1/settlement)或按笔用
settlement_asset 覆盖(USDC、BTC、GOLD)。退款返回精确的结算金额,
绝不重新报价。status: pending 且 compliance_pending: true 是什么意思?
status: pending 且 compliance_pending: true 是什么意思?
收款人筛查暂时不可用,但 CBPay 已将 payout 持久化到技术筛查队列。
没有扣款、hold 或账本分录,core 尚未被调用,也没有
receipt_url。使用相同
幂等键 replay 会返回同一个资源。等待 payout_status_changed 或查询
payout;结果为 process 时继续,hold 时进入防火墙,rejected 时
在不扣款的情况下变为 failed。compliance_hold(403)是什么意思?
compliance_hold(403)是什么意思?
payout 被保留审核且未被处理:没有资金移动,你的
idempotency_key 也未被消耗。门户会显示可复制的引用行,其中包含 UTC 时间、错误代码和短请求 ID。
联系支持团队时请提供该引用;不会披露具体的合规原因。payout 的 status: in_review 是什么意思?
payout 的 status: in_review 是什么意思?
payout 正在审核,账户看到的消息会保持通用:释放后会自动完成。当通道或其
资金库暂时不可用时,平台可能用此状态保护 payout。处于审核期间不要修改
收款人,也不要创建第二笔 payout。如果审批返回
reissue_required,请使用
新的幂等键创建新的 payout;CBPay 不会自动重新发起。为什么 payout 返回 503,却没有收款人错误?
为什么 payout 返回 503,却没有收款人错误?
部分临时通道状况并非由收款人数据造成。直接收到 503 时,请使用相同的
幂等键重放。如果 payout 已进入
in_review,请等待审核结果;只有明确的
reissue_required 才表示可以使用新的 key 创建新的 payout。超时或 5xx 之后如何安全重试?
超时或 5xx 之后如何安全重试?
用相同的
idempotency_key 重试:会返回原始 payout
(idempotency_hit: true)—— 绝不会重复。新的 key 是一笔全新的独立
payout。为什么我的美国 ACH/wire/SWIFT payout 一直处于 processing?
为什么我的美国 ACH/wire/SWIFT payout 一直处于 processing?
创建时就已经返回
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 合约不变。