ユーザーに購入権限を付与する
エクソーラから受け取ったトランザクションの詳細および購入したアイテムに関するウェブフックから受信した情報を使用して、アプリケーション内のユーザーに購入を付与する機能を実装します。
エクソーラでは、アイテムの購入および返金時にウェブフックを受信するための2つのオプションがあります：決済およびトランザクションデータを含む情報と、購入されたアイテムに関する情報は、それぞれ個別のウェブフックとして受信するか、1つに統合して受信するかを選択できます。デフォルトでは、すべての新しいプロジェクトで統合されたウェブフックを受信します。
統合されたウェブフックを受信する新しいオプションに切り替えるには、カスタマーサクセスマネージャーに連絡するか、csm@xsolla.comにメールしてください。
ウェブフックの受信オプションに関する詳細情報
統合されたウェブフックで情報を受信します：
2025年1月22日以降にパブリッシャーアカウントに登録した場合、注文の支払い成功 (order_paid) および 注文のキャンセル (order_canceled) のウェブフックで情報を受け取ります。この場合、支払い (payment) および 返金 (refund) のウェブフックを処理する必要はありません。
別々のウェブフックで情報を受信します：
2025年1月22日以前にパブリッシャーアカウントに登録した場合、以下のウェブフックを受信します：
- 支払い (
payment) および 返金 (refund) は、支払いデータとトランザクションの詳細に関する情報を含みます。 - 注文の支払い成功 (
order_paid) および 注文のキャンセル (order_canceled) は、購入アイテムに関する情報を含みます。
すべての受信ウェブフックを処理する必要があります。
インゲームストアと決済管理を完全に運用するためには、主要なウェブフックの処理を実装する必要があります：
| ウェブフック名 | 説明 |
|---|---|
ユーザー認証 > ユーザー認証 (user_validation) | ユーザーがゲームに登録されているか確認するため、支払いプロセスのさまざまな段階で送信されます。 |
ゲームサービス > 統合されたウェブフック > 注文の支払い成功 (order_paid) | 決済データ、トランザクションの詳細、および購入されたアイテムに関する情報が含まれます。ウェブフックのデータを使用して、ユーザーにアイテムを追加してください。 |
ゲームサービス > 統合されたウェブフック > 注文キャンセル (order_canceled) | キャンセルされた決済のデータ、トランザクションの詳細、および購入されたアイテムに関する情報が含まれます。ウェブフックのデータを使用して、購入されたアイテムを削除してください。 |
以下の図は、統合されたウェブフックを使用したアイテムの購入および返品のプロセスを示しています。
%%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
participant User as ユーザー
participant GameClient as ゲームクライアント
participant Xsolla as エクソーラ
participant GameServer as ゲームサーバー
%% Item Purchase
rect rgb(243, 243, 241)
Note over User, GameServer: アイテム購入
end
User ->> GameClient: ログイン
activate GameClient
GameClient ->> Xsolla: ユーザー認証リクエストを送信する
activate Xsolla
Xsolla -->> GameClient: JWT/OAuth 2.0トークンを返す
deactivate Xsolla
GameClient ->> Xsolla: JWT、プロジェクトID、ページネーションパラメータを送信する
activate Xsolla
Xsolla -->> GameClient: アイテム配列を返す
deactivate Xsolla
GameClient -->> User: ストアフロントが表示される
deactivate GameClient
User ->> GameClient: アイテムを選択し「購入」をクリックする
activate GameClient
GameClient ->> Xsolla: 注文リクエストを作成する
deactivate GameClient
activate Xsolla
Xsolla -->> GameClient: 決済トークンを返す
deactivate Xsolla
activate GameClient
GameClient ->> Xsolla: 受け取ったトークンを使用して決済UIのURLを開く
deactivate GameClient
activate Xsolla
Xsolla ->> GameServer: ユーザー検証のウェーブフックを送信する
activate GameServer
GameServer -->> Xsolla: 成功ステータスコードを返す
deactivate GameServer
Xsolla -->> User: 決済UIが表示される
deactivate Xsolla
User ->> Xsolla: ユーザーが決済方法を選択し、支払いボタンをクリックする
activate Xsolla
Xsolla ->> GameServer: 「注文支払い完了」のウェブフックを送信する
activate GameServer
activate GameServer
Note right of GameServer: ユーザーに購入アイテムを付与する
deactivate GameServer
GameServer -->> Xsolla: 成功ステータスコードを返す
deactivate GameServer
Xsolla -->> User: 購入完了画面が表示される
deactivate Xsolla
%% Refund / Chargeback
rect rgb(243, 243, 241)
Note over User, GameServer: 返金 / チャージバック
end
User ->> Xsolla: 返金またはチャージバックをリクエストする
activate Xsolla
Xsolla ->> GameServer: 注文キャンセルのウェーブフックを送信する
activate GameServer
activate GameServer
Note right of GameServer: ユーザーのインベントリからアイテムを削除する
deactivate GameServer
GameServer -->> Xsolla: 成功ステータスコードを返す
deactivate GameServer
Xsolla -->> User: 代金を払い戻す
deactivate Xsolla
アイテムカタログの個人用設定がアプリケーション側で実装されている場合は、パートナー側のカタログ個人用設定の処理を設定してください。
パブリッシャーアカウントでのウェブフックのセットアップ
ウェブフックの受信を有効にするには：
- パブリッシャーアカウントのプロジェクトで、プロジェクト設定 > ウェブフックセクションに移動します。
- ウェブフックサーバーのフィールドに、ウェブフックを受信したいサーバーのURLを
https://example.comの形式で指定します。ウェブフックのテスト用ツールで見つけたURLを指定することもできます。
- 秘密鍵を生成します：
- 秘密鍵セクションで、「キーを追加」をクリックします。
- 開いたモーダルウィンドウで、一般リストで識別できるように鍵の名前を入力します。
- 「キーを作成」をクリックします。
- 「シークレットをコピー」をクリックし、作成したキーを保存します。
- 「完了」をクリックします。
- キーを保存したことを確認し、「OK、閉じる」をクリックします。
キーに関する推奨事項：
- 生成された秘密鍵は必ず手元に保存してください。パブリッシャーアカウント内でキーを確認できるのは、作成時の1回のみです。
- 秘密鍵を他人と共有しないでください。
- 秘密鍵はサーバーに保存し、バイナリやフロントエンドには保存しないでください。
- 「ウェブフックを有効にする」をクリックします。
秘密鍵のローテーション
プロジェクトで最大5つの秘密鍵を作成して、ローテーションを有効にできます。
プロジェクトごとにアクティブな秘密鍵は1つだけです。変更したい場合は、別の鍵の行で「アクティブとして設定」をクリックし、アクションを確認します。新しいキーへの移行が成功したら、非アクティブなキーを削除することをお勧めします。
パブリッシャーアカウントでのウェブフックをテストする
プロジェクトでウェブフックを有効化すると、パブリッシャーアカウント内の詳細設定の下に、ウェブフックをテストするためのセクションが表示されます。
次のウェブフックをテストできます：
| ウェブフックテスト用タブ名 | ウェブフック名とタイプ |
|---|---|
| 決済ソリューションとストア | ユーザー検証 > ユーザー検証（user_validation） |
ゲームサービス > 組み込みのウェブフック > 注文支払い完了（order_paid） | |
ゲームサービス > 組み込みのウェブフック > 注文のキャンセル（order_canceled） | |
| サブスクリプション | ユーザー検証 > ユーザー検証（user_validation） |
決済 > 支払い（payment） | |
| 異議申し立て | 不正決済防止 > 異議申し立て (dispute) |
実数値がない場合は、任意の値を入力できます。
サンドボックスモードまたはライブモードで購入する際にウェブフックをテストすることもできます。返金をテストする機能はライブモードでのみ利用できます。
ウェブフックへの応答の送信
ウェブフックの受信を確認するには、サーバーが以下のことを返す必要があります：
- 成功した応答の場合は
200、201、または204HTTPコード。 - 指定したユーザーが見つからなかったり、無効な署名が渡された場合、問題に関する説明が記載された
400HTTPコードが表示されます。
ウェブフックハンドラーは、サーバーに一時的な問題が発生した場合に5xxコードを返すこともあります。
次のステップ
- サブスクリプションの販売を設定します（任意）。
- ユーザー認証を設定します。
ウェブフックにおけるアイテム情報の構成
注文支払い完了と注文のキャンセルのウェブフックで送信されるアイテムデータは、items配列を通じて設定できます。
追加パラメータの包含の有効化
以下の情報を示す追加パラメータの包含を有効にします：
- アイテムが無料かどう（
is_free） - アイテムがボーナスかどうか（
is_bonus） - アイテムがバンドルの一部かどうか（
is_bundle_content）
これらのパラメータを受け取るには、ウェブフック設定に関する情報を更新するAPIコールを使用してウェブフックのバージョンを2に変更してください。バージョン1（デフォルト）では、これらのパラメータは提供されていません。
追加パラメータを含むアイテム配列の例：
- json
1"items": [
2 {
3 "sku": "com.xsolla.item_new_1",
4 "type": "bundle",
5 "is_pre_order": false,
6 "is_free": false,
7 "is_bonus": false,
8 "is_bundle_content": false,
9 "quantity": 1,
10 "amount": "1000",
11 "promotions": []
12 },
13 {
14 "sku": "com.xsolla.gold_1",
15 "type": "virtual_currency",
16 "is_pre_order": false,
17 "is_free": false,
18 "is_bonus": false,
19 "is_bundle_content": true,
20 "quantity": 1500,
21 "amount": "[null]",
22 "promotions": []
23 }
24 ]
バンドルコンテンツ包含の無効化
デフォルトでは、ウェブフックはバンドルのすべてのアイテムを個別のアイテムのリストとして含めます。ウェブフックのコンテンツをリスト化せずに、バンドルそのもののみを含めるように設定することができます。
この場合、バンドルに含まれるアイテムはitems配列には含まれません。上記の配列で示されているように、バンドルの一部であるSKUcom.xsolla.gold_1のアイテムは除外されます。
バンドルコンテンツが無効になっている場合のアイテム配列の例：
- json
1
2"items": [
3 {
4 "sku": "com.xsolla.item_new_1",
5 "type": "bundle",
6 "is_pre_order": false,
7 "is_free": false,
8 "is_bonus": false,
9 "is_bundle_content": false,
10 "quantity": 1,
11 "amount": "1000",
12 "promotions": []
13 }
14 ]
バンドルコンテンツ包含を無効にするには、カスタマーサクセスマネージャーまでお問い合わせるか、csm@xsolla.comに電子メールを送信してください。
お役立ちリンク
最終更新日: 2026年6月5日誤字脱字などのテキストエラーを見つけましたか？ テキストを選択し、Ctrl+Enterを押します。
