For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/business.md.
  • 简体中文
  • 业务指南

    完整接入步骤

    从申请到首笔交易,分阶段完成入网与技术接入

    阶段 1 · 接入准备

    阶段 2 · 终端绑定

    阶段 3 · 接口接入

    快速检查清单(供参考)

    完成商户与设备开通,取得调用方凭证;完成原始字节签名、首笔支付、查单、通知验签与退款联调;通过异常测试及上线清单后再切换生产。

    端到端业务流程

    订单推送场景下的完整支付生命周期

    1. 激活(首次接入): 通过 /terminal/activate 注册调用方系统,保存 terminal_sn + terminal_key;另行确认目标设备绑定。
    2. 订单推送: 调用 /appPush/tradePush,PUSH_SUCCESS 只表示推送受理;支付单 sn 需从后续查询或通知获得。
    3. 顾客付款: 顾客扫码或刷卡 → 终端处理支付
    4. 接收结果: 结果回调至 notify_url,可通过 /upay/v2/query 主动查询
    5. 退款(按需): 调用 /upay/v2/refund → 查询确认 → 更新商户系统

    订单状态流转

    取消相关状态:CANCELED / PAY_CANCELED。

    图中展示支付与退款主路径,未列出所有状态或转换。订单状态可继续变化:PAID 后可退款,PARTIAL_REFUNDED 后可继续退款;请同时判断交易流水类型和状态,详见响应与状态判定。

    响应与状态判定

    按下面四层依次判断。字段缺失、未知枚举或验签失败时,保留“待核实”,不要自动归为成功或失败。

    层级字段/示例可以得出的结论
    HTTPHTTP 2xx只说明收到 HTTP 响应;认证失败也可能返回 HTTP 200。
    接口结果顶层 result_code = "200" / "400" / "500"业务层可处理 / 请求错误 / 服务异常;400、500 或网络超时均不能单凭这一层推断资金结果。
    业务结果biz_response.result_codePUSH_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 两个分支,也不要把新枚举默认视为终态。

    关单受理但仍在执行

    {
      "result_code": "200",
      "biz_response": {
        "result_code": "MIS_PUSH_SUCCESS",
        "error_code": "ORDER_CLOSE_ABORT_IN_PROGRESS"
      }
    }

    上例需要继续查询原订单;它不能作为“已取消”的凭据。支付、退款和撤销的状态更新应分别记录,避免迟到消息回退订单。

    最佳实践

    领域建议
    激活管理安全持久化调用方 terminal_sn / terminal_key;激活与目标设备绑定分别管理。
    密钥轮换按接入配置调用 /terminal/checkin 并原子更新密钥;本页不承诺统一的每日签到频率。
    订单号唯一性out_trade_no 在同一商户内唯一;同一业务保持原单号,结果未知时先查原单,禁止换号再次收款。
    双重确认回调与查询共同确认;同一订单的不同流水不能相互覆盖,旧通知不能回退已确认状态。
    异常处理发生网络超时后,先查询订单状态再重试,不要盲目重发。
    对账按商户、门店和业务日期核对支付、退款与账单;/mis/shift 不是资金结算到账确认。
    日志记录脱敏后的业务标识、请求时间、状态与错误码;不记录密钥、完整卡号或完整敏感报文。
    幂等处理按流水及状态处理回调去重;每个新退款业务生成退款号,同一退款结果不明时保留原号查询。

    超时、重复与结果恢复

    客户端等待结束只说明未获得可信结果。商户系统应保留独立的“结果待确认”状态,保存原业务标识,暂停再次收款或退款。

    触发条件立即处理恢复/停止条件
    推单超时、断连、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 不提供银行到账证据。