Skip to content

模拟联调通道:联调材料与接口 ​

更新时间:2026/11/10 10:51:10

这一页是给联调时抓包、拼请求用的。材料都在管理台「系统 → 联调材料」页,端点清单在「系统 → 接口文档」页,两处同源。

材料在哪 ​

「系统 → 联调材料」页给出两件东西:

  • 全局密钥对:商户私钥(签请求)与平台公钥(验响应与回调);
  • 网关地址:通道子应用出站时用的基地址,默认 http://127.0.0.1:10400。

网关只用这一套全局密钥。请求里的 key_owner_no 是归属标记,不切换密钥;主体级独立密钥已下线。

三个签名头 ​

每个网关请求与每条回调都带三个头:

头内容
Mock-Sign对「时间戳 + 随机串 + 报文体」签名串的 RSA 签名
Mock-Timestamp秒级时间戳,超出时间窗拒绝
Mock-Nonce一次性随机串,防重放

回调由平台私钥签同样的三行串,通道子应用验签后解析并转交主应用。

报文约定 ​

  • JSON,字段 snake_case;
  • 时间用 RFC3339;
  • 金额单位与平台一致(分);
  • 回调是明文单层 JSON:外层 event_type / summary / out_biz_no / data,data 里是 snake_case 业务字段;
  • 回调会回传 biz_order_no 与 attach(有值才带),支付请求里的 biz_order_no / description / attach / app_id / expire_time 与退款请求里的 reason 全部落单留痕。

端点总表 ​

网关 /v3/mock/** 共 21 个端点,按七族划分:

族端点
支付POST /v3/mock/pay、GET /v3/mock/pay/{outTradeNo}、POST /v3/mock/pay/{outTradeNo}/close
退款POST /v3/mock/refund、GET /v3/mock/refund/{outRefundNo}
对账GET /v3/mock/bill
分账POST /v3/mock/alloc、POST /v3/mock/alloc/finish、GET /v3/mock/alloc/{allocNo}、POST /v3/mock/alloc/receivers、POST /v3/mock/alloc/receivers/unbind
进件POST /v3/mock/onb/apply、GET /v3/mock/onb/{outApplyNo}
终端POST /v3/mock/terminal、DELETE /v3/mock/terminal/{terminalNo}、GET /v3/mock/terminal/{terminalNo}
预授权POST /v3/mock/preauth/freeze、POST /v3/mock/preauth/{authNo}/capture、POST /v3/mock/preauth/{authNo}/unfreeze、POST /v3/mock/preauth/{authNo}/cancel、GET /v3/mock/preauth/{authNo}

字段级定义以管理台「接口文档」页为准。转账单在管理台内操作,没有对应的网关端点。

错误码 ​

码含义
10013模拟通道商户未注册(mock 侧没有该通道商户档案)
10022付款码格式不合法
40404聚合支付推成功但未带实际钱包
40491内置档案受保护,拒绝删除/改名/改归属/改密钥/启停/冻结

对账文件契约 ​

对账文件是 CSV:逗号分隔、UTF-8、换行符 \n、首行为列头。

text
tradeNo,outTradeNo,amount,status,finishTime

用代码跑通一次 ​

调网关端点要先过签名,最省事的方式是复用通道子应用的 SDK 客户端(MockGatewayClient 一族)。纯手工调试建议直接看管理台「接口文档」页给的样例报文,再对照接入配置确认链路已经通了。