署名と署名検証

リクエスト署名ルール:パラメーターの並べ替えとMD5計算

署名はサーバー側で、その回に実際に送信するパラメーターを使って計算します。例の署名をコピーしたり、JSONテキスト全体を直接MD5にかけたりしないでください。注文作成と照会は同じパラメーター署名ルールです。

この記事の目次

5つの手順でリクエストsignを生成

  1. 最終パラメーターを組み立て、自分の mchId と現在の reqTime を設定し、まだ sign。
  2. 除外するのは sign と仕様上の空項目です。それ以外の、実際に送る非空パラメーターは保持します。
  3. 項目名をASCII昇順に並べ、各項目を 項目名=項目値 の形にして、 & でつなぎます。
  4. 末尾に &key= と加盟店APIシークレットを追加します。
  5. UTF-8文字列のMD5を計算し、小文字16進数のダイジェストを sign としてリクエストに加えます。

任意のタイトル、説明、クライアントIPも、実際に送信し空でなければ署名に含めます。署名後に金額、通知先、タイムスタンプを変更した場合は再計算が必要です。

署名元文字列の構造例

MERCHANT_ID、CURRENT_TIME_MS および MD5_SECRET はすべてバックエンドで置き換え、そのまま送信しないでください。

amount=1000&currencyCode=CNY&mchId=MERCHANT_ID&notifyUrl=https://merchant.example.com/pay/notify&outTradeNo=DEMO_COLLECT_001&reqTime=CURRENT_TIME_MS&wayCode=80001&key=MD5_SECRET

大文字・小文字、アンダースコア、綴りはすべてダイジェストに影響します。照会で platform_order_no を使う場合は、その項目名で署名し、応答中の platformOrderNo。

Python・署名と署名検証のみ
"""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)

Python署名サンプルをダウンロード

例にはゲートウェイ、アカウント、シークレットを含まず、通信も行いません。文字列、整数、空値だけを受け付け、浮動小数点、真偽値、入れ子構造の直列化を独自に推測しません。それ以外の型は接続テスト時に確認してください。

署名と送信用エンコードの順序

場面正しい処理
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接続仕様に基づいています。正式接続前に、同じマスク済みテストパラメーターで署名元文字列とダイジェストを技術担当者と照合し、両者の実装が一致することを確認してください。

事業の内容に合わせて導入を確認

商品、注文量、決済方法、精算要件を伝え、インターフェース、資金の流れ、例外処理を一つずつ確認します。

稳付payに問い合わせる ↗