決済開発

コード販売基盤への決済連携:署名検証・冪等性・在庫ロック・自動納品

コードの自動納品は、「決済成功」という文字列を受け取るたびにコードを渡せばよいわけではありません。確実な処理には、信頼できる決済通知、注文状態、在庫割当、納品ジョブを連携させ、ネットワーク再試行、プロセス再起動、手動修復に対応する必要があります。本稿はベンダーに依存しない一般的な設計です。すべての項目、署名方式、応答内容は実際の連携仕様に従って実装し、稳付payのAPI仕様としてそのまま使用しないでください。

この記事の目次

支払いと納品を別々の状態として管理する

少なくとも、支払い待ち、支払済み、返金済みなどの支払い状態と、未割当、割当済み、納品済み、納品異常などの納品状態を区別します。区別しないと、支払い後に在庫不足が判明した場合、システムは「成功」か「失敗」の二択しか持てず、実際の中間状態を保持できません。

  1. 注文の作成サーバー側で商品・金額・通貨・有効期限を確定する
  2. 支払いの確認署名と項目を検証し、支払いの事実を永続化する
  3. 在庫の割当トランザクション内で注文と対象コードをロックする
  4. 納品の実行永続ジョブを再試行し、納品結果を記録する
ブラウザーの戻り先ページでは進捗を表示できますが、支払いの事実は信頼できるサーバー側の確認処理で確定します。

数量、価格、割引はサーバーで計算し、ブラウザーから送信された最終金額をそのまま採用しません。注文には作成時の価格スナップショットを保存し、その後の値上げで既存注文の支払い条件を変更しないようにします。

署名検証の後、加盟店・金額・注文の所属を照合する

コールバックはバックエンドで処理し、決済仕様に従って署名、署名対象データ、許容時間、鍵を検証します。提供元が生のリクエストボディを要求する場合、フレームワークによる解析や再シリアライズの前に元のバイト列を保持します。StripeのWebhookガイドは、この仕組みの具体例として参考になります。ただし、項目や署名ヘッダーを他のサービスにそのまま適用することはできません。

署名検証の成功は、その鍵に対応するプロトコルにメッセージが合致することを示すだけです。加盟店、注文の所属、決済取引番号、通貨、実際の金額、最終的な成功状態も照合します。金額は単位を明確にした最小通貨単位の整数か精密な固定小数点数で比較し、誤差のある浮動小数点の近似一致に頼ってはいけません。

USDTではネットワーク、受取アドレス、対応する資産識別子も確認し、トークンの表示名だけで判断しません。フロント側のreturn先、決済画面の画像、顧客の申告はこれらの確認の代わりにはなりません。秘密鍵や認証用の鍵はサーバー側に置き、ページのスクリプトに含めないでください。

重複排除にはデータベース制約が必要。「先に照会する」だけでは足りない

障害例1:2件の通知が同時に届き、2つのプロセスがともに未納品と判断して、それぞれコードを発行してしまうケースです。照会から書き込みまでの間には競合があり、単一ホストでも起こり得ます。重複排除はメモリー上の印だけに頼らず、データベースの一意制約とトランザクションで実現する必要があります。

少なくともイベント、決済取引、業務上の納品をそれぞれ重複排除します。同じ支払いから別のイベント番号が発生する場合、イベント番号の一意性だけでは同じ入金を二重に紐付ける可能性があります。同一イベントの再送で状態を再度進めてはいけません。処理済みの通知は、永続記録を確認したうえで仕様に沿って受領を応答できます。

以下は通知テーブル、支払いテーブル、納品ジョブテーブル、在庫割当テーブルに置く一般的な制約の例です。1つのテーブルの完全な作成スクリプトではありません。NOT NULL、適用範囲、実際の構文も合わせて設計してください。PostgreSQLの制約に関するドキュメントでは、一意制約によるデータベース側の保証を説明しています。

UNIQUE (provider, provider_event_id)
UNIQUE (provider, provider_transaction_id)
UNIQUE (order_id, fulfillment_kind)
UNIQUE (card_id)

トランザクションで在庫割当を保護し、最後の1点の過剰販売を防ぐ

支払い成功の処理では、トランザクション内で対象注文をロックし、在庫がすでに割り当てられていないか確認します。未割当コードには行ロックか、状態を条件にした原子的更新を使い、割当記録と注文状態をまとめてコミットします。顧客にコードを渡してから、後でデータベースを販売済みにしようとしてはいけません。

比較して更新するCAS方式を使う場合、更新条件に「まだ使用可能」を含め、更新行数がちょうど1か確認します。0行なら在庫を選び直すか、在庫切れの処理へ進みます。複数商品の注文では一括割当の規則を明確にし、意図せず一部だけ納品しないようにします。

PostgreSQLの行ロックの説明では、同時アクセスを調整する方法を示しています。ロック保持はできるだけ短くし、外部メールやライセンスAPIを長いトランザクションに含めません。デッドロックや再試行可能な競合が起きたら、データベースの意味論に従ってトランザクション全体を再試行し、冪等性を保ちます。

Outboxでデータベースと外部への納品処理をつなぐ

トランザクションなら注文と在庫をまとめて保存できますが、データベースとメール提供元を自動的に同時成功させることはできません。業務データを確定する同一トランザクションで、永続的な納品待ちジョブ、すなわちOutboxを書き込む方法があります。別のワーカープロセスが後で通知を送信し、結果を記録します。

# Generic flow; adapt to the actual provider protocol.
event = verify_provider_request(raw_request)
with database_transaction():
    persist_inbox_event_once(event)
    record_verified_payment_once(event)
    allocate_inventory_if_needed(event.order_id)
    persist_outbox_job_once(event.order_id)
return protocol_ack_after_commit()

これは処理フローの例で、重複イベント、検証失敗、在庫切れの分岐は省略しています。在庫がない場合は「支払済み・対応待ち」と管理された手動タスクを保存し、架空の納品済み記録を作りません。永続化に失敗したのに業務上の受領成功を返してはいけません。仕様に従って再送を促すか、明示的な照会・補償処理に進めます。

受領成功の応答はメール送信の完了を待つ必要はありませんが、通知と後続ジョブが確実に永続化されていることが前提です。永続化しないメモリーキューだけで先に応答すると、再起動によって納品タスクを永久に失うおそれがあります。

在庫切れ・遅延入金・重複実行を分けて処理する

障害例2:注文の期限切れで在庫を解放した後、顧客の支払い通知が遅れて届くケースです。終了済み注文を無視すると入金済みのまま放置され、以前の在庫割当をそのまま使うと、すでに売れたコードを別の顧客に渡す可能性があります。支払いの事実を記録し、在庫と注文規則を再確認して、補充、手動納品、返金のいずれかへ進みます。

ワーカーは、外部での納品が終わってから成功状態を書き戻すまでの間に停止する可能性があります。再試行でも同じ納品番号を使い、外部システムが冪等キーや結果照会に対応するなら優先して利用します。対応していない場合は照合と手動対応の分岐が必要で、ローカルキューだけで外部操作の重複を絶対に防げるとは言えません。

割当済みの同じコードは、管理された経路を通じて元の注文の顧客に再表示できますが、新たな在庫を消費してはいけません。メールの再送と商品の再納品は別の操作であり、管理画面でも権限と監査記録を分ける必要があります。

返金と照合の履歴を残し、支払い記録を削除しない

返金は独立した業務イベントで、申請中、成功、失敗、一部返金などの状態を持ちます。注文を削除したり未払いに戻したりして返金を表現しないでください。元の決済取引、返金参照番号、金額、操作者を記録し、決済側の最終結果と照合します。

デジタル商品が閲覧・引換済みかどうかはアフターサポートに影響しますが、自由に自動返金したり在庫へ戻したりしてよいわけではありません。取り消せないライセンスコードを返金後に販売可能在庫へ戻してはいけません。取り消せるライセンスも、取消結果を確認してから次の処理を決めます。

決済記録とローカルの支払済み注文を定期的に比較し、記録欠落、金額不一致、入金済み未納品、未完了の返金を抽出します。オンチェーン監視通知も一意の業務注文に紐付け、同額の送金だけで所属を推測しません。承認条件や例外的な取引の扱いは導入時に取り決めてください。

障害チェックリストで本番前に検証し、APIの適用範囲を明確にする

  • 偽造通知、不正な署名、別の加盟店、誤った金額では納品を実行しない。
  • 同一イベントの再送や、同一取引に対応する異なるイベントでも、在庫を重複割当しない。
  • 最後の在庫に同時注文が入っても、有効な割当記録は1件だけになる。
  • コミット失敗時は成功を応答せず、コミット後の再起動でも処理を継続できる。
  • メールのタイムアウト、ジョブの中断、外部APIの結果不明を照合できる。
  • 在庫切れ、遅延入金、返金、手動再納品の状態を追跡できる。

稳付payの加盟店管理画面は開発中ですが、監視とコールバックのサービスは利用可能です。現在USDTはTron(TRC20)とEthereum(ERC20)に対応し、資金は加盟店自身のアドレスへ直接入ります。設定されたチェーン承認条件を満たした後に秒単位で業務通知を行うもので、ブロック承認そのものが数秒で終わるという意味ではありません。

本稿では、稳付payの実際のAPIアドレス、署名ヘッダー、鍵の取得手順は提示していません。連携の準備では、まず問い合わせて実際の仕様を確認し、その仕様に基づいてリクエスト検証、応答、注文反映漏れの補完規則を実装し、テスト完了後に公開してください。

参考資料・技術ドキュメント

以下の公式資料は、プロトコルと実装原理の確認に使用しています。コードと事例は技術説明のためのもので、具体的な環境と正式な連携仕様はそれぞれ検証してください。

  1. Stripe:Webhookの検証と重複イベント
  2. PostgreSQL:データベース制約
  3. PostgreSQL:明示的ロックと行ロック
  4. PostgreSQL:トランザクションの原子性
  5. OWASP:取引に使う業務データの検証

サイトをさらに整える

ネットワーク、注文、資金通知まで、業務に合わせて各段階を確認します。決済導入やUSDT監視については、お問い合わせページからご相談ください。

稳付payに問い合わせる ↗