# Otomatis 代付字段接入说明

**版本日期**：2026-06-12  
**适用接口**：`POST /api/PayRequest/UnifiedPayout`  
**渠道编码**：`channelCode=otomatis`

---

## 1. 产品清单

| 国家 / 币种 | payeeType | payTypeCode | 账户形态 |
| --- | --- | --- | --- |
| ID / IDR | `BANK` / `PERSONAL_BANK` / `BANK_CARD` | `otomatis_id_payout_bank` | 印尼银行账号或银行卡号 |

> 商户侧只使用平台标准 `payeeType`。Otomatis 上游原始 `type` 由后台产品配置映射，当前银行转账默认值为 `2`，不会要求商户直接传上游原始值。

## 2. 商户必须补齐的字段

| 平台字段 | 上游语义 | 说明 |
| --- | --- | --- |
| `payeeAccount` | `account_number` | 收款银行账号或银行卡号。 |
| `payeeBankCode` | `bank_code` | 填平台标准印尼银行码，详见 [`indonesia-bank-codes.html`](./indonesia-bank-codes.html)。平台会在上送前映射为 Otomatis `bank_code`。 |
| `payeeName` | 平台实名与审计字段 | 当前 Otomatis 上游代付报文不单独上送姓名，但平台统一要求保留收款人姓名。 |
| `countryCode` | 路由条件 | 建议固定传 `ID`。 |
| `notifyUrl` | 商户通知地址 | 可传；不传时使用商户后台出款通知地址兜底。 |

## 3. 上游映射说明

| Otomatis 字段 | 平台来源 |
| --- | --- |
| `client` | 渠道商户配置。 |
| `client_key` | 渠道商户配置。 |
| `uuid` | 渠道商户配置中的店铺 UUID。 |
| `amount` | `applyAmount / 100`，必须是整数 IDR。 |
| `bank_code` | `payeeBankCode` 先按平台印尼银行标准映射；未配置映射时透传原值。 |
| `account_number` | `payeeAccount`。 |
| `type` | 后台产品配置，默认银行转账为数字 `2`。 |
| `client_ref_id` | 平台代付订单号。 |

## 4. 流程说明

1. 平台先调用 Otomatis inquiry 接口校验收款信息。
2. inquiry 成功且返回 `inquiry_id` 后，再调用 transfer 接口提交出款。
3. 平台回调地址固定为 `/api/PayoutCallback/Otomatis`，不会使用下游商户的 `notifyUrl` 作为上游回调地址。
4. 平台收到明确成功或失败后推进本地状态，并按商户通知机制通知下游商户。

## 5. 金额、币种与银行码

- 平台内部金额单位为分；Otomatis 上游金额使用整数 IDR 主币单位。
- 非整数 IDR 金额会在本地拒绝，避免上游截断或四舍五入导致账务不一致。
- 查询/回调缺少金额或币种时，按系统通用规则：上游有返回才校验；未返回不因缺字段单独拦截。
- 银行码按平台标准治理。商户只需要查阅 `indonesia-bank-codes.html`，不要使用内部表名或上游后台配置名称。