业务指南
完整接入步骤
从申请到首笔交易,分阶段完成入网与技术接入
阶段 1 · 接入准备
阶段 2 · 终端绑定
阶段 3 · 接口接入
完成商户与设备开通,取得调用方凭证;完成原始字节签名、首笔支付、查单、通知验签与退款联调;通过异常测试及上线清单后再切换生产。
端到端业务流程
订单推送场景下的完整支付生命周期
- 激活(首次接入): 通过 /terminal/activate 注册调用方系统,保存 terminal_sn + terminal_key;另行确认目标设备绑定。
- 订单推送: 调用 /appPush/tradePush,PUSH_SUCCESS 只表示推送受理;支付单 sn 需从后续查询或通知获得。
- 顾客付款: 顾客扫码或刷卡 → 终端处理支付
- 接收结果: 结果回调至 notify_url,可通过 /upay/v2/query 主动查询
- 退款(按需): 调用 /upay/v2/refund → 查询确认 → 更新商户系统
订单状态流转
取消相关状态:CANCELED / PAY_CANCELED。
图中展示支付与退款主路径,未列出所有状态或转换。订单状态可继续变化:PAID 后可退款,PARTIAL_REFUNDED 后可继续退款;请同时判断交易流水类型和状态,详见响应与状态判定。
响应与状态判定
按下面四层依次判断。字段缺失、未知枚举或验签失败时,保留“待核实”,不要自动归为成功或失败。
订单与流水是两个对象
sn 是订单号,tsn 是交易流水号;一个订单可以先有 PAYMENT,再有多次 REFUND 或 CANCEL。未指定 refund_request_no 的查询可能返回最新退款流水。status=SUCCESS 必须与 type 一起解释。
流水 status 可包含 CREATED、IN_PROG、PRE_SUCCESS、ERROR_RECOVERY、ABORTING、SUCCESS、FAIL_CANCELED、ABORTED、FAIL_ERROR、REFUND_ERROR 等。不要仅实现 SUCCESS/FAIL 两个分支,也不要把新枚举默认视为终态。
关单受理但仍在执行
上例需要继续查询原订单;它不能作为“已取消”的凭据。支付、退款和撤销的状态更新应分别记录,避免迟到消息回退订单。
最佳实践
超时、重复与结果恢复
客户端等待结束只说明未获得可信结果。商户系统应保留独立的“结果待确认”状态,保存原业务标识,暂停再次收款或退款。
幂等边界
本组接口没有确认统一的 Idempotency-Key 请求头、固定幂等保留窗口或“重复请求返回原响应”的承诺。out_trade_no/client_sn 的商户内唯一性、refund_request_no 的业务身份,以及商户自己实现的原子记账是不同约束。新业务用新标识;同一业务结果不明时不能换标识。
时间与对账
请求/响应的毫秒时间戳是 Unix 时间;门店展示建议显式使用 Asia/Singapore(UTC+08:00)。交易日、账务日、日切点、账单格式、退款入账日和结算到账周期须按开通资料确认。保存平台订单、商户订单、支付/退款流水和业务日期的关联;net_amount 不等于扣费后到账额,/mis/shift 不提供银行到账证据。
