本页面和法币付款 OpenAPI Reference 均为设计预览。接口名称、字段、状态、权限和错误码尚未最终确定。

法币付款 API 支持组织从 Infini USD 余额向第三方银行账户支付 USD。第一期固定通过 SGB 执行，调用方无需选择服务商；响应会返回只读的 provider=sgb，用于对账和后续扩展。

所有接口使用以下前缀：

/v2/payouts

第一期不提供收款人资源。银行收款资料随 Quote 一次性提交，并不可变地绑定到 quote_id；POST /v2/payouts 不能替换或修改这份收款资料。

创建 Quote 时，请选择需要准确固定的是收款金额，还是付款账户的总扣款金额。fee_paid_by 会改变 Infini 对两侧金额的计算方式，并非仅用于展示。第一期支持以下两种方式。

适用于收款人必须准确收到指定金额的场景，例如支付发票。

{
  "amount": "1000.00",
  "amount_mode": "receive",
  "fee_paid_by": "PAYER"
}

收款人准确收到 1000.00 USD。PAYER 表示手续费外扣，付款手续费会额外计入 Infini USD 余额的扣款金额。

• receiving_amount 为 1000.00。
• sending_amount = receiving_amount + fee_amount。

适用于付款总扣款不能超过固定预算的场景。

{
  "amount": "1000.00",
  "amount_mode": "send",
  "fee_paid_by": "BENEFICIARY"
}

Infini 准确扣除 1000.00 USD。BENEFICIARY 表示手续费内扣，付款手续费从该金额中扣除，因此收款人的到账金额会更少。

• sending_amount 为 1000.00。
• receiving_amount = sending_amount - fee_amount。

请仅使用以上字段组合。第一期不支持其他 amount_mode 与 fee_paid_by 组合。修改 fee_paid_by 后必须重新请求 Quote；quote_id 会固定 Payout 使用的手续费承担方和计算结果。

• sending_amount：Infini USD 余额的实际总扣款金额。
• receiving_amount：发送到收款银行账户的金额。
• fee_amount：Quote 计算出的手续费总额；bank_fee_amount 是其中包含的银行或通道费。
• fee_rate_decimal：Quote 使用的手续费率；rate 是汇率。

对账时，请使用 sending_amount 作为该笔付款的支出金额。

API 付款不会进入后台人工审批流。POST /v2/payouts 会执行具有最终效力的付款前校验，并立即开始执行。

银行付款是异步过程。创建成功并返回 status=processing，表示请求已经通过 Infini 校验且付款执行已经开始，不代表收款人的银行账户已经到账。

completed 表示 SGB 在当前已知状态下报告付款完成。对端银行仍可能拒收并退回一笔已经完成的汇款，此时付款状态会变为 returned。

POST /v2/payouts/quotes 会校验收款资料，并执行初步的路由、金额、合规和限额检查。它返回一份包含收款资料、金额、汇率、费用和手续费承担方的有时效快照。一份 Quote：

• 不会冻结组织余额；
• 不会批准或创建付款；
• 过期后不能继续使用；
• 不保证当前限额、合规状态、余额或服务商可用性保持不变。

POST /v2/payouts 会在创建主付款单、扣减余额并开始 SGB 执行前，重新执行所有关键校验。

client_reference_id 在商户范围内唯一标识一笔逻辑付款：

• 使用相同引用和完全相同的业务请求重试时，返回已有资源；
• 付款幂等重试时，响应中的 is_duplicate=true；
• 使用相同引用提交不同业务数据时，返回 409 idempotency_conflict。

quote_id 和其他决定付款内容的字段都会参与幂等一致性比较。

Quote 请求包含银行账户敏感信息，响应只返回脱敏账号。客户端不得将完整银行账号写入 URL、日志、client_reference_id、statement_reference 或其他自由文本元数据。

API 付款不会出现待审批状态。

GET /v2/payouts/{payout_id} 是对外权威对账接口。第一期 Fiat Payout API 不提供 Webhook 文档。