# ウェブフック # 概要 {% #overview %} ウェブフックは、システムで発生するイベントに関する通知です。特定のイベントが発生すると、エクソーラはHTTPリクエストを送信し、イベントデータがアプリケーション に送信されます。通常、これはJSON形式のPOSTリクエストです。 イベントの例： - アイテムカタログとのユーザーインタラクション - 注文の決済またはキャンセル 設定されたイベントが発生すると、エクソーラはウェブフック経由でシステムにそれを通知します。その結果、次のようなアクションを実行できます： - ユーザーの残高を補充する - 支払いを返金する - ユーザーアカウントから新しいアイテムをクレジットまたはデビットする - サブスクリプションの提供を開始する - 詐欺の疑いがある場合にユーザーをブロックする 支払い処理ウェブフックのワークフローの例： ![支払い処理ウェブフック](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks-general.svg)

注意

使用されるソリューションとその統合のタイプに応じて、ウェブフックのセットとインタラクションのシーケンスは、提供された例とは異なる場合があります。

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

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

イベント情報の受信：

  • ユーザー登録/認証
  • ユーザーメールアドレスの確認
  • ユーザーのソーシャルメディアアカウントをリンクする

ウェブフックの設定の詳細については、ログインに関するドキュメントを参照してください。
# Xsolla Business Accounts {% #business-accounts %} Business Account is the primary tool for configuring Xsolla features, as well as for working with analytics and transactions. Xsolla develops tools for different business categories. To simplify navigation, these tools are grouped into separate accounts by target audience: * [mobile games](https://xsolla.com/for/mobile-games/account/) * [free-to-play PC games](https://xsolla.com/for/free-to-play-pc/account/) * [premium PC games](https://xsolla.com/for/premium-pc-games/account/) * [web games](https://xsolla.com/for/web-games/account/)

注意

Publisher Account is a legacy tool.

# 必須なウェブフックのリスト {% #list-of-required-webhooks %} If you use products and solutions that require working with webhooks, enable and test the webhooks in your account and set up their processing. When specific events occur, webhooks are sent sequentially. Therefore, if you do not process one of the webhooks, subsequent webhooks will not be sent. The list of required webhooks is presented below. ## ストアと決済ソリューション {% #store-and-payments %} エクソーラ側では、サイトでアイテムを購入して返品する際に2 つのウェブフック送信オプションが設定されています。支払いと取引データ、および購入したアイテムに関する情報は、個別に提供することも、1つのウェブフックにまとめるこ ともできます。 まとめたウェブフックで情報を受け取ります： If you registered in the [account](#business-accounts) 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. 個別のウェブフックで情報を受け取ります： If you registered in Publisher Account on or before January 22, 2025, you receive the following webhooks: - 支払い （`payment` ） そして返金 （`refund` ）に支払いデータと取引の詳細に関する情報が記載されます。 - 購入したアイテムに関する情報を含む注文支払い完了（`order_paid`）と注文キャンセル（`order_canceled`）。 すべての受信ウェブフックを処理する必要があります。まとめたウェブフックを受信する新しいオプションに切り替えるには、カスタマーサクセスマネージャーにご連絡いただく か、csm@xsolla.comまで電子メールをお送りください。 インゲームストアと決済管理の完全な運用のためには、主要なウェブフックの処理を実装する必要があります。 まとめたウェブフックを受信する場合：
ウェブフック名とタイプ 説明
ユーザー検証 > ユーザー検証（user_validation） ユーザーがゲームに登録されていることを確認するために、支払いプロセスのさまざまな段階で送信されます。
ゲームサービス > まとめたウェブフック > 注文支払い完了（order_paid） 支払いデータ、取引の詳細、購入されたアイテムに関する情報が含まれます。ウェブフックからのデータを使用して、ユーザーにアイテムを追加します。
ゲームサービス > まとめたウェブフック > 注文キャンセル（order_canceled） キャンセルされた支払のデータ、取引の詳細、および購入したアイテムに関する情報が含まれています。ウェブフックからのデータを使用して、購入されたアイテムを削除します。
個別のウェブフックを受信する場合：
ウェブフック名とタイプ 説明
ユーザー検証 > ユーザー検証（user_validation） ユーザーがゲームに登録されていることを確認するために、支払いプロセスのさまざまな段階で送信されます。
決済ソリューション > 支払い（payment） 支払いデータと取引の詳細が含まれています。
ゲームサービス> 個別のウェブフック> 注文支払い完了（order_paid） 購入したアイテムに関する情報が含まれています。ウェブフックからのデータを使用して、ユーザーにアイテムを追加します。
決済ソリューション > 返金（refund） 支払いデータと取引の詳細が含まれています。
ゲームサービス > 個別のウェブフック > 注文キャンセル（order_canceled） 購入したアイテムとキャンセルされたトランザクションのIDに関する情報が含まれます。ウェブフックのデータを使用して、購入したアイテムを削除します。
アイテムカタログの個人用設定がアプリケーション側で実装されている場合は、パートナー側でのカタログ個人用設定ウェブフックの処理を設定します。

注意

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

## サブスクリプション {% #required-webhooks-subscriptions %} サブスクリプションプランを自動的に管理するには、主要なウェブフックの処理を実装する必要があります： - ユーザーの検証（`user_validation`） — 決済プロセスのさまざまな段階で送信され、ユーザーがゲームに登録されていることを確認します。 - 決済（`payment`） — 注文が支払われたときに送信され、決済データとトランザクションの詳細が含まれます。 - 作成されたサブスクリプション（`create_subscription`） — 決済ウェブフックが正常に処理されたとき、またはユーザーが試用期間付きのサブスクリプ ションを購入したときに送信されます。これは購入したサブスクリプションの詳細とユーザーデータを含んでいます。ウェブフックデータを使用して、ユーザーにサブスクリプシ ョンを追加します。 - 更新されたサブスクリプション（`update_subscription`） — サブスクリプションが更新または変更されたとき、決済ウェブフックが正常に 処理されたときに送信されます。購入したサブスクリプションの詳細とユーザーデータが含まれます。ウェブフックデータを使用して、ユーザーのサブスクリプションを延長する か、サブスクリプションパラメータを変更します。 - 返金（`refund`） — 注文がキャンセルされたときに送信され、キャンセルされた決済データとトランザクションの詳細が含まれます。 - キャンセルされたサブスクリプション（`cancel_subscription`） — 返金ウェブフックが正常に処理されたとき、またはサブスクリプションが別の理由でキャンセ ルされたときに送信されます。サブスクリプションとユーザーデータに関する情報を含んでいます。ウェブフックデータを使用して、ユーザーから購入したサブスクリプションを 差し引きます。 # Set up webhooks in account {% #set-up-webhooks-in-account %} ## 一般設定 {% #general-settings %} ウェブフックの受信を有効にするには： 1. In the project in the [account](#business-accounts) go to the **Settings > Webhooks** section. 2. ウェブフックサーバーフィールドには、ウェブフックを受信したいサーバーのURLを `https://example.com` 形式で指定します。ウェブフックをテストするツールで見つけたURLを指定することもできます。

注意。

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

3. 秘密鍵を生成します：
    1. 秘密鍵セクションで、「キーを追加」クリックします。
    2. 開いたモーダルウィンドウに、一般リストからこの項目を識別するためのキー名を入力してください。。
    3. 「キーを作成」クリックします。
    4. 「シークレットをコピー」をクリックし、作成されたキーをユーザー側で保存してください。
    5. 「完了」クリックします。
    6. キーが保存されたことを確認し、「OK、閉じる」をクリックします。
![Add key](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/add-key.svg)

Notice

Key recommendations:

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

注意

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

Notice

You can’t simultaneously send webhooks to different URLs. What you can do in the account is specify a URL for testing first, and then replace it with the real one.

ウェブフックの受信を無効にするには： 1. In the project in the account, go to the **Settings > Webhooks** section. 2. 「ウェブフックを無効にする」をクリックします。 ## 秘密鍵のローテーション {% #secret-key-rotation %} 秘密鍵を定期的に更新することで、統合のセキュリティを向上させることができます。プロジェクトでは最大5つの秘密鍵を作成し、ローテーションを有効にすることができます 。これを行うには： 1. In the **Settings > Webhooks** section, click **Add key**. ![Add key](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/add-new-key.svg) 2. 開いたモーダルウィンドウに、一般リストからこの項目を識別するためのキー名を入力してください。。 3. 「**キーを作成**」をクリックします。 4. 「シークレットをコピー」をクリックし、作成されたキーをユーザー側で保存してください。 5. 「**完了**」をクリックします。 6. キーが保存されたことを確認し、「**OK、閉じる**」をクリックします。

Notice

Key recommendations:

プロジェクトごとに有効な秘密鍵は1つだけです。変更したい場合は、別のキーの行にある「**有効にする**」をクリックして操作を確定してください。新しいキーへの移行 が正常に完了した後は、無効化されたキーを削除することをお勧めします。 ![Change active key](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/activate-key.svg) ## 詳細設定 {% #advanced-settings %} For the webhooks in the Payments and Store section, advanced settings are available. They will automatically appear under the General settings block after you click the Enable webhooks button.

注意

詳細設定が表示されない場合は、一般設定でウェブフック受信が接続されていることを確認し、テスト > 決済ソリューションとストアタブにいることを確認してください。

このセクションでは、ウェブフックでの追加情報の受信を設定できます。これを行うには、対応するスイッチをアクティブポジションに設定します。各権限の行は、設定の変更に よって影響を受けるウェブフックを示します。
トグル 説明
保存された決済アカウントに関する情報を表示します（2025年1月22日以前にパブリッシャーアカウントに登録し、個別のウェブフックを受信している場合にのみ表示されます）。 保存された決済方法に関する情報は、payment_accountカスタムオブジェクト。
保存された決済方法によるトランザクションに関する情報を表示します。

情報は、ウェブフックの以下のカスタムパラメータに渡されます：

  • saved_payment_method:
    • 0 — 保存された決済方法は使用されませんでした
    • 1 — 決済方法は現在の支払い時に保存されました
    • 2 — 保存された決済方法は使用されませんでした
  • payment_type:
    • 1 — 一回払い
    • 2 — 定期支払い
ウェブフックにorderオブジェクトを追加します（2025年1月22日以前にパブリッシャーアカウントに登録し、個別のウェブフックを受信している場合にのみ表示されます）。 注文に関する情報は、決済ウェブフックのorderオブジェクトに渡されます。
機密データを含めず、必須のユーザーパラメータのみを送信します。

ウェブフックでは、ユーザーに関する次の情報のみが渡されます：

  • ID
  • 国
カスタムパラメータを送信します。 カスタムトークンパラメータに関する情報は、ウェブフックで渡されます。
カードのBINおよびサフィックスを表示します。

ウェブフックには、銀行カード番号に関する以下の情報が渡されます：

  • card_binパラメータの最初の6桁
  • card_suffixパラメータの最後の4桁
カードブランドを表示します。 決済に使用したカードのブランド。例えば、MastercardやVisaなど。
返金理由に関する情報を表示します。 返金理由に関する詳細情報。
国別の源泉徴収税および顧客獲得料を表示します。 payment_details.​country_whtとpayment_details.​user_acquisition_feeオブジェクトがウェブフックに含めて送信されます。このトグルはデフォルトでオンになっています。
3DS情報を送信します。 3-Dセキュア認証に関するデータを含むcardsオブジェクトがウェブフックで渡されます。
![Advanced settings](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/advanced-settings.png) # Test webhooks in account {% #test-webhooks-in-account %} ウェブフックをテストすると、ユーザー側とエクソーラ側の両方でプロジェクトが正しく設定されていることを確認できます。 If webhooks are set up successfully, a webhooks testing section is displayed below the webhooks setup section. ![Webhooks testing section](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-section.svg) The testing section in the account varies depending on the webhook receiving option. If you registered in the account after January 22, 2025, you receive combined webhooks:
ウェブフックテストのタブ名 ウェブフック名とタイプ
決済ソリューションとストア ユーザー検証 > ユーザー検証（user_validation）
ゲームサービス > まとめたウェブフック > 注文支払い完了（order_paid）
ゲームサービス > まとめたウェブフック > 注文キャンセル（order_canceled）
サブスクリプション ユーザー検証 > ユーザー検証（user_validation）
決済ソリューション > 支払い（payment）
2025年1月22日以前にパブリッシャーアカウントに登録した場合、個別のウェブフックが送信されます：
ウェブフックテストのタブ名 ウェブフック名とタイプ
ストア ゲームサービス> 個別のウェブフック> 注文支払い完了（order_paid）
ゲームサービス > 個別のウェブフック > 注文キャンセル（order_canceled）
決済ソリューション ユーザー検証 > ユーザー検証（user_validation）
決済ソリューション > 支払い（payment）
サブスクリプション ユーザー検証 > ユーザー検証（user_validation）
決済ソリューション > 支払い（payment）

注意

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

例：

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

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

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

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

まとめたウェブフックを使用したシナリオのテストプロセスを以下に説明します。 ## 決済ソリューションとストア {% #payments-and-store %} 「決済ソリューションとストア」タブでは、次のウェブフックをテストできます： - ユーザー検証（`user_validation`） - 注文の支払いが完了しました（`order_paid`） - 注文キャンセル（`order_canceled`） ウェブフックをテストするには： 1. ウェブフックのテストセクションで、「決済ソリューションとストア」タブに移動します。 2. In the drop-down list, select the item type. If you haven’t set up this item type in the account yet, click the button to configure it. After creating the item, return to the webhook testing section and proceed to the next step. 3. 必要なフィールドに入力します： * **ユーザーID** — テスト時には、任意の文字と数字の組み合わせを使用できます。 * 「**エクソーラ注文ID**」フィールドに任意の値を入力してください。 * **エクソーラインボイスID** — エクソーラ側のトランザクションID。テスト時には、任意の数値を使用できます。 * **インボイスID** — ゲーム側のトランザクションID。テスト時には、任意の文字と数字の組み合わせを使用できます。これは成功した支払いに必須のパラメータではありませんが、トランザクショ ンIDをエクソーラ側のトランザクションIDとリンクさせるために渡すことができます。 * **金額** — 決済金額。テスト時には、任意の数値を使用できます。 * **通貨** — ドロップダウンリストから通貨を選択します。 * ドロップダウンリストからアイテムのSKUを選択し、数量を指定します。同じタイプの複数のアイテムを選択するには、「**+**」をクリックして新しい行に追加します。 4. 「**ウェブフックをテスト**」をクリックします。 指定されたデータを含むユーザー検証、注文支払い完了および注文キャンセルウェブフックが、指定されたURLに送信されます。各ウェブフックタイプのテスト結果は、「ウェブフックをテス ト」ボタンの下に表示されます。 If the **Use public user ID** box is checked in your account in the **Settings > Integration settings** section, the User search webhook will also be sent to your webhook server URL and the testing result will be displayed. 各ウェブフックについて、成功したシナリオとエラーが発生したシナリオの両方の処理を設定する必要があります。 ![Payments testing section](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-results.svg) ## サブスクリプション {% #test-webhooks-subscriptions %}

Note

To test webhooks, you should have at least one subscription plan created in the account in the Items catalog > Subscriptions section.

「サブスクリプション」タブでは、次のウェブフックをテストできます： - ユーザー検証（`user_validation`） - 決済（`payment`）

注意

その他のサブスクリプション管理シナリオのテストに関する詳細情報については、統合ガイドを参照してください。

ウェブフックをテストするには： 1. テストセクションで、**サブスクリプション**タブに移動します。 2. 必要なフィールドに入力します： * **ユーザーID** — テスト時には、任意の文字と数字の組み合わせを使用できます。 * **エクソーラインボイスID** — エクソーラ側のトランザクションID。テスト時には、任意の数値を使用できます。 * **Public user ID** — ID known to a user, e.g., an email or nickname. This field is displayed if you checked the **Use public user ID** box in your account in the **Settings > Integration settings** section. * **金額** — 決済金額。テスト時には、任意の数値を使用できます。 * **通貨** — ドロップダウンリストから通貨を選択します。 * **プランID** — サブスクリプションプラン。ドロップダウンリストからプランを選択します。 * **サブスクリプション製品** — ドロップダウンリストから製品を選択します（オプション）。このリストは、プロジェクトで[製品](/ja/sell-subscriptions/integration-guide/get-started/#guides_subscriptions_glossary_product)が設定されている場合に表示されます。 * **インボイスID** — ゲーム側のトランザクションID。テスト時には、任意の文字と数字の組み合わせを使用できます。これは成功した支払いに必須のパラメータではありませんが、トランザクショ ンIDをエクソーラ側のトランザクションIDとリンクさせるために渡すことができます。 * **試行期間**。[お試し期間なしでのサブスクリプションの購入](/ja/sell-subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_sandbox)をテストす るか、または[サブスクリプションの更新](/ja/sell-subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_renewal) をテストするには、値を`0`に指定します。 3. 3. 「**テスト**」をクリックします。 指定したURLに、データが入力されたウェブフックを受け取ります。各ウェブフックのテスト結果は、成功したシナリオとエラーが発生したシナリオの両方で、「テスト 」ボタンの下に表示されます。 # ウェブフックリスナー {% #webhook-listener %} ウェブフックリスナーは、指定されたURLアドレスでウェブフックを受信し、署名を生成し、エクソーラウェブフックサーバーに応答を送信することができるプログラムコードです。

注意

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

アプリケーション側で、以下のIPアドレスからのウェブフックの受信を実装してください： - `185.30.20.0/24` - `185.30.21.0/24` - `185.30.22.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` もし「ログイン」製品を統合している場合、以下のIPアドレスからのウェブフックの処理も追加してください： - `34.94.0.85` - `34.94.14.95` - `34.94.25.33` - `34.94.115.185` - `34.94.154.26` - `34.94.173.132` - `34.102.48.30` - `35.235.99.248` - `35.236.32.131` - `35.236.35.100` - `35.236.117.164` 制限： - アプリケーションのデータベースに同じIDで成功したトランザクションが複数存在することは許可されていません。 - ウェブフックリスナーがデータベースにすでに存在するIDを持つウェブフックを受信した場合、このトランザクションの以前の処理結果を返す必要があります。ユーザーに重複 した購入をクレジットし、データベースに重複したレコードを作成することは推奨されません。 ## 署名の生成 {% #generation-of-signature %} 安全なデータ転送を確保するには、ウェブフックが実際にエクソーラサーバーから送信され、転送中に改ざんされていないことを確認する必要があります。これを行うには、受信 したリクエスト本文のペイロードに基づいて独自の署名を生成し、それを着信リクエストの`authorization`ヘッダーで提供される署名と比較してください。両方 の署名が一致する場合、そのウェブフックは正規のものであり、安全に処理できます。 検証ステップ： 1. 着信ウェブフックリクエストの`authorization`ヘッダーから署名を取得します。ヘッダーの形式は`Signature `です。 2. ウェブフックのリクエスト本文をJSON形式で取得してください。

注意

JSONペイロードは、受信したものをそのまま使用してください。ペイロード をパースしたり再エンコードしたりしないでください。フォーマットが変更され、署名検証が失敗する原因となります。

3. 比較用に独自の署名を生成します：
  1. JSONペイロードとプロジェクトの秘密鍵を連結します。秘密鍵は文字列の末尾に追加してください。
  2. 結果の文字列にSHA-1暗号ハッシュ関数を適用します。結果は小文字の16進数文字列になります。
4. 生成した署名を`authorization`ヘッダーからの署名と比較してください。両者が一致すれば、ウェブフックは信頼できるものです。 以下に、署名生成の実装例を各種プログラミング言語で示します： C#、C++、Go、PHP、Node.js。 ### ウェブフック（HTTP）の例： {% #example-of-a-webhook-http %} ```http 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）の例： {% #example-of-a-webhook-curl %} ```bash 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" } }' ``` ### C#で署名生成の実装例（一般サンプル）： {% #csharp-signature-generation-general-sample %}

注

このコードサンプルは、.NET Framework 4.0以降、および.NET Coreやその他の最新の.NETバージョンと互換性があります。署名検証には、タイミング攻撃を防ぐために、ConstantTimeEqualsメソッドによる定数時間比較が使用されています。

```csharp using System; using System.Security.Cryptography; using System.Text; public static class XsollaWebhookSignature { public static string ComputeSha1(string jsonBody, string secretKey) { // Concatenation of the JSON from the request body and the project's secret key string dataToSign = jsonBody + secretKey; using (SHA1 sha1 = SHA1.Create()) { byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign)); // Convert hash bytes to lowercase hexadecimal string var hexString = new StringBuilder(hashBytes.Length * 2); foreach (byte b in hashBytes) { hexString.Append(b.ToString("x2")); } return hexString.ToString(); } } public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature) { string computedSignature = ComputeSha1(jsonBody, secretKey); string receivedSignatureLower = receivedSignature.ToLower(); // Use constant-time comparison to prevent timing attacks return ConstantTimeEquals(computedSignature, receivedSignatureLower); } private static bool ConstantTimeEquals(string a, string b) { if (a.Length != b.Length) { return false; } int result = 0; for (int i = 0; i < a.Length; i++) { result |= a[i] ^ b[i]; } return result == 0; } } ``` ### C#による署名生成の実装例（.NET 5.0以降）： {% #csharp-signature-generation-net-5-0-and-later %}

注

Convert.ToHexStringメソッドを使用するには、.NET 5.0 以降が必要です。

.NET 7.0以降をお持ちの場合は、 CryptographicOperations.FixedTimeEqualsメソッドの代わりにConstantTimeEqualsを使用することもできます。

```csharp // For .NET 5.0 and later, you can use the more concise Convert.ToHexString method: using System; using System.Security.Cryptography; using System.Text; public static class XsollaWebhookSignature { public static string ComputeSha1(string jsonBody, string secretKey) { string dataToSign = jsonBody + secretKey; using var sha1 = SHA1.Create(); byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign)); return Convert.ToHexString(hashBytes).ToLower(); } public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature) { string computedSignature = ComputeSha1(jsonBody, secretKey); string receivedSignatureLower = receivedSignature.ToLower(); // Use constant-time comparison to prevent timing attacks return ConstantTimeEquals(computedSignature, receivedSignatureLower); } private static bool ConstantTimeEquals(string a, string b) { if (a.Length != b.Length) { return false; } int result = 0; for (int i = 0; i < a.Length; i++) { result |= a[i] ^ b[i]; } return result == 0; } } ``` ### C#による署名生成の実装例（.NET 7.0以降）： {% #csharp-signature-generation-net-7-0-and-later %}

注

.NET 7.0以降をお持ちの場合は、CryptographicOperations.FixedTimeEqualsメソッドを使用できます。

```csharp // For .NET 7.0+, you can use the built-in CryptographicOperations.FixedTimeEquals: using System.Security.Cryptography; public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature) { string computedSignature = ComputeSha1(jsonBody, secretKey); byte[] computedBytes = Encoding.UTF8.GetBytes(computedSignature); byte[] receivedBytes = Encoding.UTF8.GetBytes(receivedSignature.ToLower()); return CryptographicOperations.FixedTimeEquals(computedBytes, receivedBytes); } ``` ### C++での署名生成の実装例： {% #cpp-signature-generation %} ```c++ #include #include #include #include class XsollaWebhookSignature { public: static std::string computeSha1(const std::string& jsonBody, const std::string& secretKey) { // Concatenation of the JSON from the request body and the project's secret key std::string dataToSign = jsonBody + secretKey; unsigned char digest[SHA_DIGEST_LENGTH]; // Create SHA1 hash SHA1(reinterpret_cast(dataToSign.c_str()), dataToSign.length(), digest); // Convert to lowercase hexadecimal string std::ostringstream hexStream; hexStream << std::hex << std::setfill('0'); for (int i = 0; i < SHA_DIGEST_LENGTH; ++i) { hexStream << std::setw(2) << static_cast(digest[i]); } return hexStream.str(); } static bool verifySignature(const std::string& jsonBody, const std::string& secretKey, const std::string& receivedSignature) { std::string computedSignature = computeSha1(jsonBody, secretKey); // Timing-safe comparison if (computedSignature.length() != receivedSignature.length()) { return false; } volatile unsigned char result = 0; for (size_t i = 0; i < computedSignature.length(); ++i) { result |= (computedSignature[i] ^ receivedSignature[i]); } return result == 0; } }; ``` ### Goでの署名生成の実装例： {% #go-signature-generation %} ```go package main import ( "crypto/sha1" "crypto/subtle" "encoding/hex" "strings" ) type XsollaWebhookSignature struct{} func (x *XsollaWebhookSignature) ComputeSha1(jsonBody, secretKey string) string { // Concatenation of the JSON from the request body and the project's secret key dataToSign := jsonBody + secretKey // Create SHA1 hash h := sha1.New() h.Write([]byte(dataToSign)) signature := h.Sum(nil) // Convert to lowercase hexadecimal string return strings.ToLower(hex.EncodeToString(signature)) } func (x *XsollaWebhookSignature) VerifySignature(jsonBody, secretKey, receivedSignature string) bool { computedSignature := x.ComputeSha1(jsonBody, secretKey) receivedSignatureLower := strings.ToLower(receivedSignature) // Use constant time comparison to prevent timing attacks return subtle.ConstantTimeCompare([]byte(computedSignature), []byte(receivedSignatureLower)) == 1 } ``` ### PHPでの署名生成の実装例： {% #php-signature-generation %} ```php ``` ### Node.jsでの署名生成の実装例： {% #nodejs-signature-generation %} ```js const crypto = require('crypto'); class XsollaWebhookSignature { // IMPORTANT: jsonBody must be the raw JSON string exactly as received from Xsolla static computeSha1(jsonBody, secretKey) { // Concatenation of the JSON from the request body and the project's secret key const dataToSign = jsonBody + secretKey; // Create SHA1 hash const hash = crypto.createHash('sha1'); hash.update(dataToSign, 'utf8'); // Convert to lowercase hexadecimal string return hash.digest('hex').toLowerCase(); } static verifySignature(jsonBody, secretKey, receivedSignature) { const computedSignature = this.computeSha1(jsonBody, secretKey); const cleanReceivedSignature = receivedSignature.toLowerCase(); // Check if signatures have the same length before using timingSafeEqual if (computedSignature.length !== cleanReceivedSignature.length) { return false; } try { return crypto.timingSafeEqual( Buffer.from(computedSignature, 'hex'), Buffer.from(cleanReceivedSignature, 'hex') ); } catch (error) { // Return false if there's any error (e.g., invalid hex characters) return false; } } } ``` ## ウェブフックへの応答の送信 {% #sending-responses-to-webhook %} ウェブフックの受信を確認するには、サーバーは以下を返す必要があります： * 成功した応答の場合は、`200`、`201`、または`204`HTTPコード。 * `400`HTTPコードは問題の説明を含む、指定されたユーザーが見つからないか、無効な署名が渡 された場合に送信されます。ウェブフックハンドラーは、サーバーで一時的な問題が発生した場合に`5xx`HTTPコードを返すこともあります。 エクソーラサーバーが 注文支払い完了と注文キャンセルへのレスポンスを受け取らなかった場合、または`5xx`コードのレスポンスを受け取った場合、ウェブフックは以下の スケジュールに従って再送されます： * 5分間隔で2回の試行 * 15分間隔で7回の試行 * 60分間隔で10回の試行 ウェブフックの送信は、最初の送信から12時間以内に最大20回まで試行されます。 決済と返金ウェブフックの再試行ロジックは、対応するウェーブフックページに記載されています。

注意

以下の条件がすべて満たされている場合でも、支払いはユーザーに返金されます：

  • 返金はエクソーラによって開始されました。
  • ウェーブフックに対する応答として、4xxステータスコードが返された、またはすべての再試行後に応答がなかった、あるいは5xxステータスコードが返された場合。

エクソーラサーバーがユーザー認証ウェブフックへの応答を受信しなかった場合、または`400`または`5xx`のコードで応答を受信した場合、ユーザー認証ウェブフックは再送信されません。この場合、ユーザーにはエラーが表示され、支払いと注文支払い完了ウェブフックは送信されません。 # エラー {% #errors %} 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" } } ``` # 適用事例 {% #best-practices %} ## セキュリティ {% #security %} 以下のガイドラインに従ってください： * 有効な証明書を備えたHTTPSのみを使用してください。 * 署名の検証は必ずリクエスト本文の生データに対して行ってください。データの解析や再エンコードは行わないでください * 機密データをURLに含めたり、エラーメッセージに技術的な詳細情報を記載したりしないでください。 * ウェーブフックのエンドポイントを[CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery)ミドルウェアの対象から除外してください — エクソーラからの受信リクエストにはCSRFトークンが含まれていないため、この設定がないと拒否されます。 * [エクソーラIPアドレス](/ja/webhooks/section/webhook-listener)を許可リストに追加してください。 ## ウェブフックハンドラのアーキテクチャ {% #webhook-handler-architecture %} 以下のガイドラインに従ってください： 1. 本文とヘッダーを**変更することなく**、そのままの状態で`POST`リクエストを受け取ります。 2. [ウェブフックの署名を検証し](/ja/webhooks/section/webhook-listener/generation-of-signature) 、適切なステータスコードを返してください。 * `4xx` — 署名が一致しない場合。 * `2xx` —成功した場合。メインのビジネスロジックを実行する**前**に、「204 No Content」を返すことを推奨します。「200 OK」も受け入れ可能です。 3. ペイロードを非同期ジョブまたはキューに渡し、さらなる処理を行います。 4. [冪等性](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning)を実装してくだ さい。[同じウェーブフックを複数回受信した場合](/ja/webhooks/section/webhook-listener/sending-responses-to-webhook)でも、システムが適切に処理できるようにする必要があります。 **フローの例：** ```http HTTP POST /webhooks/xsolla read raw_body, headers if !verify_signature(raw_body, headers['authorization']): return 400 {"error":{"code":"INVALID_SIGNATURE","message":"Invalid signature"}} enqueue(raw_body) return 204 # or 200 ``` ## 冪等性と重複 {% #idempotency-and-duplicates %} 以下のガイドラインに従ってください： * トランザクションIDおよび/または [external ID](/ja/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id)、注文IDを冪等性キーとし て使用してください。 * 処理済みのIDを保存し、重複するリクエストを受信した場合は前回の結果を返却します。 * アイテムの重複付与、データベースへの二重登録、および二重課金を回避してください。 * 逐次配信においては、前のイベントでエラーが発生すると、それ以降のすべてのイベントの処理がブロックされる点に注意してください。 ## システムの回復性 {% #system-resilience %} 以下のガイドラインに従ってください： * サードパーティへのAPIコール、請求処理、アイテム付与などのリソース消費の激しい操作には、キューと非同期処理を使用してください。 * ウェブフックハンドラにタイムアウト（1〜3秒）を設定してください。一時的な障害の場合は、[エクソーラのの再試行メカニズム](/ja/webhooks/section/webhook-listener/sending-responses-to-webhook)を活用してください。 * フックハンドラ内で再試行を実装しないでください。再配信はエクソーラによって処理されます。 * ウェブフックの配信日時と処理ステータスをログに記録してください。また、5xx エラーの急増や再配信の発生に対するアラートを設定してください。 * ウェブフックに含まれる相関IDを、自システムのログやモニタリングシステム（APM）に伝播させてください。 * エラーログの記録とモニタリングをセットアップしてください。修復不可能な障害については、ジョブをデッドレターキュー（DLQ）に移動させてください。また、冪等性メカ ニズムによって保護された、イベントを再実行するための安全なツールを開発してください。 ## 実装例 {% #implementation-examples %} **購入成功 - 初回試行でアイテムが付与されました：** ![購入](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/purchase-v2.svg) **重複配信（初回試行時にパートナーのタイムアウトが発生しました）** ![タイムアウト](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/timeout-v2.svg) **返金：** ![返金](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/refund-v2.svg) **パートナー側の機能障害**： ![パートナー側の機能障害](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/server-error.svg) # よくある質問 {% #faqs %} ## ウェブフックプロトコルにはHTTPSを使用する必要がありますか？ {% #do-i-need-to-use-https-for-a-webhook-protocol %} はい。 ## 複数のURLで支払いに関するウェブフックを受信することはできますか？ {% #can-i-receive-payment-webhooks-at-several-urls %} いいえ。支払いウェブフックはサーバー間プロトコルを使用しており、[プロジェクト設定](/ja/webhooks/section/set-up-webhooks-in-publisher-account)で指定された単一のURLに送信されます。ゲーム、ウェブサイト、またはモバイルアプリケーションで通知を受け取りたい場合は、お客様のサーバー側でウェ ブフックの送信設定を行い、エクソーラとお使いのゲーム間でデータを渡すようにしてください。また、開発者コンソールからウェブフックのテストを行うことも可能です。

Note

If you are testing the integration locally, POST requests from Xsolla don’t reach URLs like http://localhost:3000/my-webhook-endpoint. Use services such as Ngrok that allow you to create a tunnel for external access, enabling you to receive requests from Xsolla locally. E.g., you can read more about this in the ngrok documentation.

## エクソーラからの通知がウェブフックURLに送信されなかったのはなぜですか？ {% #why-was-xsolla-notification-not-sent-to-the-webhook-url %} ウェブフックサーバーが、HTTPリクエストの`POST`および`GET`メソッドをサポートしていることを確認してください。 ## 処理中のトランザクションIDの重複を防ぐにはどうすればよいですか？ {% #how-do-i-prevent-duplicate-transaction-ids-during-processing %} external IDを使用してください。これはお客様のシステム内の注文に割り当てられた、ゲーム内でのトランザクションIDを指します。エクソーラ側では、external IDはトランザクションIDにリンクされており、これによりエクソーラは同じトランザクションに対する重複支払いを防止できます。設定の詳細については、こちらの[ドキュ メント](/ja/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id)を参照してください。 ## ウェブフックを利用する際の適用事例はありますか？ {% #are-there-any-best-practices-for-working-with-webhooks %} 以下の対応を推奨します： * 署名検証後、直ちに「204」または「200」を返します。 * 変更を加えず、生のリクエスト本文に対してウェブフックの署名を検証します。 * すべての演算に対して冪等性を実装します。 * すべてのイベントをログに記録し、エラーモニタリングをセットアップします。 * URLに機密データを含めることを避け、エラーメッセージに技術的な詳細情報を記載したりしないでください。 詳細については、[適用事例](/ja/webhooks/section/best-practices)セクションを参照してください。 # ウェブフック統合のチェックリスト {% #webhook-integration-checklist %} ウェブフックを正しく機能させるために、本番環境へのリリース前に以下のことが整っていることを確認してください： * HTTPSが使用されています。 * ウェブフックの[署名検証](/ja/webhooks/section/webhook-listener/generation-of-signature)が、リクエスト本文を変更することなく、生データに対して実装されています。 * 署名が確認されるとすぐに「204/200」という応答が返されます。 * すべての操作に対して、冪等性が実装されています。 * エラーログの記録とモニタリングが設定されています。 * 機密データはURLには含まれず、技術的な詳細はエラーメッセージにも表示されません。 * [エクソーラの再試行ロジック](/ja/webhooks/section/webhook-listener/sending-responses-to-webhook)に基づき、ウェブフックの再試行がサポートされています。 * 統合プロセス全体がドキュメント化されています。 # ウェブフックリスト {% #webhooks-list %}

注意

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

ウェブフック 通知タイプ 説明
ユーザー検証 user_validation ユーザーがゲーム内に存在するかどうかを確認するために送信されます。
ユーザー検索 user_search パブリックユーザーIDに基づいてユーザー情報を取得するために送信されます。
決済 payment ユーザーが決済を完了した場合に送信されます。
返金 refund 何らかの理由で決済をキャンセルする必要がある場合に送信されます。
一部返金 partial_refund 何らかの理由で決済を一部キャンセルする必要がある場合に送信されます。
支払いが拒否されました ps_declined 支払いが決済システムによって拒否されたときに送信されます。
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 新しい紛争手続きが開かれたときに送信されます。
Version: 1.0 ## Servers ``` https://api.xsolla.com/merchant/v2 ``` ## Download OpenAPI description [ウェブフック](https://xsolla.redocly.app/_bundle/@l10n/ja/webhooks/index.yaml) ## ユーザー検証 ### ユーザーの検索 - [POST user-search](https://xsolla.redocly.app/ja/webhooks/user-validation/user-search.md): Public User IDは、User ID（Public User IDはメールアドレス、画面名など）とは異なり、ユーザを一意に識別し、ユーザーに知られているパラメータです。エクソーラは、ゲームストアの外（例えば現金キオスクなど）で購入する場合、user_searchタイプのウェブフックを送信します。 ### ユーザー検証 - [POST user-validation](https://xsolla.redocly.app/ja/webhooks/user-validation/user-validation.md): エクソーラはユーザーがゲームに登録されていることを確認するために、user_validationタイプのウェブフックをウェブフックURLに送信します。このリ クエストは支払いプロセスの一部として複数回送信されます： * ユーザーが決済UIで決済方法を選択する場合 * ユーザーが決済フォームにデータを入力する場合（例: 銀行カードのデータやPayPal経由で支払う場合の郵便番号） * ユーザーが今すぐ支払うをクリックして決済を続行する場合 * 支払処理が完了し、取引状況がdoneに変更された場合 このリクエストは、任意の決済方法で支払いを行う際に送信されます。 When you save the webhook URL in the account, you can give permissions to receive detailed information in webhooks. To do that, activate the necessary toggles in the Settings > Webhooks > Advanced settings section. Note If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Settings > Webhooks > Testing > Payments > Advanced settings section. トグル 説明 機密データは含まず、必要なユーザーパラメータのみを送信する ウェブフックでは、ユーザーに関する次の情報のみが渡されます：ID国 カスタムパラメータを送信する カスタムトークンパラメータに関する情報は、ウェブフックで渡されます。 ### ウェブショップでのユーザー検証 - [POST user-validation-in-webshop](https://xsolla.redocly.app/ja/webhooks/user-validation/user-validation-in-webshop.md): ユーザーがゲームに存在するかどうかを確認するために、エクソーラはウェブショップサイトからウェブフックを送信します。ウェブフックは以下のIPアドレスからに送信されます： 34.102.38.178。 注意 ウェブフックはウェブショップ内でユーザーの検証にのみ使用されます。サイトビルダーでウェブフックを構成する詳細については、こちらの説明を参照してください。 ## 決済ソリューション ### 決済アカウントを追加する - [POST add-payment-account](https://xsolla.redocly.app/ja/webhooks/payments/add-payment-account.md): ユーザーがゲーム内で何かを購入するときに決済アカウントを追加したり、決済アカウントを保存したりするたびに、エクソーラは「payment_account_add」タイプのウェブフックをウェブフックURLに送信します。このウェブフックを受信するには、カスタマーサクセスマネージャーにご連絡いただくか、csm@xsolla.comまで電子メールでお問い合わせください。 ### 一部返金 - [POST partial-refund](https://xsolla.redocly.app/ja/webhooks/payments/partial-refund.md): 一部返金が行われた場合、エクソーラはpartial_refundタイプのウェブフックのウェブフックURLにキャンセルされたトランザクションの詳細を送信します 。返金プロセスの一部の詳細は、これらの説明を参照してください。 When you save the webhook URL in the account, you can give permissions to receive detailed information in webhooks. To do that, activate the following toggle in your account in the Settings > Webhooks > Advanced settings section. Note If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Project settings > Webhooks > Testing > Payments > Advanced settings section. トグル 説明 保存された決済方法による取引に関する情報を表示する 情報は、パラメータの以下のカスタムパラメータに渡されます：saved_payment_method:0 — 保存された決済方法は使用されませんでした1 — 決済方法は現在の支払い時に保存されました2 — 保存された決済方法は使用されませんでしたpayment_type:1 — 一回払い2 — 定期支払い 返金コード： コード 理由 説明 1 Cancellation by the user request / the game request Cancellation initiated from the account. 3 Integration error エクソラとゲームの統合に関する問題推奨事項：ブロックリストにユーザーを追加しません。 5 Test payment テストトランザクション後にキャンセル処理が実行されます。推奨事項：ブロックリストにユーザーを追加しません。 7 Fraud notification from PS 決済システムが不正の可能性を検知したため、決済が拒否されました。推奨事項：ユーザーをブロックリストに追加してください。 9 Cancellation by the user request ユーザは何らかの理由でゲームや購入に満足していませんでした。推奨事項：ブロックリストにユーザーを追加しません。 10 Cancellation by the game request ゲームによってキャンセルが要求されました。推奨事項：ブロックリストにユーザーを追加しません。 ### 支払い - [POST payment](https://xsolla.redocly.app/ja/webhooks/payments/payment.md): ユーザーが支払いを完了すると、エクソーラはpaymentタイプのウェブフックで決済詳細をウェブフックURLに送信します。 予想される応答コードについては、Responsesセクションでは、他の応答コードも使用できます： 応答コード 説明 200、201、204 成功応答。 4xx エラーが発生しました。たとえば、指定されたユーザーが見つからない場合や、無効な署名が渡された場合などです。 5xx 一時的なサーバーエラーです。この応答を受信すると、エクソーラはウェブフックの送信を自動的に再試行し、リスナーが受信を確認するまで試行間隔を徐々に長くします。最大再試行回数は48時間で12回です。 When you save the webhook URL in the account, you can also set up receiving additional information in webhooks. Note If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the Settings > Webhooks > Testing > Payments > Advanced settings section. トグル 説明 保存された決済アカウントに関する情報を表示する 保存された決済方法に関する情報は、payment_accountカスタムオブジェクト。 保存された決済方法による取引に関する情報を表示する 情報は、ウェブフックの以下のカスタムパラメータに渡されます：saved_payment_method:0 — 保存された決済方法は使用されませんでした1 — 決済方法は現在の支払い時に保存されました2 — 保存された決済方法は使用されませんでしたpayment_type:1 — 一回払い2 — 定期支払い 注文オブジェクトをウェブフックに追加する 注文に関する情報は、決済ウェブフックのorderオブジェクトに渡されます。 機密データは含まず、必要なユーザーパラメータのみを送信する ウェブフックでは、ユーザーに関する次の情報のみが渡されます：ID国 カードのBINとサフィックスを表示する ウェブフックには、銀行カード番号に関する以下の情報が渡されます：card_binパラメータの最初の6桁card_suffixパラメータの最後の4桁 カードブランドを表示する 決済に使用したカードのブランド。例えば、MastercardやVisaなど。 国別の源泉徴収税および顧客獲得料を表示します。 payment_details.​country_whtとpayment_details.​user_acquisition_feeオブジェクトがウェブフックに含めて送信されます。このトグルはデフォルトでオンになっています。 3DS情報を送信します。 3-Dセキュア認証に関するデータを含むcardsオブジェクトがウェブフックで渡されます。 Notice The set of fields sent in a webhook depends on:the advanced settings configured in the accountthe custom settings configured on the Xsolla sideIf you have any questions, contact your Customer Success Manager or email to csm@xsolla.com. ### 支払いが拒否されました - [POST payment-declined](https://xsolla.redocly.app/ja/webhooks/payments/payment-declined.md): 決済システムによってトランザクションが拒否された場合、エクソーラは設定されたウェブフックURLに、ps_declinedタイプのウェブフックでトランザクショ ンの詳細を送信します。このウェブフックは認証または支払い処理の段階で送信されます。この場合、payment\ order_paidウェブフックは送信されません。 決済システムで支払いが拒否される一般的な理由： * カードの認証が失敗した（例：技術的なエラーや銀行からの応答がないため、決済システムが認証プロセスを完了できなかった場合）または認証が拒否された（例：銀行からの応 答があったものの、残高不足やカード情報の誤りなどにより取引を拒否した場合）。 * 3-Dセキュア認証が失敗した、完了しなかった、またはユーザーの確認がタイムアウトした場合。 * 決済処理業者または加盟店契約銀行が一時的に利用不能である、あるいは口座閉鎖や無効なカード番号といった不可逆的なエラーによる確定的な拒否（ハードディクライン）が返 された場合。根本的な問題に対処せずに再試行しても、取引の成功にはつながりません。 以下と混同しないでください： * 不正決済防止による拒否は、afs_rejectウェブフックで報告されます。 * 成功した支払い後の全額返金および一部返金（refundおよびpartial_refundウェブフックで報告されます）。 注意 ps_declinedウェブフックを受け取るには、担当のカスタマーサクセスマネージャーにご連絡いただくか、csm@xsolla.comまでメールでお問い合わせください。 ### 払い戻し - [POST refund](https://xsolla.redocly.app/ja/webhooks/payments/refund.md): 支払いがキャンセルされると、エクソーラはキャンセルされた取引の詳細を、refundタイプのウェブフックとしてウェブフックURLに送信します。 ウェブフックの再試行メカニズムは、誰が返金を開始したかによって異なります： * 返金がお客様側で開始された場合、ウェブフックは再送されません。ウェブフックへの応答に関係なく、支払いはユーザーに返金されます。 * 返金がサードパーティ（例：決済システム、またはエクソーラカスタマーサポートチームなど）によって開始され、かつウェブフックへの応答として5xxステータスコード が返された場合、ウェブフックは間隔を空けながら再送されます。最大再試行回数は、最初の試行から48時間以内に12回です。 返金プロセスに関する詳細な情報は、こちらの説明.をご参照ください。 注意 以下の条件がすべて満たされている場合でも、支払いはユーザーに返金されます：返金はエクソーラによって開始されました。ウェーブフックに対する応答として、4xxステータスコードが返された、またはすべての再試行後に応答がなかった、あるいは5xxステータスコードが返された場合。 When you save the webhook URL in the account, you can also set up receiving additional information in webhooks. Note If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the Settings > Webhooks > Testing > Payments > Advanced settings section. トグル 説明 保存された決済方法による取引に関する情報を表示する 情報は、ウェブフックの以下のカスタムパラメータに渡されます：saved_payment_method:0 — 保存された決済方法は使用されませんでした1 — 決済方法は現在の支払い時に保存されました2 — 保存された決済方法は使用されませんでしたpayment_type:1 — 一回払い2 — 定期支払い 返金理由に関する情報を表示します。 返金理由に関する詳細情報。 返金コード： コード 理由 説明 1 Cancellation by the user request / the game request Cancellation initiated from the account. 2 Chargeback トランザクションのチャージバックが要求されました。 3 Integration error エクソラとゲームの統合に関する問題推奨事項：ブロックリストにユーザーを追加しません。 4 Potential fraud – AFS reject エクソーラの不正決済防止システムが不正の可能性を検知したため、トランザクションが拒否されました。 5 Test payment テストトランザクション後にキャンセル処理が実行されます。推奨事項：ブロックリストにユーザーを追加しません。 6 User invoice expired 請求書の期限が切れました（後払いモデルで使用）。 7 Fraud notification from PS 決済システムが不正の可能性を検知したため、決済が拒否されました。推奨事項：ユーザーをブロックリストに追加してください。 8 Cancellation by the PS request 決済システムによってキャンセルが要求されました。推奨事項：ブロックリストにユーザーを追加しません。 9 Cancellation by the user request ユーザは何らかの理由でゲームや購入に満足していませんでした。推奨事項：ブロックリストにユーザーを追加しません。 10 Cancellation by the game request ゲームによってキャンセルが要求されました。推奨事項：ブロックリストにユーザーを追加しません。 11 Account holder called to report fraud アカウント所有者は、このトランザクションを行っていないと主張しています。推奨事項：ユーザーをブロックリストに追加してください。 12 Potential fraud – friendly fraud 正当なカード所有者が、自身のトランザクションに対して異議申し立てを行いました。 13 Duplicate 同じインボイスのトランザクションが重複しています。 21 Potential fraud – BIN attack 1つまたは複数のBINから盗まれたカードのバッチ。主な指標は、短期間のうちに特定のBIN範囲を共有する試行が急増することであり、多くの場合、列挙されたカード番号が含まれます。 22 Potential fraud – monetization fraud 盗まれたカードを使用して、転売を目的とした取引可能アイテムを購入しました。 23 Potential fraud – low-scale card fraud 1つまたは複数のBINから盗まれたカード。BIN攻撃ほど広範囲かつ組織的なものではありません（返金コード21）。 24 Potential fraud – regional price abuse 地域別価格の悪用、またはキーの転売の不正行為。ユーザーが場所や決済方法を偽装して地域別価格を悪用し、安価にアイテムを入手して、より高価な市場で転売する行為。 25 Potential fraud – partner or PS exploit 認証情報の窃取およびアカウントの乗っ取り。カードの直接的な不正利用ではなく、パートナー側または決済システムの合意アカウントや統合設定を悪用した行為。 26 Potential fraud – not definable 不正行為が確認されたが、正確な攻撃タイプを特定するための証拠が不十分なもの。 27 Fraud notification from PS – linked transactions 決済システムの不正報告において、当該トランザクション自体は指定されていなかったが、共有のカードやデバイスを介して、不正行為に関連する理由で返金されたトランザクションと関連があるもの。 ### 決済アカウントを削除する - [POST remove-payment-account](https://xsolla.redocly.app/ja/webhooks/payments/remove-payment-account.md): ユーザーが保存アカウントから決済アカウントを削除すると、エクソーラは payment_account_removeタイプのウェブフックをウェブフックURLに送信します。このウェブフックを受信するには、カスタマーサクセスマネージャーにご連絡いただくか、csm@xsolla.comまで電子メールでお問い合わせください。 ## まとめたウェブフック ### 注文キャンセル（支払いと取引の詳細を含む） - [POST order-cancellation](https://xsolla.redocly.app/ja/webhooks/combined-webhooks/order-cancellation.md): ユーザー、パートナー、またはシステムによって支払いがキャンセルされた場合、エクソーラは指定されたURLにorder_canceledウ ェーブフックを送信します。このウェーブフックには、キャンセルされたアイテムと決済データに関する情報と、キャンセルされた注文の詳細が含まれています。 支払いが成功しなかった場合、ウェブフックは送信されません。例： * 決済UIは開かれましたが、ユーザーが注文の支払いを行われません * 決済UIが開かれましたが、支払いの実行中にエラーが発生しました 推奨されるウェーブフックの処理時間は3秒以内です。 ### 注文支払い完了（支払いおよび取引の詳細を含む） - [POST successful-order-payment](https://xsolla.redocly.app/ja/webhooks/combined-webhooks/successful-order-payment.md): エクソーラはユーザーが注文の支払いに成功すると、指定したURLにorder_paidウェブフックを送信します。 order_paidウェブフックには、購入したアイテム、支払いデータ、取引の詳細に関する情報が含まれています。 支払いが成功しなかった場合、order_paidウェブフックは送信されません： * 決済フォームは開かれましたが、ユーザーは注文の支払いをしていません * 決済フォームが開かれましたが、支払い中にエラーが発生しました order_paidウェブフックの処理時間は3秒未満にすることをお勧めします。 Notice The set of fields sent in a webhook depends on the following settings:the ones you configured in the account in the Settings > Webhooks > Advanced settings sectionthe ones configured on the Xsolla sideIf you have any questions, contact your Customer Success Manager or email to csm@xsolla.com. 予想される回答は、「応答」セクションに記載されています。他の応答コードを使用できます。応答コードと自動返金機能の接続に応じて、エクソーラ側のウェブ フック処理ロジックは以下のようになります： 応答コード 自動返金は無効になっています（デフォルト） 自動返金が有効になっています 400、401、402、403、404、409、422、415 操作なし ユーザーへの自動返金 200、201、204 操作なし 操作なし 別のコードまたはウェブフックへの応答なし 指定された時間間隔内に複数のウェブフックが送信されます。5分間隔で2回、15分間隔で7回、60分間隔で10回試行されます。 指定された時間間隔内に複数のウェブフックが送信されます。5分間隔で2回、15分間隔で7回、60分間隔で10回試行されます。すべてのウェブフックが送信されても正常な応答が受信されない場合、ユーザーに自動返金が発行されます。 自動返金機能を接続するには、カスタマーサクセスマネージャーにお問い合わせいただくか、csm@xsolla.comまで電子メールをお送りください。 ## 個別のウェブフック ### 注文キャンセル（支払いおよび取引の詳細なし） - [POST order-cancellation-separate](https://xsolla.redocly.app/ja/webhooks/separate-webhooks/order-cancellation-separate.md): ユーザー、パートナー、またはシステムによって支払いがキャンセルされた場合、エクソーラは指定されたURLにorder_canceledウ ェーブフックを送信します。このウェーブフックには、キャンセルされたアイテムに関する情報と、キャンセルされた注文の詳細が含まれています。 支払いが成功しなかった場合、ウェブフックは送信されません。例： * 決済UIは開かれましたが、ユーザーが注文の支払いを行われません * 決済UIが開かれましたが、支払いの実行中にエラーが発生しました 推奨されるウェーブフックの処理時間は3秒以内です。 ### 注文支払い完了（支払いおよび取引の詳細なし） - [POST successful-order-payment-separate](https://xsolla.redocly.app/ja/webhooks/separate-webhooks/successful-order-payment-separate.md): エクソーラは、次の条件が満たされると、指定されたURLにorder_paidウェブフックを送信します： 1. ユーザーは注文の支払いに成功しました。 2. エクソーラは、決済ウェブフックの正常な処理に関する応答を受け取りました。 order_paidウェブフックには、購入したアイテムとトランザクションの詳細に関する情報が含まれています。 次の場合、order_paidウェブフックは送信されません： * 決済が失敗しました。例： * 決済フォームは開かれましたが、ユーザーは注文の支払いをしていません * 決済フォームが開かれましたが、支払い中にエラーが発生しました * 決済ウェブフックの正常な処理に関する応答が受信されていません。 order_paidウェブフックの処理時間は3秒未満にすることをお勧めします。 予想される回答は、「応答」セクションに記載されています。他の応答コードを使用できます。応答コードと自動返金機能の接続に応じて、エクソーラ側のウェブ フック処理ロジックは以下のようになります： 応答コード 自動返金は無効になっています（デフォルト） 自動返金が有効になっています 400、401、402、403、404、409、422、415 操作なし ユーザーへの自動返金 200、201、204 操作なし 操作なし 別のコードまたはウェブフックへの応答なし 指定された時間間隔内に複数のウェブフックが送信されます。5分間隔で2回、15分間隔で7回、60分間隔で10回試行されます。 指定された時間間隔内に複数のウェブフックが送信されます。5分間隔で2回、15分間隔で7回、60分間隔で10回試行されます。すべてのウェブフックが送信されても正常な応答が受信されない場合、ユーザーに自動返金が発行されます。 自動返金機能を接続するには、カスタマーサクセスマネージャーにお問い合わせいただくか、csm@xsolla.comまで電子メールをお送りください。 ## 個人用設定ウェブフック ### パートナー側でのカタログ個人用設定 - [POST personalized-partner-catalog](https://xsolla.redocly.app/ja/webhooks/personalization/personalized-partner-catalog.md): エクソーラは、ユーザーがストアと対話するときに、ユーザーとプロジェクトのパラメータを含む partner_side_catalogウェブフックをウェブフックURLに送信します。 応答として、ユーザが利用可能なitem_idまたはアイテムSKUのリストを返します。この場合、特定のユーザーが特定の製品を指定回数購入 できるという情報を含めることも可能です。この機能により、ユーザーがカートに追加して購入できる製品の数やタイプを制御することができます。 ご注意 ウェブフックを処理するときは、以下の制限事項を考慮してください：ウェブフックは3秒以内に処理される必要があります。処理時間がこれを超過した場合、仮想アイテムを取得する、決済トークンを作成する、または注文を作成するのAPIがエラーを返します。ウェブフックのレスポンスサイズは64 KBを超えてはなりません。この制限を超えるレスポンスは処理されないため、ユーザーには空のカタログが表示され、アイテムを購入することができなくなります。レスポンスサイズの上限変更をご希望の場合は、担当のカスタマーサクセスマネージャーにお問い合わせいただくか、csm@xsolla.comまでメールでご連絡ください。 ## 不正決済防止 ### 不正決済防止ブロックリストの更新 - [POST afs-rejected-blocklist](https://xsolla.redocly.app/ja/webhooks/anti-fraud/afs-rejected-blocklist.md): 不不正決済防止システムのブロックリストが更新（パラメータを追加または削除）される場合、エクソーラはafs_black_listタイプのウェブフックをウェブフックURLに送信します。引数の追加はエクソーラ側で、または要求に応じて自動的に行われます。パラメータは要求時にのみ削除できます。このウェブフックを受信するには、カスタマーサクセスマネージャーにご連絡いただくか、csm@xsolla.comまで電子メールでお問い合わせください。 ### 不正決済防止システムによりトランザクションが拒否されました - [POST afs-rejected-transaction](https://xsolla.redocly.app/ja/webhooks/anti-fraud/afs-rejected-transaction.md): 不正決済防止システムのチェック中にトランザクションが拒否された場合、エクソーラはウェブフックのトランザクションの詳細を「afs_reject」タイプでウェブ フックURLに送信します。このウェブフックを受信するには、カスタマーサクセスマネージャーにご連絡いただくか、csm@xsolla.comまで電子メールでお問い合わせください。 When you save the webhook URL in the account, you can give permissions to receive detailed information in webhooks. To do that, activate the following toggle in your account in the Settings > Webhooks > Advanced settings section. Note If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Settings > Webhooks > Testing > Payments > Advanced settings section. トグル 説明 保存された決済方法による取引に関する情報を表示する 情報は、パラメータの以下のカスタムパラメータに渡されます：saved_payment_method:0 — 保存された決済方法は使用されませんでした1 — 決済方法は現在の支払い時に保存されました2 — 保存された決済方法は使用されませんでしたpayment_type:1 — 一回払い2 — 定期支払い ### 異議申立 - [POST dispute](https://xsolla.redocly.app/ja/webhooks/anti-fraud/dispute.md): 新しい異議申立が行われ、または異議申立のステータスが変更された時、エクソーラは「dispute」タイプのウェブフックをウェブフックURLに送信します。このウェブフックを受信するには、カスタマーサクセスマネージャーにご連絡いただくか、csm@xsolla.comまで電子メールでお問い合わせください。 ## サブスクリプション ### キャンセルされたサブスクリプション - [POST canceled-subscription](https://xsolla.redocly.app/ja/webhooks/subscriptions/canceled-subscription.md): サブスクリプションがキャンセルされる場合、エクソーラは「cancel_subscription」タイプのウェブフックをウェブフックURLに送信します。 ### 作成されたサブスクリプション - [POST created-subscription](https://xsolla.redocly.app/ja/webhooks/subscriptions/created-subscription.md): ユーザーがサブスクリプションを作成すると、エクソーラはcreate_subscriptionタイプのウェブフックをウェブフックURLに送信します。 ### 非更新のサブスクリプション - [POST nonrenewing-subscription](https://xsolla.redocly.app/ja/webhooks/subscriptions/nonrenewing-subscription.md): サブスクリプションステータスが非更新に設定されている場合、エクソーラはnon_renewal_subscriptionタイプのウェブフックをウェブフックURLに送信します。このウェブフックを受信するには、カスタマーサクセスマネージャーにご連絡いただくか、csm@xsolla.comまで電子メールでお問い合わせください。 ### 更新されたサブスクリプション - [POST updated-subscription](https://xsolla.redocly.app/ja/webhooks/subscriptions/updated-subscription.md): サブスクリプションのパラメータ（plan_id、date_next_charge）が変更された場合、そしてサブスクリプションが更新される時に、エクソーラはupdate_subscriptionタイプのウェブフックをウェブフックURLに送信します。