GET /v1/rates 返回的汇率)从当地货币折算为账户默认余额,并从该
余额中扣除等值金额和固定费用(如已配置)。明确设置 USDT 默认值的 legacy 账户
仍从 USDT 余额扣款。
以下是完整的生命周期,包括每一步中您的余额发生的变化:
1. 查询可用通道
国家、货币和方式由 CBPay 定义。请始终查询目录:
可用性可能变化;目录(
GET /v1/payouts/methods)始终是唯一可信来源。
如果某个国家只有一种方式,method 为可选。每种方式的计费方式相同:
您的汇率 + 固定费用。
对于银行转账,您还需要银行目录(收款人的 bank_code 即来自这里):
2. 创建出金
每笔出金都会自动将收款人保存为联系人
(发送
"save_contact": false 可跳过)。若要再次向其付款而无需重新输入
资料,请发送 "beneficiary_contact_id" 代替 beneficiary —— 系统将使用
其在该国家和方式下最近保存的收款人信息(若不存在则返回
422 no_saved_destination)。202 Accepted:
total_debit 已从 available 转入
held(在 settlement_asset 对应的余额上)。
US/USD 汇款 payout
对于发送至美国的 USDwire 或 swift payout,如果代表第三方付款,
请将 options.is_remittance 设置为字符串 "true"。此选项仅支持
US/USD wire 和 swift;在 ach 上会被拒绝,在其他通道上会被忽略。
202 Accepted:
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 不会推导或编造这些值。
manual_dispatch 术语或合规细节。
从其他余额支付(settlement_asset)
扣款默认来自 USD;使用 PUT /v1/settlement 更改。若要让单笔操作从其他余额支付,请在请求中加入
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_rate109029.34070000):105.535465 / 109029.3407 = 0.00096795 BTC(向上取整到聪)。 - 以 BTC 扣款并冻结:
settlement_amount0.00096795从您的 BTC 余额中扣除;收款人照常收到其 100,000 CLP,分毫不差。
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:
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 指示性报价。
阿根廷:付款前解析银行别名
对于 ARS 银行转账,请先解析别名、确认已验证的持有人,再使用返回的 账户资料创建正常 payout。该查询按账户隔离,每分钟最多 10 次。POST /v1/payouts 中将原始别名作为 account_number,并使用返回的
tax_id/name;dispatch 会在最新状态下重新解析别名,并在证据中记录
destination_alias。alias_unresolvable 是确定性的,
beneficiary_lookup_unavailable 是暂时性的;
invalid_alias、query_required、verification_required 和
too_many_attempts 都是可处理的查询错误。请参阅错误码。
出金状态
查询与历史记录
每笔出金都可以单独读取,列表接口支持筛选:from/to 使用 YYYY-MM-DD(组织时区,两端均含);日期无效时返回
400 invalid_range。method 按实时 payout 目录过滤,search 会对 payout ID、
银行参考号或幂等键进行不区分大小写的部分匹配。