デジタルコード販売サイトの詳細な接続手順:商品設定から決済通知・自動納品の検収まで
商品、ドメイン、コード販売システムを用意した後、顧客が支払って自分のライセンスコードを確実に受け取るにはどうすればよいでしょうか。準備、開発、接続テスト、本番公開を一つの導入順に整理します。例は自社保有または販売許諾を得たデジタル商品を対象とし、本文の項目名と疑似コードは対応関係を示すもので、稳付payの実API仕様ではありません。
この記事の目次
ステップ1:商品・決済・提供それぞれの役割を明確にする
最初に3つの境界を整理します。コード販売システムは商品・注文・提供を管理し、決済サービスは取引を識別して通知し、精算処理は合意に従って支払うべき金額を加盟店へ渡します。支払い成功、商品提供済み、精算着金済みは別の事実であり、一つの「完了」スイッチで扱ってはいけません。
- 商品を準備SKU・在庫・購入後対応のルールを決定
- 決済を作成バックエンドで注文金額と決済試行を固定
- 支払いを検証信頼できる通知とサーバー照会を併用
- 自動で提供トランザクションで割り当て、永続タスクで再試行
例えば自作ソフトのアクティベーションコードを売る場合、注文は支払い済み・納品待ちでありながら、まだ今回の精算対象に入っていないことがあります。顧客が支払ったのに精算待ちのため商品を受け取れない状態は、多くの場合これらの経路を誤って結び付けていることを示します。
ステップ2:商品・在庫・実行環境を準備
仕様ごとに安定した商品番号を割り当て、ライセンス期間、対応バージョン、購入数上限、提供方法、問い合わせ先を明確にします。表示価格とサーバー計算の価格には同じ信頼できるデータを使い、ブラウザーに請求額を決定させないでください。
在庫は販売可能、予約済み、割当済み、提供済みに分けます。予約には有効期限と原子的な解放条件が必要で、支払い待ち時間との調整も必要です。支払い確認済み注文を期限処理だけで未払いに戻し、無条件に在庫解放してはいけません。
本番環境には少なくとも有効なHTTPS、独立したテスト設定、信頼できるデータベース、永続タスクのプロセス、バックアップと復元手順を用意します。コードや認証情報は注文に権限を持つ利用者だけに表示し、アクセスログやエラースタックに完全なコード、秘密鍵、決済シークレットを記録しません。
ステップ3:対応機能を確認して項目の対応表を作る
認証、署名の対象、元メッセージの要件、照会機能、決済状態、通知への応答、再送、タイムゾーン、金額精度を実際のプロトコルで確認します。既成プラグインが合わない場合はアダプター層を修正し、ページテンプレートの変更で接続の代わりにしないでください。
| ローカル業務情報 | 接続時の確認事項 | 保存目的 |
|---|---|---|
| 加盟店注文番号 | 長さ・使用文字・一意性の範囲 | 商品・支払い・提供を一貫して関連付け |
| 決済試行番号 | 同じ注文の再試行の識別方法 | タイムアウト後の二重作成を防止 |
| 支払額・通貨 | 単位・精度・許容状態 | 不足払いと通貨不一致を防止 |
| チャネル取引番号・イベント番号 | 有無・有効範囲・照会方法 | 支払いの紐付けと重複通知の排除 |
| 通知先・戻り先 | サーバー通知とブラウザー遷移の違い | 業務確認と進捗表示を分離 |
| ネットワーク・資産・受取アドレス | USDTのネットワークと資産識別子 | 別チェーンや同名トークンの誤認を防止 |
表の名前は業務上の概念にすぎません。最終的な項目と署名方法は双方で確認した実仕様に従い、本文をそのままリクエスト形式として使わないでください。
ステップ4:バックエンドで注文を作成し、各決済試行を保存
顧客が商品を選んだら、バックエンドで価格を再読込し、在庫と購入制限を確認して加盟店注文番号を発行し、金額スナップショット、通貨、有効期限を保存します。決済サービスの呼び出し前に試行記録を保存し、通信断後も「今回のリクエスト」を特定できるようにします。
作成リクエストのタイムアウトは明確な応答が得られなかったことだけを意味し、決済注文が作られなかった証拠ではありません。元の加盟店注文番号または合意した条件で優先的に確認し、提供元が冪等リクエストに対応する場合だけ、同じ業務内容と定められた冪等識別子で安全に再試行します。 Stripeの冪等リクエスト解説で仕組みを理解できますが、すべてのチャネルが同じリクエストヘッダーに対応するとは考えないでください。
顧客が決済方法を選び直しても、以前の試行の所属を保持し、古い通知が新しいチャネル注文に紐付かないようにします。実際に2回支払われた場合は別々に記録して重複支払い処理へ進め、商品を2つ渡して問題を隠してはいけません。
ステップ5:決済案内を表示し、戻り画面では進捗だけを表示
サーバーが取得した決済リンクまたは必要パラメーターをフロントエンドに渡し、注文番号、支払額、有効期限、問い合わせ先を表示します。USDTの導入時は正確なネットワークと受取アドレスも表示し、「USDT」とだけ書いて顧客に推測させないでください。
支払い後のサイトへの復帰、ページ終了、端末変更で、バックエンドの確認処理が変わってはいけません。戻り画面は自社サーバーに進捗を照会するだけとし、URLのsuccessパラメーターから直接提供しません。注文詳細とコード照会にはログイン認証または十分に強い注文アクセス資格情報が必要です。
OWASPの外部決済接続ガイドはサーバー検証と金額一致を重視しています。決済表示でも「送信済み」「確認中」と「支払い済み」を分け、未確認の送金を成功と誤表示しないでください。
ステップ6:バックエンドで署名検証・照会・業務項目の照合
通知を受信したら実際の仕様に従って署名を検証し、加盟店、注文、金額、通貨、成功状態を確認します。元のリクエストBodyが必要な仕様では、解析や書換え前に元のバイト列を保持します。有効な署名だけで業務項目の照合を省略することはできません。
接続方式に応じ、認証済みのサーバー照会で決済状態を確認します。特に通知欠落、作成タイムアウト、状態競合の場合に重要です。照会が一時的に利用不能なら確認待ちにして再試行を予定し、通信エラーを「失敗」と扱ったり、支払いスクリーンショットだけで自動納品したりしないでください。
StripeのWebhookドキュメントでは通知検証、重複配信、順序逆転などが説明されています。受信成功の応答は仕様を満たし、イベントと後続処理の責任を確実に永続化した後に行います。先に応答し、タスクをメモリだけに残すと、プロセス再起動で処理を失うおそれがあります。
ステップ7:支払いと在庫をトランザクションで記録し、コミット後に非同期納品
支払い事実、在庫割当、納品タスクを一緒に保存できる必要があります。同一注文には行ロックか状態条件付き原子更新を用い、イベント、取引、提供には適切な範囲の一意制約を設定します。在庫割当も注文明細と購入数量ごとに一意の所属を持たせ、重複処理では元の割当を返します。タスク未完了を理由にもう1枚取得してはいけません。「存在確認してから書込む」だけでは並行処理を防げません。
# Protocol mapping example, not a runnable payment integration.
event = verify_using_confirmed_protocol(raw_request)
payment = query_and_match_payment(event)
with database_transaction():
lock_order(payment.order_id)
persist_verified_event_once(event)
record_payment_once(payment)
if not fulfillment_exists(payment.order_id):
if allocate_or_reuse_stock_once(payment.order_id):
create_outbox_job_once(payment.order_id, "deliver")
else:
mark_paid_awaiting_stock(payment.order_id)
create_outbox_job_once(payment.order_id, "stock_review")
return acknowledgement_required_by_protocol()
PostgreSQLのトランザクション説明で一括コミットを理解でき、行ロックの仕組みで競合を調整します。外部照会とメール送信は短いトランザクションの外で行います。Outboxは業務データと同時保存するタスク記録で、コミット後にワーカーが実行します。例では例外処理を省略していますが、本番では重複キー、デッドロック、失敗時の再試行も処理してください。
ステップ8:在庫切れ・遅延入金・返金の分岐を補完
支払い確認後に在庫切れと分かった場合は「支払い済み・対応待ち」を保存し、補充、納期調整、返金を運営者へ知らせます。未払いへ戻してはいけません。期限切れ注文に有効な遅延入金が来た場合も、まず支払いを記録し、現時点の在庫と合意ルールで処理して、単に無視しないでください。
メール送信のタイムアウトは、メールが送られなかったことを意味しません。提供タスクの番号を固定し、冪等性対応の外部ライセンスサービスでは同じ識別子を再利用します。非対応なら先に照会または手動確認します。元注文のコード再送と新しいコードの再割当は別操作であり、再送で在庫をもう一度減らしてはいけません。
返金は申請、処理中、成功、失敗を独立した状態として保持し、元取引に関連付けます。表示・使用済みライセンスコードを安易に販売可能へ戻さず、取消可能なライセンスも取消結果を先に確認します。返金や再提供には担当者、理由、関連番号を記録します。
ステップ9:検収マトリクスで例外への対応を実証
接続テストは正常決済1回だけで済ませません。各ケースに注文番号、決済試行番号、検証結果、支払い記録、在庫割当、タスク状態を残し、別の保守担当者も確認できるようにします。
| テスト入力 | 期待する注文結果 | 提供の検収 |
|---|---|---|
| 実際の成功決済 | 支払い済みで取引を照合可能 | 数量が正しく、提供は一度だけ |
| 不正署名または金額 | 成功とせず理由を記録 | 在庫を割り当てない |
| 同じ通知が同時に届く | 同じ支払いの紐付けは一度だけ | 有効な割当は一つだけ |
| 作成タイムアウト・一時的な通知欠落 | 照会で明確な状態へ復旧 | 重複支払いも納品漏れも起こさない |
| 最後の在庫へ同時購入 | 各支払い事実をそれぞれ保存 | 在庫超過販売をせず、在庫切れ注文に対応可能 |
| 遅延入金・ページは終了済み | 支払い済みの事実を保持 | ルールに従い追加納品または購入後対応 |
| コミット後にプロセス再起動 | 永続記録が残る | タスクを復旧し、過剰提供しない |
| 返金と納品が同時に発生 | 独立状態を追跡可能 | 調整ルールに従って競合を処理 |
提供元にテスト環境があれば優先して使います。ない場合は少額実決済、返金、費用のルールを事前確認してください。本文の流れは実チャネルの接続テストの代わりではなく、「検収済み」の証明にもなりません。
ステップ10:段階的に公開し、切り戻し後も既存注文を処理
公開前に復元可能なバックアップ、旧アダプターと設定を保存し、変更後のデータ構造を切り戻せるか確認します。最初は導入範囲を限定し、確認待ち件数、署名検証失敗、支払い済み未提供、タスク滞留、照会異常を監視します。
異常時は新規決済試行を停止できますが、既存注文の通知受信と照合を続け、旧仕様の互換性とシークレット更新計画を保持してください。通知先の削除やキュー消去を「切り戻し」として行うと、既存の支払いが永久に紐付かなくなるおそれがあります。
稳付payはAlipayやWeChatなどのチャネル接続に対応し、収納代行後のUSDT精算は双方の合意に従います。USDTの自有アドレス監視では顧客が加盟店ウォレットへ直接支払います。現在はTron(TRC20)とEthereum(ERC20)に対応し、設定した承認条件を満たした後に秒単位の業務通知を行います。ブロック承認自体が数秒という意味ではありません。加盟店管理画面は開発中のため、まず 仕様・精算条件・接続テスト範囲を問い合わせて確認 し、その後対応するアダプター層を実装してください。
参考資料・技術ドキュメント
公式資料は一般的な技術原理の確認用です。例は実際のAPI仕様と稼働環境に合わせて検証する必要があります。