支付开放 API 文档
与 /doc 内容一致。可运行样例：/index.html。判断成功请用 code === 200。平台单号建议 OR*，商城单 MO* 自动关联。
0.通用约定
1.获取价格
2.发起支付
3.直付支付
4.异步通知
5.订单查询
6.签名验签
0. 通用约定
成功响应
{
"code": 200,
"data": { },
"msg": "请求成功"
}
开放 API 响应不含顶层 sign；sign 仅出现在第 4 节异步通知 JSON body 中。
失败响应
{
"code": 400,
"msg": "签名验证失败"
}
失败时无 data、无 sign。勿依赖 code:9999 等未定义码。
常见错误码
| code | 说明 | 示例 msg |
|---|
| 200 | 成功 | 请求成功 |
| 400 | 业务/签名错误 | 签名验证失败、商户未配置支付通道… |
| 422 | 参数校验 | 商户编号缺失、签名缺失… |
| 500 | 服务异常 | 生产环境可能为 Server internal error |
对接前置条件
需同时具备：shop_number、secret、后台已关联支付通道、公网可达的 notify_url（JSON 接收 + 响应 success）。跳转支付成功 ≠ 已收到异步通知。
最小对接步骤
- 确认商户已配置支付通道，获取商户号与密钥。
POST /api/prices（档位支付时）。POST /api/pay 或 /api/direct_pay，成功后跳转 data.pay_url。- 实现
notify_url：JSON 验签 + 响应 success。
- （可选）
POST /api/pay_result 查询订单。
开放 API 与异步通知差异
| 项目 | 开放 API | 异步通知 |
|---|
| Content-Type | 推荐 form-urlencoded；亦支持 JSON | application/json;charset=utf-8 |
| 验签字段 | shop_number、timestamp、biz_content | order_sn、shop_number、pay_number、pay_result、pay_time、amount、extra_data（非空） |
| amount | biz 中意向金额 | 订单实付（可能有随机扣减） |
1. 获取价格信息
POST
application/x-www-form-urlencoded 或 JSON
同价多商品合并；/api/pay 时同价随机匹配。channels 为商户已关联的 ALIPAY 通道列表；支付可不传 channel 由系统随机，或传 channels[].id 指定通道。
| 参数名 | 必填 | 参与签名 | 说明 |
|---|
| shop_number | 是 | 是 | 平台商户号 |
| timestamp | 是 | 是 | yyyyMMddHHmmss（14 位） |
| sign | 是 | 否 | MD5 大写 |
{
"code": 200,
"data": {
"channels": [
{ "id": 1, "channel_name": "厦门夏玟", "channel_app_id": "2021006155697017" },
{ "id": 2, "channel_name": "宿州锐科信息科技发展有限公司", "channel_app_id": "2021xxxxxxxxxxxx" }
],
"source": "mall",
"prices": [
{ "key": "13", "amount": "99.00", "name": "网站安全检测基础版" },
{ "key": "24", "amount": "399.00", "name": "Nginx反向代理配置协助" }
]
},
"msg": "请求成功"
}
2. 发起支付 /api/pay
POST
须先调 prices。金额须为档位之一。channel 可选：不传则随机通道；传则须为 channels[].id。pay_type 仅支持字符串：ALIPAY / WECHAT（禁止传 1/2）。返回 amount 为实付（可能有扣减）。
biz_content 示例（验签须与此 JSON 字符串键序一致）：
{
"order_sn": "OR202605221200001",
"key": "24",
"amount": "399.00",
"pay_type": "ALIPAY",
"notify_url": "https://your-domain/notify",
"extra_data": { "from": "api", "mode": "pay" }
}
order_sn：建议 OR 开头，系统不强制。channel（可选）：指定通道 ID；省略时从商户已关联通道随机。pay_type：仅允许 ALIPAY 或 WECHAT（大写字符串），不要传数字 1/2，否则返回 code=400,msg=不支持的支付类型。extra_data：通知中为合并商城字段后的 JSON 字符串，非原样。
返回：
{
"code": 200,
"data": {
"order_sn": "OR202605221200001",
"pay_number": "PO20260522120001",
"amount": "399.00",
"pay_url": "https://...",
"mall_order_sn": "MO20260522120001"
},
"msg": "请求成功"
}
3. 直付支付 /api/direct_pay
POST
无需 prices；自定义金额；随机名义商品；channel 可选（不传则随机通道）。pay_type 仅支持字符串：ALIPAY / WECHAT（禁止传 1/2）。返回 amount 规则同第 2 节。
商户直付限额：总后台可为商户配置金额上下限，仅本接口生效（/api/pay 档位支付不受影响）。未配置不限制；可只配 min 或 max。按请求 amount 闭区间校验。
biz_content 示例：
{
"order_sn": "OR202605221300001",
"channel": "2",
"amount": "128.50",
"pay_type": "ALIPAY",
"notify_url": "https://your-domain/notify",
"extra_data": { "from": "api", "mode": "direct_pay" }
}
返回：
{
"code": 200,
"data": {
"order_sn": "OR202605221300001",
"pay_number": "PO20260522130001",
"amount": "128.50",
"pay_url": "https://...",
"mall_order_sn": "MO20260522130001"
},
"msg": "请求成功"
}
4. 支付结果异步通知
通知请求格式
- POST，
Content-Type: application/json;charset=utf-8
- Body 为 JSON 对象（非 form）
- 商户响应正文：
success
- 未响应 success 时：10 秒、30 秒、2 分钟、10 分钟、30 分钟后重试
字段：
| 字段 | 参与签名 | 说明 |
|---|
| order_sn | 是 | 商户订单号 |
| shop_number | 是 | 商户编号 |
| pay_number | 是 | 平台流水号，一般 PO 开头 |
| pay_result | 是 | success / fail |
| pay_time | 是 | yyyy-MM-dd HH:mm:ss |
| amount | 是 | 订单实付；可能有随机扣减 |
| extra_data | 非空时 | 合并商户+商城字段的 JSON 字符串 |
| sign | 否 | 见第 6 节 |
验签与开放 API 不同：无 timestamp、biz_content。规则见 异步通知验签。
5. 支付信息查询 /api/pay_result
POST
biz_content：
{ "order_sn": "OR202605221200001" }
返回示例：
{
"code": 200,
"data": {
"order_sn": "OR202605221200001",
"shop_number": "202452313486651",
"pay_number": "PO20260522120001",
"pay_result": "success",
"pay_time": "2025-02-24 16:53:54",
"amount": "399.00"
},
"msg": "请求成功"
}
pay_result：waiting / success / fail。响应不含 sign。
联调自检
- API 签名失败：对照第 6 节演算 B 与实际 biz_content 原文字符串。
- 通知验签失败：按 JSON 解析；extra_data 须与通知逐字一致。
- 收不到通知：notify_url 公网可达且返回 success。
6. 签名 / 验签
对接方可直接复制说明（pay_type）
【支付参数规范】
1) pay_type 必须传字符串：ALIPAY 或 WECHAT
2) 不要传数字 1/2（会返回：code=400, msg=不支持的支付类型）
3) 示例："pay_type":"ALIPAY"
开放 API 签名算法
- 参与字段：
shop_number、timestamp、biz_content；sign 不参与。
timestamp 14 位 yyyyMMddHHmmss。- key 升序
k=v&...，空值不参与。
sign = UPPER(MD5(paramStr + secret))。
勿解析 biz 后再序列化；带 extra_data 时勿用演算 A 的串。
演算示例 A（不含 extra_data）
演示 secret：MySecretKey2026
biz_content = {"channel":"1","key":"24","pay_type":"ALIPAY","amount":"399.00","order_sn":"OR202605221200001","notify_url":"https://example.com/notify"}
paramStr =
biz_content={"channel":"1","key":"24","pay_type":"ALIPAY","amount":"399.00","order_sn":"OR202605221200001","notify_url":"https://example.com/notify"}&shop_number=202452313486651×tamp=20260522143000
sign = 7560890832ED5E4E38A97152DB2387B9
演算示例 B（含 extra_data，/index.html 键序）
biz_content = {"order_sn":"OR202605221200001","channel":"1","key":"24","amount":"399.00","pay_type":"ALIPAY","notify_url":"https://example.com/notify","extra_data":{"from":"api","mode":"pay"}}
paramStr =
biz_content={"order_sn":"OR202605221200001","channel":"1","key":"24","amount":"399.00","pay_type":"ALIPAY","notify_url":"https://example.com/notify","extra_data":{"from":"api","mode":"pay"}}&shop_number=202452313486651×tamp=20260522143000
sign = 08E9FA169A0CB89F1F7A6CDF2D28446B
异步通知验签
参与签名（有值才参与）：amount、extra_data、order_sn、pay_number、pay_result、pay_time、shop_number。
extra_data = {"from":"api","mode":"pay","mall_order_id":1001,"mall_order_sn":"MO20260522120001","mall_product_id":24,"mall_product_name":"示例商品","pay_mode":"pay"}
paramStr =
amount=399.00&extra_data={"from":"api","mode":"pay","mall_order_id":1001,"mall_order_sn":"MO20260522120001","mall_product_id":24,"mall_product_name":"示例商品","pay_mode":"pay"}&order_sn=OR202605221200001&pay_number=PO202605221430001&pay_result=success&pay_time=2026-05-22 14:35:10&shop_number=202452313486651
signStr = paramStr + MySecretKey2026
sign = 949C70116BEC6736A475358751072FD0
实际 extra_data 以平台 POST 为准逐字验签；为空则不参与拼接。