请求签名规则:参数排序与MD5计算
签名在你的服务端完成,使用本次实际提交的参数计算。不要复制示例签名值,也不要把整个 JSON 文本直接做 MD5。下单和查询使用相同的参数签名规则。
文章目录
按五步生成请求sign
- 组装最终参数,填写自己的
mchId和当前reqTime,先不放sign。 - 排除
sign和规范所说的空字段,保留其余实际提交的非空参数。 - 字段名按 ASCII 升序排列,逐项拼成
字段名=字段值,再用&连接。 - 末尾追加
&key=与商户 API 密钥。 - 对 UTF-8 字符串计算 MD5,取小写十六进制摘要,作为
sign加入请求。
可选的标题、说明和客户端 IP,只要实际提交且非空,也要参与签名。签名完成后修改金额、通知地址或时间戳,都必须重新计算。
待签名字符串结构示例
MERCHANT_ID、CURRENT_TIME_MS 和 MD5_SECRET 均需后端替换,不可原样提交。
amount=1000¤cyCode=CNY&mchId=MERCHANT_ID¬ifyUrl=https://merchant.example.com/pay/notify&outTradeNo=DEMO_COLLECT_001&reqTime=CURRENT_TIME_MS&wayCode=80001&key=MD5_SECRET大小写、下划线和拼写都会影响摘要。查询使用 platform_order_no 时,就以该字段名参与签名,不能替换成响应中的 platformOrderNo。
"""Example-only helpers for the documented flat collection signing protocol.
No HTTP calls or credentials are included. Configure secrets on your server.
The supported example input values are strings, integers and null. Confirm
additional value types, response signatures and channel limits during setup.
"""
from __future__ import annotations
import hashlib
import hmac
import re
from collections.abc import Mapping
def sign_collect(parameters: Mapping[str, object], secret: str) -> str:
"""Sort nonempty flat scalar fields, append the secret, return MD5 hex."""
if not isinstance(secret, str) or not secret:
raise ValueError("A server-side secret is required")
values: dict[str, str] = {}
for name, value in parameters.items():
if not isinstance(name, str) or not re.fullmatch(r"[A-Za-z0-9_]+", name):
raise ValueError("Use the exact documented ASCII field names")
if name == "sign" or value is None or value == "":
continue
if isinstance(value, bool) or not isinstance(value, (str, int)):
raise TypeError("This example accepts only strings and integers")
values[name] = str(value)
canonical = "&".join(name + "=" + values[name] for name in sorted(values))
signed_text = canonical + "&key=" + secret
return hashlib.md5(signed_text.encode("utf-8")).hexdigest()
def verify_collect_notification(
parameters: Mapping[str, object],
api_secret: str,
callback_secret: str | None = None,
) -> bool:
"""Verify the JSON field signature, preserving all received string values."""
if not isinstance(parameters, Mapping):
return False
supplied = parameters.get("sign")
if not isinstance(supplied, str) or not re.fullmatch(r"[0-9a-f]{32}", supplied):
return False
secret = callback_secret or api_secret
try:
expected = sign_collect(parameters, secret)
except (ValueError, TypeError):
return False
return hmac.compare_digest(expected, supplied)示例不包含网关、账户或密钥,也不会发起请求。它只接受字符串、整数和空值,不对浮点、布尔或嵌套结构自行猜测序列化规则;额外类型请在联调时确认。
签名与传输编码的先后顺序
| 场景 | 正确处理 |
|---|---|
| POST JSON | 对业务参数签名,再把带 sign 的参数序列化为 JSON;不是对 JSON 原文做本规则签名。 |
| GET 查询 | 先按原参数值签名,再使用 URL 编码器构造查询串。 |
| 金额与时间 | 下单示例 amount、reqTime 为整数,避免变成带小数点的文本。 |
| 可选参数 | 参与签名的参数与发送内容一致,不要只在其中一侧补默认值。 |
| 特殊值 | 空白字符串、布尔值、复杂类型及特殊字符边界,由技术人员在联调时确认。 |
建议把参数整理、签名和发送封装在同一后端模块。调试记录字段名和脱敏摘要,不要记录末尾带完整密钥的待签名串,也不要把签名功能放到前端。
每次请求生成当前毫秒时间
reqTime 为毫秒级 Unix 时间戳,默认容许与服务端时钟相差 5 分钟。秒级时间、固定示例时间或排队后复用旧签名,都可能导致失败。
服务器保持时间同步。重新查询时生成新时间戳并重算签名,仍用原订单号定位订单。下单超时先查原单,是否可安全重试创建,由查询结果和技术对接规则决定。
回调验签与响应验证
标准回调 JSON Body 中的 sign 同样使用非空字段排序拼接和小写 MD5,但密钥优先取单独配置的 CALLBACK_SECRET,未配置才取 MD5_SECRET。详情见回调验签与幂等交付。
先保留收到的字段原值验签,再做业务转换。不要提前把字符串 00 变成数字 0,或把 10.00 变成 10。
响应 sign 和兼容回调签名头的处理细节,在开通联调时由技术人员确认。含嵌套 data 的响应不能直接假定使用扁平请求函数,也不要自行推导兼容头算法。
本文依据稳付pay接入规范整理。正式接入前,用同一组脱敏测试参数与技术人员核对待签名串和摘要,确认两端实现一致。