非同期通知

決済コールバック:署名検証・注文照合・冪等な商品提供

コールバックは遅れたり重複して届いたりすることがあります。サーバーでJSONを受信し、署名と注文を検証して成功状態を確実に保存したうえで、安全に再試行できる商品提供処理へ渡してください。

この記事の目次

通知がサーバーに届くタイミング

プラットフォームはチャネルから支払い成功通知を受けて収納代行注文を更新した後、その注文の notifyUrl に非同期で POST,Content-Type は application/json です。注文に通知先がない場合は加盟店の既定アドレスを使用しますが、注文作成時には仕様どおり notifyUrl。

通知エンドポイントは公開インターネットからアクセスできる必要があり、ブラウザーのログイン状態に依存してはいけません。受信するのは稳付payの統一形式であり、上流チャネルの生データを解析する必要はありません。ブラウザーの成功画面や利用者のスクリーンショットは、サーバーでの検証の代わりにはなりません。

標準通知の15項目

項目意味と照合方法
bizType収納代行では固定値 collect。
mchIdローカル注文が属する加盟店と一致する必要があります。
platformOrderNoプラットフォーム注文番号。ローカルの決済記録と関連付けます。
outTradeNo注文作成時に指定した加盟店注文番号。
merchantOrderNo互換用項目。outTradeNoと同じ値です。
transactionIdチャネルの取引番号。チャネルが返さない場合はプラットフォーム注文番号を使用します。
amount金額の単位は分。文字列の例: 1000。
amountYuan金額の単位は元。小数点以下2桁で、例: 10.00。
currencyCode通貨。例: CNY。
orderStatus注文状態。成功通知の例では文字列 1。
tradeState収納代行の成功時は SUCCESS。
returnCode00 は業務処理の成功を表します。
successTime成功日時。形式: yyyy-MM-dd HH:mm:ss。
notifyTime今回の通知日時。形式は上と同じです。
sign業務署名。自分自身の署名計算には含めません。

通知例ではすべての項目が文字列です。まず受信した値をそのまま保持して署名を検証してください。特に 00 および 10.00 は、署名検証前に整形、ゼロの削除、数値への強制変換をしないでください。

署名を検証してから注文と決済結果を照合

  1. JSONを読み取り、各項目の元の値を保持してBodyの sign。
  2. 優先するのは CALLBACK_SECRET で、個別設定がない場合は MD5_SECRET。
  3. signと空の項目を除き、項目名をASCII昇順に並べて連結し、 &key=シークレット を追加して小文字のMD5を計算し、比較します。
  4. 署名検証後に加盟店番号、業務種別、加盟店注文番号、プラットフォーム注文番号を照合し、実在するローカル注文を特定します。
  5. 分単位の金額、通貨、支払い成功状態を確認してから、冪等処理に進みます。

次の値だけを見て returnCode=00 と orderStatus=1 として納品してはいけません。署名、注文の識別、金額、通貨、成功状態をすべて検証し、不一致があれば提供を停止して例外を記録します。

互換ヘッダー X-Plat-Signature の規則は技術担当者が別途確認します。このページではBodyの標準業務署名を使い、JSON原文全体を直接MD5にかける方法ではありません。

Pythonでの署名検証と業務フローの例
import json
import os
from wenfupay_collect_sign import verify_collect_notification

try:
    notice = json.loads(raw_request_body)
except (ValueError, UnicodeDecodeError):
    return http_response(400, "INVALID_JSON")
if not isinstance(notice, dict):
    return http_response(400, "INVALID_JSON_OBJECT")
verified = verify_collect_notification(
    notice,
    api_secret=os.environ["MD5_SECRET"],
    callback_secret=os.environ.get("CALLBACK_SECRET"),
)
if not verified:
    return http_response(400, "INVALID_SIGNATURE")

# Business-specific pseudocode: implement these durable operations.
with database_transaction():
    order = lock_order(notice["outTradeNo"])
    match_merchant_currency_and_amount_in_cents(order, notice)
    require_documented_success_fields(notice)
    record_payment_once(order, notice["platformOrderNo"])
    enqueue_fulfillment_once(order)

# Only after successful durable acceptance:
return http_response(200, "OK", content_type="text/plain")

業務処理関数は流れを示す例です。加盟店自身の注文処理とデータベースへ接続する必要があります。保存失敗、署名不一致、金額不一致の際は先に成功応答を返してはいけません。確実に受理済みの重複通知は、確認後に OK。

同じ注文の支払い記録と商品提供は一度だけ

  1. 検証して注文を特定署名、金額、通貨を確認し、同じ加盟店決済記録を特定します。
  2. トランザクション内で状態更新注文のロックまたは条件付き更新を行い、成功済み通知では二重計上しません。
  3. 一意の商品提供タスクを保存注文の一意キーでコード納品、チャージ、発送のタスクを記録します。
  4. コミット後に確認応答状態とタスクを確実に保存してからOKを返し、商品提供は必要に応じて再試行します。
通知を受信
  署名検証失敗:処理を拒否し、成功確認を返さない
  加盟店・注文・金額・通貨が不一致:例外を記録し、提供しない
  データベーストランザクション開始
    ローカル注文を照会してロック
    未成功なら:支払い成功状態へ更新
    提供タスクの存在を保証、業務一意キー = ローカル注文ID
  データベーストランザクションをコミット
  HTTP 200、プレーンテキストOKを返す

商品提供タスク
  業務一意キーの商品提供が完了済みなら:終了
  それ以外:安全に一度だけ提供して結果を記録
  一時的な失敗:タスクを保持し、業務ルールに従って再試行

これは業務処理の疑似コードであり、そのまま実行できるトランザクションではありません。同じトランザクションで提供を完了できない場合は、永続化したタスクと一意の提供記録を使い、入金成功後のプロセス再起動で納品されないままになる事態を防ぎます。

正しいOK応答と再送への対応

成功確認にはHTTP 200 と、応答Bodyに success、ok と OK が含まれることの両方が必要です。直接 プレーンテキスト OK を返すことを推奨します。ログイン画面、HTMLテンプレート、フレームワーク既定のJSONラッパーは使いません。

処理済みと確認できた重複通知にもOKを返します。データベースが使えない場合や署名・業務検証に失敗した場合、再送を止めるために先に成功を確認してはいけません。

通知が失敗すると非同期で再送され、初回を含めて合計最大3回通知します。最初の2回の失敗後、それぞれ約60秒後、300秒後に再送します。無期限の再送でも、初回とは別に3回送る意味でもありません。

通知が届かない場合は照会で補完

仕様が明記しているのは支払い成功後の通知です。失敗、クローズ、期限切れも必ず通知されると考えてはいけません。長く支払い待ちの注文、作成がタイムアウトした注文、通知処理に問題があった注文は、サーバーから能動的に照会します。

照会で成功を確認したら、コールバックと同じ冪等な提供処理へ進めます。金額照合を省略する別の納品経路は作りません。照会金額の単位は利用開始時に確認してから換算・比較し、結果不明のものは確認待ちに保ちます。

接続テストでは少なくとも、重複通知、照会後の通知、通知後の照会、データベースの一時障害、成功後の商品提供の再試行を検証します。技術担当者が具体的な設定と例外処理の確認を支援します。

本文は稳付pay接続仕様に基づいています。導入概要 に戻るか、注文作成と照会の項目。

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

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

稳付payに問い合わせる ↗