Xsolla-logo

概要

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

イベントの例：

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

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

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

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

支払い処理ウェブフック

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

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

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

ウェブフックの設定に関する詳細情報は、デジタル配信ソリューションのドキュメンテーションを参照してください。

必須なウェブフックのリスト

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

インゲームストアと決済ソリューション

エクソーラ側では、サイトでアイテムを購入して返品する際に2 つのウェブフック送信オプションが設定されています。支払いと取引データ、および購入したアイテムに関する情報は、個別に提供することも、1つのウェブフックにまとめるこ ともできます。

まとめたウェブフックで情報を受け取ります：

If you registered in Publisher Account after January 22, 2025, you receive all the information in the Successful payment for order (order_paid) and Order cancellation (order_canceled) webhooks. In this case, you do not need to process the Payment (payment) and Refund (refund) webhooks.

個別のウェブフックで情報を受け取ります：

2025年1月22日以降にパブリッシャーアカウントに登録した場合は、以下のウェブフックを受け取ります：

すべての受信ウェブフックを処理する必要があります。まとめたウェブフックを受信する新しいオプションに切り替えるには、カスタマーサクセスマネージャーにご連絡いただく か、csm@xsolla.comまで電子メールをお送りください。

インゲームストアと決済管理の完全な運用のためには、主要なウェブフックの処理を実装する必要があります。

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

ウェブフック名とタイプ 説明
ユーザー検証 > ユーザー検証（user_validation） ユーザーがゲームに登録されていることを確認するために、支払いプロセスのさまざまな段階で送信されます。
Game services > Combined webhooks > Successful payment for order (order_paid) 支払いデータ、取引の詳細、購入されたアイテムに関する情報が含まれます。ウェブフックからのデータを使用して、ユーザーにアイテムを追加します。
ゲームサービス > まとめたウェブフック > 注文キャンセル（order_canceled） キャンセルされた支払のデータ、取引の詳細、および購入したアイテムに関する情報が含まれています。ウェブフックからのデータを使用して、購入されたアイテムを削除します。

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

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

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

Note

To receive real payments, you only need to sign the licensing agreement and implement processing of the webhooks:

サブスクリプション

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

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

アドミンページでウェブフックをセットアップする

一般設定

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

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

注意。

データ転送にはHTTPSプロトコルが使用されます。HTTPプロトコルはサポートされていません。

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

注意

ウェブフックをテストするには、webhook.siteのような専用のウェブサイトか、ngrokのようなプラットフォームを選択できます。

注意

異なるURLに同時にウェブフックを送信することはできません。アドミンページでは、まずテスト用のURLを指定し、それを実際のURLに置き換えることができます。

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

  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）
Game services > Combined webhooks > Successful payment for order (order_paid)
ゲームサービス > まとめたウェブフック > 注文キャンセル（order_canceled）
サブスクリプション ユーザー検証 > ユーザー検証（user_validation）
決済ソリューション > 支払い（payment）

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

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

注意

テストセクションにテストがパスしていないという警告が表示された場合は、ウェブフックリスナーのウェブフック応答設定を確認してください。テストでのエラーの理由はテスト結果に示されます。

例：

テストには、専門サイトwebhook.siteを使用します。

「無効な署名に対する応答のテスト」セクションにエラーが表示されます。

エクソーラが間違った署名を持つウェブフックを送信し、ハンドラーがINVALID_SIGNATUREエラーコードを指定する4xx HTTPコードで応答することを期待しているために発生します。

webhook.siteは、署名が間違ったウェブフックを含むすべてのウェブフックに応答して200 HTTPコードを送信します。期待される4xx HTTPコードが得られないため、テスト結果にエラーが表示されます。

テストエラー

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

決済ソリューションとストア

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

テストするには：

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

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

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

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

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

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

User validation, Successful payment for order and Order cancellation webhooks with the specified data are sent to the provided URL. The results of testing each webhook type are displayed below the Test webhooks button.

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

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

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

サブスクリプション

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

注意

アドミンページでは、基本的なユーザー検証および支払いウェブフックのみをテストできます。他のウェブフックタイプをテストするには、次の場所に移動します：

注意

ウェブフックをテストするには、アドミンページ > サブスクリプション > サブスクリプションプランセクションで、少なくとも1つのサブスクリプションプランが作成されている必要があります。

テストするには：

  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アドレスでウェブフックを受信し、署名を生成し、エクソーラウェブフックサーバーに応答を送信することができるプログラムコードです。

注意

Pay Station PHP SDKライブラリには、ウェブフックを処理するための既製のクラスが含まれています。

アプリケーション側で、以下の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コードを返すこともあります。

If the Xsolla server did not receive a response to Successful payment for order and Order cancellation webhooks or received a response with a 5xx code, the webhooks are resent according to the following schedule:

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

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

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

注意

支払いの返金がエクソーラによって開始され、返金ウェブフックに対する応答として`5xx`HTTPコードを含む応答が返された場合でも、支払いは返金されます。

If the Xsolla server did not receive a response to the User validation webhook or received a response with a code of 400 or 5xx, the User validation webhook is not resent. In this case, the user sees an error and the Payment and Successful payment for order webhooks are not sent.

エラー

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"
    }
}

ウェブフックリスト

注意

通知タイプはnotification_typeパラメータで送信されます。

ウェブフック 通知タイプ 説明
ユーザー検証 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 ユーザーがストアと直接交信する時に送信されます。
Successful payment for order order_paid 注文が支払われたときに送信されます。
注文キャンセル order_canceled 注文がキャンセルされたときに送信されます。
紛争 dispute 新しい紛争手続きが開かれたときに送信されます。
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.