> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # 测试与排障 ## 错误码与排障 \{#errors} 先检查顶层 `result_code/error_code`,再检查 `biz_response.result_code/error_code/error_code_standard`。下表为已核对的常见默认码;部署映射可能改变错误文案或标准码,程序不得按中文/英文提示文本分支。 | 错误/症状 | 含义与下一步 | | -------------------------------------------------------- | --------------------------------------------------------------------------------------- | | ILLEGAL_SIGN | 对比 Header 与 Body 的 terminal_sn;确认激活/交易凭证未混用、算法小写、使用最终原始 Body、密钥未过期。先跑签名测试向量;不向支持人员提供密钥。 | | INVALID_PARAM | 检查字段类型、长度、正整数金额和必填条件;修正参数前先判断原业务是否可能已受理。 | | PRE_AUTH_PAY_TYPE_MIX_ERROR | 预授权类型与其他支付类型组合不允许;按已开通的设备能力重新选择类型。 | | PUSH_DEVICE_SN_ERROR / TERMINAL_SN_UN_BIND | 设备号不存在或来源终端已解绑;核对 TUSN、激活凭证及绑定关系后再测试。 | | STORE_NOT_MARCH / MERCHANT_NOT_MARCH | 来源终端与目标设备的门店/商户关系不满足要求;注意 MARCH 是接口原始拼写。修复绑定,不绕过商户授权。 | | DEVICE_TYPE_NOT_SUPPORT | 该路由/机型不支持指令,确认设备、固件与应用开通。 | | DEVICE_OFFLINE / DEVICE_STATUS_UN_KNOW | 相关路由检测到设备离线/状态未知;恢复网络与设备登录,查询原单后再处理。不是每种路由都会返回这些码。 | | PUSH_FAIL / MIS_PUSH_FAIL / ERROR / UNKNOWN_SYSTEM_ERROR | 按未知结果恢复:保留业务标识,查原单并收集错误信息,不能只见 FAIL 就重新扣款。 | | ORDER_CLOSE_ABORT_IN_PROGRESS | 关单处理中,即使 MIS_PUSH_SUCCESS 也需继续查询。 | | ORDER_CLOSE_ERROR / UPAY_QUERY_ORDER_ERROR | 关单失败或查单异常,先查询原支付状态;持续不明进入人工核对。 | | PAY_TYPE_CANCEL_NOT_SUPPORTED | 该支付方式不支持当前取消动作;按设备/渠道规则处理并查单,不能据此判定已退款。 | | REFUND_IN_PROGRESS / REFUND_ERROR | 这是退款业务结果码;用原退款号查单,不换号重退。 | | ILLEGAL_REQUEST 或 HTTP 429/限流提示 | 可能触发入口限流;降低查询频率/并发。具体配额按分配配置,支付副作用仍需按原业务核实。 | ### 转人工时提供的诊断信息 - **环境与设备:** 环境、商户/门店标识、调用方 `terminal_sn`、目标设备号。 - **订单与流水:** `out_trade_no` / `client_sn`、`sn`、`tsn`、退款号。 - **请求与响应:** 请求发生时间及时区、接口路径、HTTP 状态、两层结果码、平台返回的追踪标识(如有)。 - **排查记录:** 已尝试的查询及设备现象。 请求/响应只提供脱敏样本;移除密钥、完整卡号、个人敏感信息。通过开户时指定的技术支持渠道提交,持续保留待核对状态。 ## 联调验收与上线 \{#testing} 下列用例应在授权测试环境执行并留存脱敏证据。本次文档校验不等于这些用例已在真实终端/渠道通过;没有模拟器的场景需安排受控联调。 | 场景与触发方式 | 必须验证的行为 | 通过证据 | | ------------------------------ | --------------------------------------------- | ------------------------------------ | | 成功支付:推送新单并在设备完成付款 | 受理后等待,按查询/验签通知确认;只履约一次。 | 同一 out_trade_no/sn、金额与 PAYMENT 流水一致。 | | 超时:测试代理在受理后丢弃响应 | 不换订单号重扣,按 client_sn 找回原单。 | 原单恢复且无重复收款。 | | 未付款/设备离线:断开测试设备网络 | 不把推送失败或暂时无订单当作资金结果;恢复后查原单。 | 设备、推送和查单记录可解释。 | | 并发/重复提交:同一业务重复调用 | 商户本地限制重复提交,保留原标识并核实结果。 | 只有一笔预期资金动作;不依赖服务端重放响应。 | | 验签:篡改 Body 字节、签名或错误公钥 | 拒绝无效回调,不产生履约;合法样本可验签。 | 包含中文、空白、转义的原始样本也通过正确验签。 | | 回调重试:返回 HTTP 500 或带引号的 success | 通知重试;改回纯文本 success 后停止。 | HTTP 状态与精确响应字节、投递时间记录。 | | 重复/乱序:在本地测试桩重放合法通知快照 | 同一业务效果一次;支付旧消息不覆盖新退款。 | 幂等记录与最终查单一致。 | | 部分/多次退款:仅测试已开通能力 | 记录每次退款号,查询指定退款;未知结果不换号。 | 累计退款、net_amount 和原订单匹配,无超退。 | | 退款结果丢失:丢弃退款响应 | 按原退款号恢复;不改走另一退款路径重复提交。 | 指定退款流水明确,资金动作唯一。 | | 支付与关单竞争:支付时发起关闭 | 对 ORDER_CLOSE_ABORT_IN_PROGRESS 持续核实;不提前声明取消。 | 最终支付/撤销结果与本地记录一致。 | | 签到:新旧密钥切换及多实例配置更新 | 成功响应用新密钥校验;后续请求可用,配置不回退。 | 脱敏校验结果、版本记录,无密钥泄漏。 | | 跨日对账与交班:按已确认日切规则执行 | 区分交易完成、交班执行与资金到账,核对支付/退款。 | 账单与业务标识对应,时区明确。 | ### 上线前确认 - 生产商户、门店、目标设备与调用方凭证绑定一致,币种和支付方式开通完成。 - 测试/生产 URL、公钥、密钥、回调域名分离;密钥安全存储,TLS 证书有效。 - 支付、退款、通知、超时和重复业务用例有可回溯证据,未知状态有人工接管流程。 - 已确认频控、设备固件、退款期限/权限/手续费、取消回调范围、对账与结算规则。 - 配置监控和支持联系人;先按约定完成小额生产验证,再逐步放量。 各项能力的确认方、所需证据及原文代码核对范围见[维护依据与待确认项](/zh/guide/sources.md#sources)。