請求簽名規則:參數排序與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接入規范整理。正式接入前,用同一組脫敏測試參數與技術人員核對待簽名串和摘要,確認兩端實現一致。