# Otomatis 代收 `payTypeCode` 接入说明

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

---

## 1. 产品清单

| 国家 / 币种 | payTypeCode | 支付形态 | 上游产品 | 收银台展示 |
| --- | --- | --- | --- | --- |
| ID / IDR | `otomatis_id_acquire_qris` | QRIS 扫码 | QRIS | 上游返回 QRIS 原文时，收银台直接显示二维码 |
| ID / IDR | `otomatis_id_acquire_va` | VA 虚拟账号 | Virtual Account | 上游返回纯数字 VA 账号时，收银台显示银行转账付款指引 |

> 若商户使用 `auto_route`，可以不强制传 `payTypeCode`，但商户开通配置必须能唯一命中 Otomatis 对应产品；无法唯一命中时请补传 `payTypeCode` 或 `channelCode`。

## 2. 统一代收入参要点

| 平台字段 | 必填 | 说明 |
| --- | --- | --- |
| `appId` | 是 | 商户应用 ID。 |
| `merchantOrderNo` | 是 | 商户订单号，和 `appId` 组成幂等键。 |
| `amount` | 是 | 金额单位为分；Otomatis 上游使用整数 IDR，平台会在上送前转换为 IDR 主币单位。 |
| `currency` | 是 | 固定 `IDR`。 |
| `countryCode` | 建议 | 建议传 `ID`，便于路由唯一定位。 |
| `channelCode` | 建议 | 固定选择 Otomatis 时传 `otomatis`。 |
| `payTypeCode` | 条件 | QRIS 可传 `otomatis_id_acquire_qris`；VA 可传 `otomatis_id_acquire_va`。 |
| `buyerId` | 是 | Otomatis QRIS/VA 必传。请传下游商户侧付款用户名称或用户标识，平台会作为上游 `username` 上送。 |
| `notifyUrl` | 建议 | 商户代收通知地址；平台收到上游状态后通知商户。 |
| `returnUrl` | 可选 | 支付完成后的商户跳转地址。 |

## 3. 上游映射说明

| Otomatis 字段 | 平台来源 |
| --- | --- |
| `username` | 商户请求 `buyerId`。特别说明：Otomatis 要求该字段为下游商户传入的用户名称/用户标识，不再取渠道商户配置。 |
| `storeUuid` / `uuid` | 渠道商户配置中的 Otomatis 店铺 UUID。 |
| `amount` | `amount / 100`，必须是整数 IDR。 |
| `custom_ref` | 平台订单号。 |
| `notify_url` | 平台上游回调地址 `/api/PayCallback/Otomatis`。 |

## 4. 收银台展示规则

1. 上游返回 `data/payData/paymentData` 为 `000201...` 开头的 QRIS 原文时，平台返回二维码内容，收银台直接生成二维码。
2. 上游返回 `data/payData/paymentData` 为纯数字，并且产品为 VA 时，平台把该值作为虚拟账号展示给付款人。
3. 如果上游返回的是 H5/跳转 URL，收银台按通用 H5 逻辑处理。

## 5. 回调与查询

- 平台上游回调地址：`/api/PayCallback/Otomatis`。
- Otomatis 资料未提供请求级签名算法，平台按渠道资料中的回调 IP 白名单和回调报文结构解析。
- 平台仍会通过订单号、金额、币种和状态机保护资金状态；查询失败不会直接推进订单为失败。