注文状況追跡のセットアップ

テスト用ウェブアプリケーションを実装例として使用します：

ユーザーにアイテムを付与するには、支払いが成功したことを確認する必要があります。

作成された注文のステータスを追跡して検証するには、アプリケーションのサーバー側でウェブフック処理を構成する必要があります。

商品を購入して返品する際には、エクソーラ側に2つのウェブフック受信オプションが設定されています。支払いと取引データを含む情報と購入した商品に関する情報は、別々に取得することも、1つのウェブフックにまとめることもできます。

ウェブフック受信オプションの詳細情報

組み込みのウェブフックで情報を受信します：

2025年1月22日以降にアドミンページに登録した、またはプロジェクトを作成した場合、注文支払い完了（order_paid）と注文のキャンセル（order_canceled）のウェブフックですべての情報を受け取ります。この場合、支払い（payment）と返金（refund）ウェブフックを処理する必要はありません。

個別のウェブフックで情報を受信します：

2025年1月22日以前にアドミンページに登録した、またはプロジェクトを作成した場合、以下のウェブフックを受け取ります：

支払いデータや取引の詳細に関する情報を含む支払い（payment）と返金（refund）ウェブフック。
購入したアイテムに関する情報を含む注文支払い完了（order_paid)と注文のキャンセル（order_canceled）ウェブフック。

すべての受信ウェブフックを処理する必要があります。

組み込みのウェブフックを受信する新しいオプションに切り替えるには、カスタマーサクセスマネージャーに連絡するか、csm@xsolla.comに電子メールを送信してください。

インゲームストアと決済管理を完全に操作するには、メインのウェブフックの処理を実装する必要があります：

ウェブフック名	説明
ユーザー検証 > ユーザー検証（`user_validation`）	ユーザーがゲームに登録されていることを確認するため、支払いプロセスのさまざまな段階で送信されます。
ゲームサービス > 組み込みのウェブフック > 注文支払い完了（`order_paid`）	支払いデータ、トランザクションの詳細、購入した商品に関する情報が含まれます。ウェブフックのデータを使用して、ユーザーにアイテムを追加します。
ゲームサービス > 組み込みのウェブフック > 注文のキャンセル（`order_canceled`）	キャンセルされた支払いのデータ、取引の詳細、購入した商品に関する情報が含まれます。ウェブフックのデータを使用して、購入したアイテムを削除します。

以下のスキームは、リストからウェブフックを使用してアイテムを購入して返品するプロセスを示しています。

ウェブフック名	説明
ユーザー検証 > ユーザー検証（`user_validation`）	ユーザーがゲームに登録されていることを確認するため、支払いプロセスのさまざまな段階で送信されます。
決済 > 支払い（`payment`）	支払いデータと取引の詳細が含まれます。
ゲームサービス > 個別のウェブフック > 注文支払い完了（`order_paid`）	購入したアイテムに関する情報とトランザクションIDが含まれています。ウェブフックのデータを使用して、ユーザーにアイテムを追加します。
決済 > 返金（`refund`）	支払いデータと取引の詳細が含まれます。
ゲームサービス > 個別のウェブフック > 注文のキャンセル（`order_canceled`）	購入したアイテムに関する情報とキャンセルされたトランザクションのIDが含まれています。購入した商品を削除するには、ウェブフックのデータを使用します。

以下のスキームは、リストから集約ウェブフックを使用してアイテムを購入して返品するプロセスを示しています。

アイテムカタログのパーソナライゼーションがアプリケーション側で実装されている場合は、パートナー側でカタログのパーソナライゼーションの処理を設定します。

実際の支払いを受け取るには、ライセンス契約に署名し、ウェブフックの処理を実装するだけです：

別々のウェブフックを受信した場合は支払い、注文支払い完了、またはユーザー検証
ウェブフックを組み合わせた場合は注文支払い完了またはユーザー検証

ウェブフックの完全なリストと、ウェブフックの操作に関する一般情報については、ウェブフックのドキュメンテーションを参照してください。

PHP SDK

ウェブフック処理には既製のクラスを使用します。

ウェブフックの送信を設定する

エクソーラ側でウェブフックを構成するには：

アドミンページでプロジェクトを開きます。
サイドメニューで「プロジェクト設定」をクリックし、「ウェブフック」セクションに移動します。
「ウェブフックURL」フィールドに、エクソーラがウェブフックを送信するURLを指定します：

ウェブフックを受信するには、https://example.com形式でサーバーのURLを指定します。データ転送にはHTTPSプロトコルが使用されます。HTTPプロトコルはサポートされていません。

ウェブフックをテストするには、webhook.siteなどの専門サイトや、ngrokなどのプラットフォームを選択することもできます。実際のプロジェクトでは、購入検証ロジックを追加する必要があります。

「ウェブフックを有効にする」をクリックします。

ウェブフックリスナーを追加する

ウェブフックリスナーは、指定されたURLアドレスで受信したウェブフックを受信し、署名を生成し、エクソーラウェブフックサーバーに応答を送信できるようにするプログラムコードです。

署名の生成

ウェブフックを受信する場合、データ伝送のセキュリティを確保する必要があります。そのためには、ウェブフックのデータから署名を生成し、それがHTTPリクエストヘッダで送信された署名と一致することを検証する必要があります。

署名を生成するには：

リクエスト本文のJSONとプロジェクトの秘密鍵を連結します。
最初のステップで取得した文字列にSHA-1暗号化ハッシュ関数を適用します。

ウェブフックへの応答の送信

ウェブフックの受信を確認するには、サーバーが以下のことを返す必要があります：

成功した応答の場合は200、201、または204 HTTPコード。
指定されたユーザーが見つからなかったり、無効な署名が渡された場合、問題に関する説明が記載された400 HTTPコードが表示されます。

ウェブフックハンドラーは、サーバーに一時的な問題が発生した場合に5xxコードを返すこともあります。

エクソーラサーバーが「注文支払い完了」と「注文のキャンセル」のウェブフックで応答を受信しなかった場合、または5xxコードの応答を受信した場合、以下のスケジュールでウェブフックを再送信します：

5分間隔で2回再試行
15分間隔で7回再試行
60分間隔で10回再試行

ウェブフックの送信は、最初の試行から12時間以内に最大20回まで試行されます。

エクソーラサーバーが決済ウェブフックまたは返金ウェブフックに対して応答を受信しない場合、または応答を受信した5xxコード、ウェブフックも時間間隔が長くなって再送される12時間以内に最大12回の試行が行われます。

エクソーラサーバーがユーザー検証ウェブフックに対する応答が受信されなかった場合、400または5xxのコードを含む応答が受信された場合、ユーザー検証ウェブフックは再送信されません。

この場合、ユーザーにはエラーが表示され、「決済」と「注文支払い完了」のウェブフックは送信されません。

ウェブフックの完全なリストとメカニズム、およびその処理の詳細な事例については、ウェブフックドキュメンテーションに記載されています。

ご意見ありがとうございました！

あなたのメッセージを確認し、体験を向上させるために利用させていただきます。

最終更新日: 2025年1月23日

誤字脱字などのテキストエラーを見つけましたか？テキストを選択し、Ctrl+Enterを押します。