## Mock 契约

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


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

所有接口使用以下前缀：

`/v2/payouts`

## 最小接口集合

| 方法 | 接口 | 用途 |
|  --- | --- | --- |
| `POST` | `/v2/payouts/quotes` | 校验银行资料并获取有时效性的付款报价 |
| `POST` | `/v2/payouts` | 创建并立即开始执行直接付款 |
| `GET` | `/v2/payouts/{payout_id}` | 查询当前付款状态 |


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

## 选择需要固定的金额

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

### 固定收款金额

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

```json
{
  "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`。


### 固定总扣款金额

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

```json
{
  "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 使用的手续费承担方和计算结果。

### 查看 Quote 金额

- `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`。

## Quote 与执行前校验

`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` 或其他自由文本元数据。

## 状态与对账

| 付款状态 | 含义 |
|  --- | --- |
| `processing` | 已开始执行，等待最终结算 |
| `completed` | SGB 在当前已知状态下报告付款完成 |
| `failed` | 付款在银行成功完成前失败 |
| `returned` | 对端银行退回一笔已经提交或完成的汇款 |


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

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