> 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` 不提供银行到账证据。