简体中文
模拟联调通道:联调材料与接口
这一页是给联调时抓包、拼请求用的。材料都在管理台「系统 → 联调材料」页,端点清单在「系统 → 接口文档」页,两处同源。
材料在哪
「系统 → 联调材料」页给出两件东西:
- 全局密钥对:商户私钥(签请求)与平台公钥(验响应与回调);
- 网关地址:通道子应用出站时用的基地址,默认
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 一族)。纯手工调试建议直接看管理台「接口文档」页给的样例报文,再对照接入配置确认链路已经通了。