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

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

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

• 組み込みのウェブフックを受信した場合
• 個別のウェブフックを受け取った場合

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

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

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

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

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

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

PHP SDK

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

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

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

1. パブリッシャーアカウントでプロジェクトを開き、決済ソリューショント > ウェブフックセクションに移動します。
2. 「ウェブフックサーバー」フィールドに、エクソーラがウェブフックを送信するURLを指定します：

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

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

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

署名の生成

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

署名を生成するには：

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

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

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

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

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

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

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

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

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

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

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

ウェブフックにおけるアイテム情報の構成

注文支払い完了と注文のキャンセルのウェブフックで送信されるアイテムデータは、items配列を通じて設定できます。

追加パラメータの包含の有効化

以下の情報を示す追加パラメータの包含を有効にします：

• アイテムが無料かどう（is_free）
• アイテムがボーナスかどうか（is_bonus）
• アイテムがバンドルの一部かどうか（is_bundle_content）

これらのパラメータを受け取るには、ウェブフック設定に関する情報を更新するAPIコールを使用してウェブフックのバージョンを2に変更してください。バージョン1（デフォルト）では、これらのパラメータは提供されていません。

追加パラメータを含むアイテム配列の例：

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      },
14      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

バンドルコンテンツ包含の無効化

デフォルトでは、ウェブフックはバンドルのすべてのアイテムを個々のアイテムのリストとして含めます。ウェブフックのコンテンツをリスト化せずに、バンドルそのもののみを含めるように設定することができます。

この場合、バンドルに含まれるアイテムはitems配列には含まれません。上記の配列で示されているように、バンドルの一部であるSKUcom.xsolla.gold_1のアイテムは除外されます。

バンドルコンテンツが無効になっている場合のアイテム配列の例：

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ],

バンドルコンテンツ包含を無効にするには、カスタマーサクセスマネージャーまでお問い合わせるか、csm@xsolla.comに電子メールを送信してください。

概要

エクソーライベントAPIを使用すると、GetUpdatesサービスを利用して、サーバー上でウェブフックを使用せずに、アプリケーションクライアントから直接支払い情報を受信および処理できます。支払いウェブフックを処理するために独自のサーバーをセットアップおよび維持する必要性をなくし、統合を迅速化および簡素化したい場合は、この統合オプションを使用してください。

ゲームとエクソーラの間のインタラクション：

設定方法

APIを介してエクソーラからイベントを受信するには：

1. プロジェクトのパブリッシャーアカウントで、決済ソリューショント > ウェブフックセクションに移動します。
2. 「APIを使用する」をクリックします。設定は自動的に保存されます。

3. アプリケーションクライアントから、支払い情報を取得するためにhttps://getupdate.xsolla.com/eventsにリクエストを送信してください。詳細については、APIリファレンスを参照してください。応答として、決済ウェブフックと同じ形式で支払いデータを受け取ります。
4. 支払いが成功した場合、ユーザーに購入を許可します。

APIリファレンス

ユーザーの未処理イベントリストを取得する

1GET https://getupdate.xsolla.com/events

セキュリティ：BearerユーザーJWTトークン

レスポンス例：

 1{
 2  "events": [
 3   {
 4     "id": 49, // event_id
 5     "status": 0,
 6     "created_at": "2025-04-03T21:21:27Z",
 7     "data": {
 8       "notification_type": "payment",
 9       "purchase": {
10         "order": {
11           "id": 000000001,
12           "lineitems": [
13             {
14               "quantity": 1,
15               "sku": "skill"
16             }
17           ]
18         }
19       },
20       ...
21     }
22   }
23 ]
24}

イベントを処理済みとしてマークする

1POST https://getupdate.xsolla.com/events/<event_id>/processed

event_idは、ユーザーの未処理イベントリストを取得するAPIコールのレスポンスから取得されるevents.idパラメータです。

セキュリティ：BearerユーザーJWTトークン