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

注意

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

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

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

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

# 必須なウェブフックのリスト {% #list-of-required-webhooks %} ウェブフックの操作が必要な製品やソリューションを使用している場合、パブリッシャーアカウントでウェブフックを有効化してテストし、その処理をセットアップします。特定のイベントが発生する時、ウェブフックが順次送信されます。したがって、1つのウェブフックを処理しない場合、その後のウェブフックは送信されません。必要なウェブフックのリストは以下の通りです。 ## ストアと決済ソリューション {% #store-and-payments %} エクソーラ側では、サイトでアイテムを購入して返品する際に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に関する情報が含まれます。ウェブフックのデータを使用して、購入したアイテムを削除します。

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

注意

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

個別のウェブフックを受信する場合、支払い、注意文支払い完了、およびユーザー検証
まとめたウェブフックを受信する場合、注意文支払い完了とユーザー検証

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

注意。

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

3. 秘密鍵を生成します：

秘密鍵セクションで、「キーを追加」クリックします。
開いたモーダルウィンドウに、一般リストからこの項目を識別するためのキー名を入力してください。。
「キーを作成」クリックします。
「シークレットをコピー」をクリックし、作成されたキーをユーザー側で保存してください。
「完了」クリックします。
キーが保存されたことを確認し、「OK、閉じる」をクリックします。

![Add key](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/add-key.svg)

注意

キーに関する推奨事項：

生成されたシークレットキーは手元に保存してください。キーは作成時に一度だけパブリッシャーアカウントで確認できます。
秘密鍵は決して他人に教えないでください。
秘密鍵はサーバー上に保存する必要があり、バイナリファイルやフロントエンドには決して保存してはいけません。

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

注意

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

注意

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

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

注意

キーに関する推奨事項：

生成されたシークレットキーは手元に保存してください。キーは作成時に一度だけパブリッシャーアカウントで確認できます。
秘密鍵は決して他人に教えないでください。
秘密鍵はサーバー上に保存する必要があり、バイナリファイルやフロントエンドには決して保存してはいけません。

プロジェクトごとに有効な秘密鍵は1つだけです。変更したい場合は、別のキーの行にある「**有効にする**」をクリックして操作を確定してください。新しいキーへの移行が正常に完了した後は、無効化されたキーを削除することをお勧めします。 ![Change active key](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/activate-key.svg) ## 詳細設定 {% #advanced-settings %} ウェブフックについては決済ソリューションとストアセクションでは、詳細設定が利用できます。「ウェブフックを取得」ボタンをクリックすると、自動的に一般設定ブロックの下に表示されます。

注意

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

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

トグル	説明
保存された決済アカウントに関する情報を表示します（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-publisher-account %} ウェブフックをテストすると、ユーザー側とエクソーラ側の両方でプロジェクトが正しく設定されていることを確認できます。ウェブフックが正常にセットアップした場合、ウェブフック設定セクションの下にウェブフックのテストセクションが表示されます。 ![Webhooks testing section](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-section.svg) パブリッシャーアカウントのテストセクションは、ウェブフック受信オプションによって異なります。 2025年1月22日以降にパブリッシャーアカウントに登録した場合、以下の統合されたウェブフックを受信します：

ウェブフックテストのタブ名	ウェブフック名とタイプ
決済ソリューションとストア	ユーザー検証 > ユーザー検証（`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. ドロップダウンリストからアイテムタイプを選択してください。パブリッシャーアカウントでこのアイテムタイプをまだ設定していない場合は、ボタンをクリックして設定してください。アイテム作成後、ウェブフックテストセクションに戻り、次のステップに進んでください。 3. 必要なフィールドに入力します： * **ユーザーID** — テスト時には、任意の文字と数字の組み合わせを使用できます。 * 「**エクソーラ注文ID**」フィールドに任意の値を入力してください。 * **エクソーラインボイスID** — エクソーラ側のトランザクションID。テスト時には、任意の数値を使用できます。 * **インボイスID** — ゲーム側のトランザクションID。テスト時には、任意の文字と数字の組み合わせを使用できます。これは成功した支払いに必須のパラメータではありませんが、トランザクションIDをエクソーラ側のトランザクションIDとリンクさせるために渡すことができます。 * **金額** — 決済金額。テスト時には、任意の数値を使用できます。 * **通貨** — ドロップダウンリストから通貨を選択します。 * ドロップダウンリストからアイテムのSKUを選択し、数量を指定します。同じタイプの複数のアイテムを選択するには、「**+**」をクリックして新しい行に追加します。 4. 「**ウェブフックをテスト**」をクリックします。指定されたデータを含むユーザー検証、注文支払い完了および注文キャンセルウェブフックが、指定されたURLに送信されます。各ウェブフックタイプのテスト結果は、「ウェブフックをテスト」ボタンの下に表示されます。プロジェクト設定 > 統合設定セクションで公開ユーザーIDを使用するボックスにチェックが入っている場合、ユーザー検索ウェブフックは、お客様のウェブフックサーバーのURLにも送信され、テスト結果が表示されます。各ウェブフックについて、成功したシナリオとエラーが発生したシナリオの両方の処理を設定する必要があります。 ![Payments testing section](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-results.svg) ## サブスクリプション {% #test-webhooks-subscriptions %}

注意

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

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

注意

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

ウェブフックをテストするには： 1. テストセクションで、**サブスクリプション**タブに移動します。 2. 必要なフィールドに入力します： * **ユーザーID** — テスト時には、任意の文字と数字の組み合わせを使用できます。 * **エクソーラインボイスID** — エクソーラ側のトランザクションID。テスト時には、任意の数値を使用できます。 * **公開ユーザーID** — メールアドレスやニックネームなど、ユーザーに知られているIDです。このフィールドは、プロジェクトの[プロジェクト設定 > 統合設定](https://publisher.xsolla.com/0/projects/0/edit/advanced)セクションで**公開ユーザーIDを使用する**チェックボックスにチェックを入れている場合に表示されます。 * **金額** — 決済金額。テスト時には、任意の数値を使用できます。 * **通貨** — ドロップダウンリストから通貨を選択します。 * **プラン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. 比較用に独自の署名を生成します：

JSONペイロードとプロジェクトの秘密鍵を連結します。秘密鍵は文字列の末尾に追加してください。
結果の文字列に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に送信されます。ゲーム、ウェブサイト、またはモバイルアプリケーションで通知を受け取りたい場合は、お客様のサーバー側でウェブフックの送信設定を行い、エクソーラとお使いのゲーム間でデータを渡すようにしてください。また、開発者コンソールからウェブフックのテストを行うことも可能です。

注意

ローカル環境で統合のテストを行っている場合、エクソーラからの`POST`リクエストはhttp://localhost:3000/my-webhook-endpointのようなURLには届きません。外部からのアクセスを可能にするトンネルを作成できるNgrokなどのサービスを使用することで、ローカル環境でエクソーラからのリクエストを受信できるようになります。詳細については、ngrokに関するドキュメントを参照してください。

## エクソーラからの通知がウェブフック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に変更された場合このリクエストは、任意の決済方法で支払いを行う際に送信されます。パブリッシャーアカウントにウェブフックURLを保存すると、ウェブフックで詳細情報を受信する権限を与えることができます。これを行うには、パブリッシャーアカウントの「プロジェクト設定> ; ウェブフック> 詳細設定」セクションで必要なトグルを「アクティブ」に設定します。注意 2025年1月22日以前にパブリッシャーアカウントに登録した場合は、「プロジェクト設定>ウェブフック>テスト>決済ソリューション>詳細設定」セクションでトグルを見つけます。トグル説明機密データは含まず、必要なユーザーパラメータのみを送信するウェブフックでは、ユーザーに関する次の情報のみが渡されます：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にキャンセルされたトランザクションの詳細を送信します。返金プロセスの一部の詳細は、これらの説明を参照してください。パブリッシャーアカウントにウェブフックURLを保存すると、ウェブフックで詳細情報を受信する権限を与えることができます。これを行うには、パブリッシャーアカウントのプロジェクト設定> ; ウェブフック> 詳細設定セクションで次のトグルを「アクティブ」に設定します。注意 2025年1月22日以前にパブリッシャーアカウントに登録した場合は、「プロジェクト設定>ウェブフック>テスト>決済ソリューション>詳細設定」セクションでトグルを見つけます。トグル説明保存された決済方法による取引に関する情報を表示する情報は、パラメータの以下のカスタムパラメータに渡されます：saved_payment_method:0 — 保存された決済方法は使用されませんでした1 — 決済方法は現在の支払い時に保存されました2 — 保存された決済方法は使用されませんでしたpayment_type:1 — 一回払い2 — 定期支払い返金コード：コード理由説明 1 Cancellation by the user request / the game request パブリッシャーアカウントからキャンセルが開始されました。 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回です。パブリッシャーアカウントでウェブフックURLを保存すると、ウェブフックで追加情報を受信するように設定することもできます。注意 2025年1月22日以前にパブリッシャーアカウントに登録した場合は、プロジェクトで設定 > ウェブフック > テスト > 決済ソリューション > 詳細設定セクションでトグルを見つけます。トグル説明保存された決済アカウントに関する情報を表示する保存された決済方法に関する情報は、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オブジェクトがウェブフックで渡されます。お知らせウェブフックで送信されるフィールドのセットは、以下によって異なります：パブリッシャーアカウントで構成された詳細設定エクソーラ側で構成されたカスタム設定ご質問がある場合は、カスタマーサクセスマネージャーを連絡して、または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ステータスコードが返された場合。パブリッシャーアカウントでウェブフックURLを保存すると、ウェブフックで追加情報を受信するように設定することもできます。注意 2025年1月22日以前にパブリッシャーアカウントに登録した場合は、プロジェクトで設定 > ウェブフック > テスト > 決済ソリューション > 詳細設定セクションでトグルを見つけます。トグル説明保存された決済方法による取引に関する情報を表示する情報は、ウェブフックの以下のカスタムパラメータに渡されます：saved_payment_method:0 — 保存された決済方法は使用されませんでした1 — 決済方法は現在の支払い時に保存されました2 — 保存された決済方法は使用されませんでしたpayment_type:1 — 一回払い2 — 定期支払い返金理由に関する情報を表示します。返金理由に関する詳細情報。返金コード：コード理由説明 1 Cancellation by the user request / the game request パブリッシャーアカウントからキャンセルが開始されました。 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秒未満にすることをお勧めします。お知らせウェブフックで送信されるフィールドのセットは、次の設定によって異なります：パブリッシャーアカウントの「プロジェクト設定>ウェブフック>詳細設定」セクションで構成されたウェブフックエクソーラ側で構成されたウェブフックご不明な点がございましたら、カスタマーサクセスマネージャーに連絡して、または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まで電子メールでお問い合わせください。パブリッシャーアカウントにウェブフックURLを保存すると、ウェブフックで詳細情報を受信する権限を与えることができます。これを行うには、パブリッシャーアカウントのプロジェクト設定> ; ウェブフック> 詳細設定セクションで次のトグルを「アクティブ」に設定します。注意 2025年1月22日以前にパブリッシャーアカウントに登録した場合は、「プロジェクト設定>ウェブフック>テスト>決済ソリューション>詳細設定」セクションでトグルを見つけます。トグル説明保存された決済方法による取引に関する情報を表示する情報は、パラメータの以下のカスタムパラメータに渡されます：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に送信します。