> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.
# 业务指南
## 完整接入步骤 \{#integration-journey}
从申请到首笔交易,分阶段完成入网与技术接入
### 阶段 1 · 接入准备
```mermaid
flowchart LR
accTitle: 阶段 1:接入准备
accDescr: 提交申请并审核通过后,获取服务商凭证,再完成商户入网。
A["步骤 1 · 提交申请
向平台提交企业资料、
联系人和技术栈信息
ISV → AiMT
产出:审核通过"]
B["步骤 2 · 获取开发参数
AiMT 根据审核通过的申请
发放服务商凭证
AiMT → ISV
产出:vendor_sn · vendor_key
app_id · app_key"]
C["步骤 3 · 商户入网
ISV 提交商户资料,
AiMT 协助登记门店
并生成 store_sn
ISV → AiMT
产出:merchant_sn · store_sn"]
A --> B --> C
classDef preparation fill:#fffbeb,stroke:#d97706,color:#78350f
class A,B,C preparation
```
### 阶段 2 · 终端绑定
```mermaid
flowchart LR
accTitle: 阶段 2:终端绑定
accDescr: AiMT 绑定目标支付设备并生成激活码,目标设备编号用于后续步骤 7 推单。
D["步骤 4 · 绑定 POS 终端
将 target_device_id
绑定到门店
执行方:AiMT
产出:target_device_id
用于步骤 7 的订单推送"]
E["步骤 5 · 生成激活码
AiMT 协助生成激活码,
将门店与设备绑定
执行方:AiMT
产出:code"]
D --> E
classDef binding fill:#eff6ff,stroke:#2563eb,color:#1e3a8a
class D,E binding
```
### 阶段 3 · 接口接入
```mermaid
flowchart LR
accTitle: 阶段 3:接口接入
accDescr: 激活 ISV 调用方终端,使用已绑定的目标设备推单,随后通过查询、退款和回调管理交易。
F["步骤 6 · 激活终端
调用 /terminal/activate
将 ISV/服务商设备
注册为平台 API 调用方
执行方式:接口调用
产出:terminal_sn
terminal_key"]
G["步骤 7 · 推送订单
调用 /appPush/tradePush
使用步骤 4 的 target_device_id
订单显示在 POS 终端
执行方式:接口调用
产出:out_trade_no
等待支付;查询/通知获取 sn"]
H["步骤 8 · 其他接口操作
退款、查询、回调验签
持续管理交易生命周期
执行方式:接口调用
接口:/upay/v2/refund
/upay/v2/query · 回调"]
F --> G --> H
classDef integration fill:#f0fdf4,stroke:#16a34a,color:#14532d
class F,G,H integration
```
:::info 快速检查清单(供参考)
完成商户与设备开通,取得调用方凭证;完成原始字节签名、首笔支付、查单、通知验签与退款联调;通过异常测试及上线清单后再切换生产。
:::
## 端到端业务流程 \{#integration-flow}
订单推送场景下的完整支付生命周期
1. **激活(首次接入):** 通过 /terminal/activate 注册调用方系统,保存 terminal_sn + terminal_key;另行确认目标设备绑定。
2. **订单推送:** 调用 /appPush/tradePush,PUSH_SUCCESS 只表示推送受理;支付单 sn 需从后续查询或通知获得。
3. **顾客付款:** 顾客扫码或刷卡 → 终端处理支付
4. **接收结果:** 结果回调至 notify_url,可通过 /upay/v2/query 主动查询
5. **退款(按需):** 调用 /upay/v2/refund → 查询确认 → 更新商户系统
### 订单状态流转
```mermaid
flowchart TD
accTitle: 支付与退款订单状态
accDescr: 订单从创建到支付后,可以全额或部分退款;部分退款后还可以继续退款。
CREATED --> PAID
PAID --> REFUNDED
PAID --> PARTIAL_REFUNDED
PARTIAL_REFUNDED --> PARTIAL_REFUNDED
PARTIAL_REFUNDED --> REFUNDED
```
取消相关状态:`CANCELED` / `PAY_CANCELED`。
图中展示支付与退款主路径,未列出所有状态或转换。订单状态可继续变化:PAID 后可退款,PARTIAL_REFUNDED 后可继续退款;请同时判断交易流水类型和状态,详见[响应与状态判定](#response-states)。
## 响应与状态判定 \{#response-states}
按下面四层依次判断。字段缺失、未知枚举或验签失败时,保留“待核实”,不要自动归为成功或失败。
| 层级 | 字段/示例 | 可以得出的结论 |
| ---- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
| HTTP | HTTP 2xx | 只说明收到 HTTP 响应;认证失败也可能返回 HTTP 200。 |
| 接口结果 | 顶层 result_code = "200" / "400" / "500" | 业务层可处理 / 请求错误 / 服务异常;400、500 或网络超时均不能单凭这一层推断资金结果。 |
| 业务结果 | biz_response.result_code | PUSH_SUCCESS / MIS_PUSH_SUCCESS=指令受理;查询 SUCCESS=查询执行成功;服务端退款看 REFUND\_\*。同时读取 error_code。 |
| 交易结果 | biz_response.data.type / status / order_status | 结合商户、client_sn/sn、total_amount 和流水类型确认。支付成功示例:PAYMENT + SUCCESS + PAID;退款后应分别记录原支付与退款结果。 |
### 订单与流水是两个对象
`sn` 是订单号,`tsn` 是交易流水号;一个订单可以先有 PAYMENT,再有多次 REFUND 或 CANCEL。未指定 `refund_request_no` 的查询可能返回最新退款流水。`status=SUCCESS` 必须与 `type` 一起解释。
| order_status | 处理方式 |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| CREATED | 尚未确认付款,继续等待并查单。 |
| PAID | 订单已支付;可以按幂等规则履约,但以后仍可能退款或撤销。 |
| PARTIAL_REFUNDED / REFUNDED | 分别表示部分/全额退款;核对指定退款流水,不能再次将订单记为新支付。 |
| PAY_CANCELED / CANCELED | 支付已关闭,或订单已取消/撤销。CANCELED 也可能来自未付款时的主动关单;这两个枚举都不能单独证明曾扣款或资金已退,须核对原支付/撤销流水、金额及渠道结果。 |
| PAY_ERROR / REFUND_INPROGRESS / REFUND_ERROR / CANCEL_INPROGRESS / CANCEL_ERROR | 按对应操作保留处理中或待核实,继续查询或升级处理;不能因为错误字样就再次扣款/退款。 |
流水 `status` 可包含 `CREATED`、`IN_PROG`、`PRE_SUCCESS`、`ERROR_RECOVERY`、`ABORTING`、`SUCCESS`、`FAIL_CANCELED`、`ABORTED`、`FAIL_ERROR`、`REFUND_ERROR` 等。不要仅实现 SUCCESS/FAIL 两个分支,也不要把新枚举默认视为终态。
### 关单受理但仍在执行
```json
{
"result_code": "200",
"biz_response": {
"result_code": "MIS_PUSH_SUCCESS",
"error_code": "ORDER_CLOSE_ABORT_IN_PROGRESS"
}
}
```
上例需要继续查询原订单;它不能作为“已取消”的凭据。支付、退款和撤销的状态更新应分别记录,避免迟到消息回退订单。
## 最佳实践 \{#best-practices}
| 领域 | 建议 |
| ------ | --------------------------------------------------- |
| 激活管理 | 安全持久化调用方 terminal_sn / terminal_key;激活与目标设备绑定分别管理。 |
| 密钥轮换 | 按接入配置调用 /terminal/checkin 并原子更新密钥;本页不承诺统一的每日签到频率。 |
| 订单号唯一性 | out_trade_no 在同一商户内唯一;同一业务保持原单号,结果未知时先查原单,禁止换号再次收款。 |
| 双重确认 | 回调与查询共同确认;同一订单的不同流水不能相互覆盖,旧通知不能回退已确认状态。 |
| 异常处理 | 发生网络超时后,先查询订单状态再重试,不要盲目重发。 |
| 对账 | 按商户、门店和业务日期核对支付、退款与账单;/mis/shift 不是资金结算到账确认。 |
| 日志 | 记录脱敏后的业务标识、请求时间、状态与错误码;不记录密钥、完整卡号或完整敏感报文。 |
| 幂等处理 | 按流水及状态处理回调去重;每个新退款业务生成退款号,同一退款结果不明时保留原号查询。 |
## 超时、重复与结果恢复 \{#reliability}
客户端等待结束只说明未获得可信结果。商户系统应保留独立的“结果待确认”状态,保存原业务标识,暂停再次收款或退款。
| 触发条件 | 立即处理 | 恢复/停止条件 |
| ---------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| 推单超时、断连、5xx、无效响应签名 | 保留原 out_trade_no 与请求参数;用 client_sn 查原单,已有 sn 则优先用 sn。不要换单号、换设备或改走另一个支付通道再次扣款。 | 查询/可信通知确认已支付则幂等完成;仍未知则继续核实。 |
| 推单受理后暂时查不到订单 | 设备可能尚未创建支付交易;核对调用终端与目标设备所属商户,等待付款流程继续。 | 查不到不是未受理的证明;确认设备及平台原操作不会继续执行后,才按约定重新发起。 |
| 查询显示处理中或错误恢复 | 保持原订单;采用有上限的退避查询并等待通知。 | 建议客户端 2、5、10 秒逐步退避,随后低频补查;这是接入建议,不是平台频控或时效承诺。门店等待超时后进入待核对,不改成付款失败。 |
| 退款超时 / REFUND_IN_PROGRESS / REFUND_ERROR | 用原 sn/client_sn + refund_request_no 查询;不换退款号,不切换设备/服务端退款路径重复提交。 | 确认该次退款 SUCCESS 后记账;明确失败后按业务规则决定后续操作,长期不明转人工。 |
| 关单与支付并发 | 保留关单请求与原支付结果;ORDER_CLOSE_ABORT_IN_PROGRESS 继续查单。 | 以核实后的订单及流水结果更新;如已收款且未撤销,按允许的退款流程处理,不能直接关闭本地订单。 |
| 重复或乱序通知 | 验签、持久化;以商户/订单 + type + tsn + status 等构造处理记录,并用本地原子状态更新防止重复履约。 | 去重已执行的业务效果;同一 sn 的新退款不能丢弃,迟到 PAYMENT 通知不能覆盖最新退款状态。 |
| 限流、平台/渠道临时故障 | 降低并发并退避;支付/退款请求先查询原业务,读取接口层和业务层错误码。 | 恢复后继续原业务核实;不无限循环、不将批量重发作为恢复策略。 |
### 幂等边界
本组接口没有确认统一的 `Idempotency-Key` 请求头、固定幂等保留窗口或“重复请求返回原响应”的承诺。`out_trade_no/client_sn` 的商户内唯一性、`refund_request_no` 的业务身份,以及商户自己实现的原子记账是不同约束。新业务用新标识;同一业务结果不明时不能换标识。
### 时间与对账
请求/响应的毫秒时间戳是 Unix 时间;门店展示建议显式使用 `Asia/Singapore`(UTC+08:00)。交易日、账务日、日切点、账单格式、退款入账日和结算到账周期须按开通资料确认。保存平台订单、商户订单、支付/退款流水和业务日期的关联;`net_amount` 不等于扣费后到账额,`/mis/shift` 不提供银行到账证据。