ウェブフックは、システムで発生するイベントに関する通知です。特定のイベントが発生すると、エクソーラはHTTPリクエストを送信し、イベントデータがアプリケーション に送信されます。通常、これはJSON形式のPOSTリクエストです。

イベントの例：

• アイテムカタログとのユーザーインタラクション
• 注文の決済またはキャンセル

設定されたイベントが発生すると、エクソーラはウェブフック経由でシステムにそれを通知します。その結果、次のようなアクションを実行できます：

• ユーザーの残高を補充する
• 支払いを返金する
• ユーザーアカウントから新しいアイテムをクレジットまたはデビットする
• サブスクリプションの提供を開始する
• 詐欺の疑いがある場合にユーザーをブロックする

支払い処理ウェブフックのワークフローの例：

エクソーラウェブフック統合のビデオガイド：

エクソーラ製品およびソリューションを使用する場合のウェブフック設定：

製品/ソリューション	必須/任意	ウェブフックは何に使用されますか
決済ソリューション	必須	ユーザー検証。 支払いが成功した場合や支払いが返金された場合に、トランザクションの詳細情報を受け取ります。 ユーザーに購入したアイテムを付与し、注文がキャンセルされた場合にアイテムを差し引きます。
インゲームストア	必須	ユーザー検証。 支払いが成功した場合や支払いが返金された場合に、トランザクションの詳細情報を受け取ります。 ユーザーに購入したアイテムを付与し、注文がキャンセルされた場合にアイテムを差し引きます。
ゲーム販売	任意	ゲームキーの販売では、ユーザーの検証やアイテムの付与は必要ありません。支払いや注文キャンセルなどのイベントに関する情報を受け取りたい場合は、ウェブフックを接続することができます。 ウェブフックを接続する場合は、すべての受信した必要なウェブフックを処理することが重要です。
サブスクリプション	任意	サブスクリプションの作成、更新、またはキャンセルに関する情報を受け取ります。または、API経由で情報をリクエストすることもできます。
ウェブショップ	必須	ユーザー検証。 支払いが成功した場合や支払いが返金された場合に、トランザクションの詳細情報を受け取ります。 ユーザーに購入したアイテムを付与し、注文がキャンセルされた場合にアイテムを差し引きます。 ユーザー認証、ユーザーIDによる認証を使用する場合。または、エクソーラログイン経由でユーザー認証を使用することもできます。
デジタル配信ソリューション	必須	ユーザー検証。 エクソーラ側のトランザクションIDをシステムのトランザクションIDにリンクします。 注文に追加のトランザクションパラメータを転送します。 ユーザーに購入したアイテムを付与し、注文がキャンセルされた場合にアイテムを差し引きます。 ウェブフックの設定に関する詳細情報は、デジタル配信ソリューションのドキュメンテーションを参照してください。

ウェブフックの操作が必要な製品やソリューションを使用している場合、アドミンページでウェブフックを有効化してテストし、その処理をセットアップしてください。特定のイベントが発生する時、ウェブフックが順次送信されます。したがって、1つのウェブフックを処理 しない場合、その後のウェブフックは送信されません。必要なウェブフックのリストは以下の通りです。

エクソーラ側では、サイトでアイテムを購入して返品する際に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）	購入したアイテムに関する情報が含まれています。ウェブフックからのデータを使用して、ユーザーにアイテムを追加します。
決済ソリューション > 返金（refund）	支払いデータと取引の詳細が含まれています。
ゲームサービス > 個別のウェブフック > 注文キャンセル（order_canceled）	購入したアイテムとキャンセルされたトランザクションのIDに関する情報が含まれます。ウェブフックのデータを使用して、購入したアイテムを削除します。

アイテムカタログの個人用設定がアプリケーション側で実装されている場合は、パートナー側でのカタログ個人用設定ウェブフックの処理を設定します。

サブスクリプションプランを自動的に管理するには、主要なウェブフックの処理を実装する必要があります：

• ユーザーの検証（user_validation） — 決済プロセスのさまざまな段階で送信され、ユーザーがゲームに登録されていることを確認します。
• 決済（payment） — 注文が支払われたときに送信され、決済データとトランザクションの詳細が含まれます。
• 作成されたサブスクリプション（create_subscription） — 決済ウェブフックが正常に処理されたとき、またはユーザーが試用期間付きのサブスクリプ ションを購入したときに送信されます。これは購入したサブスクリプションの詳細とユーザーデータを含んでいます。ウェブフックデータを使用して、ユーザーにサブスクリプシ ョンを追加します。
• 更新されたサブスクリプション（update_subscription） — サブスクリプションが更新または変更されたとき、決済ウェブフックが正常に 処理されたときに送信されます。購入したサブスクリプションの詳細とユーザーデータが含まれます。ウェブフックデータを使用して、ユーザーのサブスクリプションを延長する か、サブスクリプションパラメータを変更します。
• 返金（refund） — 注文がキャンセルされたときに送信され、キャンセルされた決済データとトランザクションの詳細が含まれます。
• キャンセルされたサブスクリプション（cancel_subscription） — 返金ウェブフックが正常に処理されたとき、またはサブスクリプションが別の理由でキャンセ ルされたときに送信されます。サブスクリプションとユーザーデータに関する情報を含んでいます。ウェブフックデータを使用して、ユーザーから購入したサブスクリプションを 差し引きます。

ウェブフックの受信を有効にするには：

1. パブリッシャーアカウントのプロジェクトで、プロジェクト設定 > ウェブフックセクションに移動します。
2. ウェブフックサーバーフィールドには、ウェブフックを受信したいサーバーのURLを https://example.com 形式で指定します。ウェブフックをテストするツールで見つけたURLを指定することもできます。

3. プロジェクトのウェブフックに署名するための秘密鍵は、デフォルトで生成されます。新しい秘密鍵を生成したい場合は、更新アイコンをクリックしてください。
4. 「ウェブフックを有効にする」をクリックします。

ウェブフックの受信を無効にするには：

1. パブリッシャーアカウントのプロジェクトで、プロジェクト設定 > ウェブフックセクションに移動します。
2. 「ウェブフックを無効にする」をクリックします。

ウェブフックについては決済ソリューションとストアセクションでは、詳細設定が利用できます。「ウェブフックを取得」ボタンをクリックする と、自動的に一般設定ブロックの下に表示されます。

このセクションでは、ウェブフックでの追加情報の受信を設定できます。これを行うには、対応するスイッチをアクティブポジションに設定します。各権限の行は、設定の変更に よって影響を受けるウェブフックを示します。

トグル	説明
保存された決済アカウントに関する情報を表示する	保存された決済方法に関する情報は、payment_accountカスタムオブジェクト。
保存された決済方法による取引に関する情報を表示する	情報は、パラメータの以下のカスタムパラメータに渡されます： saved_payment_method: 0 — 保存された決済方法は使用されませんでした 1 — 決済方法は現在の支払い時に保存されました 2 — 保存された決済方法は使用されませんでした payment_type: 1 — 一回払い 2 — 定期支払い
注文オブジェクトをウェブフックに追加する	注文に関する情報は、決済ウェブフックのorderオブジェクトに渡されます。
機密データは含まず、必要なユーザーパラメータのみを送信する	ウェブフックでは、ユーザーに関する次の情報のみが渡されます： ID 国
カスタムパラメータを送信する	カスタムトークンパラメータに関する情報は、ウェブフックで渡されます。
カードのBINとサフィックスを表示する	銀行カード番号に関する次の情報がウェブフックで渡されます。 card_binパラメータの最初の6桁 card_suffixパラメータの最後の4桁
カードブランドを表示する	決済に使用したカードのブランド。例えば、MastercardやVisaなど。

ウェブフックをテストすると、ユーザー側とエクソーラ側の両方でプロジェクトが正しく設定されていることを確認できます。

ウェブフックが正常にセットアップした場合、ウェブフック設定セクションの下にウェブフックのテストセクションが表示されます。

アドミンページのテストセクションは、ウェブフック受信オプションによって異なります。

まとめたウェブフックを受信する場合：

ウェブフックテストのタブ名	ウェブフック名とタイプ
決済ソリューションとストア	ユーザー検証 > ユーザー検証（user_validation）
	ゲームサービス > まとめたウェブフック > 注文支払い完了（order_paid）
	ゲームサービス > まとめたウェブフック > 注文キャンセル（order_canceled）
サブスクリプション	ユーザー検証 > ユーザー検証（user_validation）
	決済ソリューション > 支払い（payment）

個別のウェブフックを受信する場合：

ウェブフックテストのタブ名	ウェブフック名とタイプ
ストア	ゲームサービス> 個別のウェブフック> 注文支払い完了（order_paid）
	ゲームサービス > 個別のウェブフック > 注文キャンセル（order_canceled）
決済ソリューション	ユーザー検証 > ユーザー検証（user_validation）
	決済ソリューション > 支払い（payment）
サブスクリプション	ユーザー検証 > ユーザー検証（user_validation）
	決済ソリューション > 支払い（payment）

まとめたウェブフックを使用したシナリオのテストプロセスを以下に説明します。

「決済ソリューションとストア」タブでは、次のウェブフックをテストできます：

• ユーザー検証（user_validation）
• 注文の支払いが完了しました（order_paid）
• 注文キャンセル（order_canceled）

テストするには：

1. ウェブフックのテストセクションで、「決済ソリューションとストア」タブに移動します。

2. ドロップダウンメニューで、アイテムのタイプを選択します。選択したタイプのアイテムがアドミンページに設定されていない場合は、以下をクリックします：

   • 接続 – このタイプのアイテムを含むモジュールが接続されていない場合
   • 構成 – 以前にモジュールを接続したが、セットアップを完了していない場合
     ボタンをクリックすると、選択したアイテムのタイプに対応するアドミンページのセクションにリ ダイレクトされます。アイテムを作成したら、ウェブフックのテストセクションに戻り、次のステップに進みます。

3. 必要なフィールドに入力します：

   1. ドロップダウンリストからアイテムのSKUを選択し、数量を指定します。同じタイプのアイテムを複数選択するには、「 + 」をクリックして新しい行に追加します。
   2. ユーザーID — テスト時には、文字と数字の任意の組み合わせを使用できます。
   3. パブリックユーザーID — ユーザーに知られているID（メールアドレスやニックネームなど）。このフィールドは、プロジェクトで「ペイステーション > 設定」でパブリックユーザーIDが有効になっている場合に表示されます。
   4. エクソーラ注文IDフィールドに任意の値を入力します。
   5. エクソーラ請求書ID — エクソーラ側のトランザクションID。テスト時には任意の数値を使用できます。
   6. 請求書ID — ゲーム側のトランザクションID。 テスト時には、文字と数字の任意の組み合わせを使用できます。これは支払いを成功させるために必要なパラメータではありませんが、これを渡すことで、ゲーム側のトランザク ションIDをエクソーラ側のトランザクション ID にリンクできます。
   7. 金額 — 支払い金額。テスト時には任意の数値を使用できます。
   8. 通貨 — ドロップダウンリストから通貨を選択します。

4. 「ウェブフックをテスト」をクリックします。

指定されたデータを含むユーザー検証、注文支払い完了および注文キャンセルウェブフックが、指定されたURLに送信されます。各ウェブフックタイプのテスト結果は、「ウェブフックをテス ト」ボタンの下に表示されます。

プロジェクトでパブリックユーザー IDが有効になっている場合は、ユーザー検索チェックの結果も表示されます。

各ウェブフックについて、成功したシナリオとエラーが発生したシナリオの両方の処理を設定する必要があります。

！支払いテストセクション

「サブスクリプション」タブでは、次のウェブフックをテストできます：

• ユーザー検証（user_validation）
• 決済（payment）

テストするには：

1. テストセクションで、サブスクリプションタブに移動します。
2. 必要なフィールドに入力してください：
   1. ユーザーID — テスト時には、文字と数字を任意に組み合わせて使用できます。
   2. エクソーラインボイスID — エクソーラ側のトランザクションID。テスト時には、任意の数値を使用できます。
   3. パブリックユーザーID — メールアドレスやニックネームなど、ユーザーに知られているID。このフィールドは、「ペイステーション > 設定 > 追加設定」セクションでプロジェクトのパブリックユーザーIDが有効になっている場合に表示されます。
   4. 通貨— ドロップダウンリストから通貨を選択します。
   5. プランID — サブスクリプションプラン。ドロップダウンリストからプランを選択します。
   6. サブスクリプション製品 — ドロップダウンリストから製品を選択します（任意）。
   7. 金額- 支払金額。テスト時には、任意の数値を使用できます。
   8. インボイスID — ゲーム側のトランザクションID。テスト時には、文字と数字を任意に組み合わせて使用できます。これは決済を成功させるために必要なパラメータではありませんが、エクソー ラ側のトランザクションIDとあなた側のトランザクションIDをリンクさせるために渡すことができます。
   9. 試用期間。試用期間 のないサブスクリプションの購入をテストする、またはサブスクリプションの更新をテストするには、値0を指定します。
3. 「ウェブフックをテストする」をクリックします。

指定したURLに、データが入力されたウェブフックを受け取ります。各ウェブフックのテスト結果は、成功したシナリオとエラーが発生したシナリオの両方で、「ウェブ フックをテストする」ボタンの下に表示されます。

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

アプリケーション側で、以下のIPアドレスからのウェブフックの受信を実装します：185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197。

制限：

• アプリケーションのデータベースに同じIDで成功したトランザクションが複数存在することは許可されていません。
• ウェブフックリスナーがデータベースにすでに存在するIDを持つウェブフックを受信した場合、このトランザクションの以前の処理結果を返す必要があります。ユーザーに重複 した購入をクレジットし、データベースに重複したレコードを作成することは推奨されません。

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

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

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

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

• 成功した応答の場合は、200、201、または204HTTPコード。
• 400HTTPコードは問題の説明を含む、指定されたユーザーが見つからないか、無効な署名が渡 された場合に送信されます。ウェブフックハンドラーは、サーバーで一時的な問題が発生した場合に5xxHTTPコードを返すこともあります。

エクソーラサーバーが 注文支払い完了と注文キャンセルへのレスポンスを受け取らなかった場合、または5xxコードのレスポンスを受け取った場合、ウェブフックは以下の スケジュールに従って再送されます：

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

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

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

エクソーラサーバーがユーザー認証ウェブフックへの応答を受信しなかった場合、または400または5xxのコードで応答を受信した場合、ユーザー認証ウェブフックは再送信されません。この場合、ユーザーにはエラーが表示され、支払いと注文支払い完了ウェブフックは送信されません。

HTTPコード400のエラーコード：

コード	メッセージ
INVALID_USER	無効なユーザー
INVALID_PARAMETER	無効なパラメータ
INVALID_SIGNATURE	無効な署名
INCORRECT_AMOUNT	不正確な金額
INCORRECT_INVOICE	不正確なインボイス

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

ウェブフック	通知タイプ	説明
ユーザー検証	user_validation	ユーザーがゲーム内に存在するかどうかを確認するために送信されます。
ユーザー検索	user_search	パブリックユーザーIDに基づいてユーザー情報を取得するために送信されます。
決済	payment	ユーザーが決済を完了した場合に送信されます。
返金	refund	何らかの理由で決済をキャンセルする必要がある場合に送信されます。
一部返金	partial_refund	何らかの理由で決済を一部キャンセルする必要がある場合に送信されます。
AFSが拒否したトランザクション	afs_reject	AFSチェック中にトランザクションが拒否された場合に送信されます。
AFSが更新したトランザクション	afs_black_list	AFSブロックリストが更新される場合に送信されます。
作成されたサブスクリプション	create_subscription	ユーザーがサブスクリプションを作成する場合に送信されます。
更新されたサブスクリプション	update_subscription	サブスクリプションが更新または変更された場合に送信されます。
キャンセルされたサブスクリプション	cancel_subscription	サブスクリプションがキャンセルされた場合に送信されます。
非更新サブスクリプション	non_renewal_subscription	ステータスが非更新に設定される場合に送信されます。
決済アカウントを追加する	payment_account_add	ユーザーが支払いアカウントを追加または保存した場合に送信されます。
決済アカウントを削除する	payment_account_remove	ユーザーが保存済みアカウントから決済アカウントを削除する場合に送信されます。
ウェブショップでのユーザー検証	-	ウェブショップのサイトから送信され、ゲーム内にユーザーが存在するかどうかを確認します。
パートナー側でのカタログ個人用設定	partner_side_catalog	ユーザーがストアと直接交信する時に送信されます。
注文支払い完了	order_paid	注文が支払われたときに送信されます。
注文キャンセル	order_canceled	注文がキャンセルされたときに送信されます。
紛争	dispute	新しい紛争手続きが開かれたときに送信されます。