Quy tắc ký yêu cầu: sắp xếp tham số và tính MD5
Chữ ký được tạo ở máy chủ của bạn từ các tham số thực tế gửi trong lần này. Không sao chép giá trị chữ ký ví dụ và không băm MD5 trực tiếp toàn bộ văn bản JSON. Tạo đơn và truy vấn dùng cùng quy tắc ký tham số.
Mục lục bài viết
Tạo sign cho yêu cầu theo năm bước
- Ghép bộ tham số cuối cùng, điền
mchIdcủa bạn vàreqTimehiện tại; chưa thêmsign。 - Loại bỏ
signvà các trường rỗng theo quy chuẩn, giữ những tham số khác thực tế được gửi và không rỗng. - Sắp xếp tên trường tăng dần ASCII, ghép từng mục thành
tên_trường=giá_trị_trườngrồi dùng&để nối. - Thêm ở cuối
&key=và khóa API của đơn vị kinh doanh. - Tính MD5 của chuỗi UTF-8, lấy giá trị băm hệ thập lục phân chữ thường làm
signrồi thêm vào yêu cầu.
Các trường tùy chọn như tiêu đề, mô tả và IP khách hàng cũng phải tham gia ký nếu thực tế được gửi và không rỗng. Sau khi ký, mọi thay đổi số tiền, địa chỉ thông báo hay dấu thời gian đều cần tính lại chữ ký.
Ví dụ cấu trúc chuỗi cần ký
MERCHANT_ID、CURRENT_TIME_MS và MD5_SECRET đều phải được máy chủ thay thế, không gửi nguyên giá trị minh họa.
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_SECRETChữ hoa, chữ thường, dấu gạch dưới và cách viết đều ảnh hưởng giá trị băm. Nếu truy vấn dùng platform_order_no thì phải ký bằng đúng tên trường đó, không thay bằng trường trong phản hồi 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)Ví dụ không chứa gateway, tài khoản hay khóa và không gửi yêu cầu. Hàm chỉ chấp nhận chuỗi, số nguyên và giá trị rỗng, không tự đoán quy tắc tuần tự hóa cho số thực, boolean hay cấu trúc lồng nhau; xác nhận các kiểu bổ sung khi kiểm thử tích hợp.
Thứ tự giữa ký và mã hóa truyền tải
| Tình huống | Cách xử lý đúng |
|---|---|
| POST JSON | Ký tham số nghiệp vụ trước rồi tuần tự hóa bộ tham số có sign thành JSON; quy tắc này không ký trực tiếp văn bản JSON gốc. |
| Truy vấn GET | Ký theo giá trị tham số gốc trước rồi dùng bộ mã hóa URL tạo chuỗi truy vấn. |
| Số tiền và thời gian | Trong ví dụ tạo đơn, amount và reqTime là số nguyên; tránh chuyển thành văn bản có dấu thập phân. |
| Tham số tùy chọn | Tham số tham gia ký phải khớp với nội dung gửi; không bổ sung giá trị mặc định chỉ ở một bên. |
| Giá trị đặc biệt | Kỹ thuật viên xác nhận khi tích hợp các trường hợp biên của chuỗi toàn khoảng trắng, boolean, kiểu phức tạp và ký tự đặc biệt. |
Nên đóng gói việc chuẩn bị tham số, ký và gửi trong cùng một mô-đun máy chủ. Khi gỡ lỗi, ghi tên trường và bản tóm tắt đã che dữ liệu nhạy cảm; không ghi chuỗi cần ký có khóa đầy đủ ở cuối và không đặt chức năng ký ở giao diện.
Tạo dấu thời gian mili giây hiện tại cho mỗi yêu cầu
reqTime là dấu thời gian Unix theo mili giây, mặc định cho phép lệch đồng hồ máy chủ 5 phút. Dùng thời gian giây, thời gian ví dụ cố định hoặc chữ ký cũ sau khi chờ trong hàng đợi đều có thể gây lỗi.
Giữ đồng hồ máy chủ đồng bộ. Mỗi lần tra cứu lại, tạo dấu thời gian mới và tính lại chữ ký nhưng vẫn dùng mã đơn gốc để tìm đơn. Nếu tạo đơn hết thời gian chờ, tra cứu đơn gốc trước; việc thử lại tạo đơn có an toàn hay không phụ thuộc kết quả truy vấn và quy tắc đã xác nhận khi tích hợp.
Xác minh callback và kiểm tra phản hồi
Trường trong JSON Body của callback tiêu chuẩn sign cũng dùng cách sắp xếp, ghép trường không rỗng và MD5 chữ thường, nhưng ưu tiên khóa được cấu hình riêng CALLBACK_SECRET; chỉ khi chưa cấu hình mới dùng MD5_SECRET. Xem chi tiết tại Xác minh callback và giao sản phẩm lũy đẳng。
Giữ nguyên giá trị các trường nhận được để xác minh chữ ký trước rồi mới chuyển đổi nghiệp vụ. Không chuyển sớm chuỗi 00 thành số 0 hoặc chuyển 10.00 thành 10。
Trường phản hồi sign và cách xử lý header chữ ký callback tương thích được kỹ thuật viên xác nhận khi mở và kiểm thử dịch vụ. Với phản hồi chứa cấu trúc lồng nhau data , không được mặc định dùng trực tiếp hàm ký yêu cầu phẳng, cũng không tự suy ra thuật toán cho header tương thích.
Bài này được biên soạn theo quy chuẩn tích hợp 稳付pay. Trước khi tích hợp chính thức, dùng cùng một bộ tham số thử nghiệm đã che dữ liệu nhạy cảm để đối chiếu chuỗi cần ký và giá trị băm với kỹ thuật viên, xác nhận hai bên triển khai thống nhất.
Xác nhận tích hợp theo tình huống kinh doanh của bạn
Trình bày sản phẩm, số lượng đơn, phương thức thanh toán và nhu cầu quyết toán; lần lượt xác nhận API, dòng tiền và xử lý bất thường.
Liên hệ 稳付pay ↗