Xsolla-logo

概要

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

イベントの例：

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

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

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

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

支払い処理ウェブフック

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

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

詳細については、デジタル配信ソリューションのウェブフック設定方法に関する説明をご覧ください。

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

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

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

インゲームストアを完全に操作するには、メインウェブフックの処理を実装する必要があります：

  • ユーザーの検証（user_validation） — 決済プロセスのさまざまな段階で送信され、ユーザーがゲームに登録されていることを確認します。
  • 決済（payment） — 注文が支払われたときに送信され、決済データとトランザクションの詳細が含まれます。
  • 注文の支払いが完了しました（order_paid） — 決済ウェブフックが正常に処理されたときに送信され、購入したアイテムに関する情報とト ランザクションIDを含んでいます。ウェブフックからのデータを使用して、ユーザーにアイテムを追加します。
  • 返金（refund） — 注文がキャンセルされたときに送信され、キャンセルされた決済データとトランザクションの詳細が含まれます。
  • 注文キャンセル（order_canceled ） — 返金ウェブフックが正常に処理されたときに送信され、購入したアイテムに関する情報とキャ ンセルされたトランザクションのIDが含まれています。購入したアイテムを削除するには、ウェブフックのデータを使用します。

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

注

実際の支払いを受け取るには、決済、注文の支払いが完了しました、そしてユーザーの検証ウェブフックだけでなく、ライセンス契約に署名するウェブフックの処理を実装します。

サブスクリプション

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

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

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

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

  1. アドミンページでプロジェクトを開きます。
  2. サイドメニューで、「プロジェクト設定」をクリックして「ウェブフック」タブに移動します。
  3. ウェブフックサーバーフィールドには、ウェブフックを受信したいサーバーのURLを https://example.com 形式で指定します。ウェブフックをテストするツールで見つけたURLを指定することもできます。
  4. プロジェクトのウェブフックに署名するための秘密鍵は、デフォルトで生成されます。新しい秘密鍵を生成したい場合は、更新アイコンをクリックしてください。
  5. 「ウェブフックを有効にする」をクリックします。

注

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

注意

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

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

  1. アドミンページでプロジェクトを開きます。
  2. サイドメニューで、「プロジェクト設定」をクリックして「ウェブフック」タブに移動します。
  3. 「ウェブフックを無効にする」をクリックします。

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

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

以下のウェブフックの受信をテストできます：

ウェブフック名 ウェブフックタイプ
ユーザーの検証 user_validation
決済 payment
注文のキャンセル order_canceled
注文の支払いが完了しました order_paid

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

ウェブフックのテストセクション

注

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

例：

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

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

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

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

テストエラー

ストア

「ストア」タブでは、次のウェブフックをテストできます：

テストするには：

  1. ウェブフックのテストセクションで、「ストア」タブに移動します。
  2. ドロップダウンメニューで、アイテムのタイプを選択します。選択したタイプのアイテムがアドミンページに設定されていない場合は、以下をクリックします：
    • 接続 – このタイプのアイテムを含むモジュールが接続されていない場合
    • 構成 – 以前にモジュールを接続したが、セットアップを完了していない場合
      ボタンをクリックすると、選択したアイテムのタイプに対応するアドミンページのセクションにリ ダイレクトされます。アイテムを作成したら、ウェブフックのテストセクションに戻り、次のステップに進みます。
  3. 「エクソーラ注文ID」フィールドに任意の値を入力してください。
  4. ドロップダウンリストからアイテムのSKUを選択し、数量を指定します。同じタイプの複数のアイテムを選択するには、「+」をクリックして新しい行に追加し ます。
  5. 注文の支払いに使用する通貨を選択します。
  6. 「テスト」をクリックします。

注文の支払いが成功しましたそして注文のキャンセルのウェブフックは、指定されたデータを指定されたURLに送信します。各ウェブフックタイプのテスト結果は、「ウェブフックをテストする」ボタンの下に表示されます。

ウェブフックのテストセクション

決済ソリューション

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

テストするには：

  1. テストセクションで、決済ソリューションタブに移動します。

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

指定されたURLには、データが入力されたウェブフックが送信されます。成功したシナリオとエラーが発生したシナリオの両方のテスト結果は、「ウェブフックをテスト する」ボタンの下に表示されます。プロジェクトでパブリックユーザーIDが有効になっている場合は、ユーザー検索の結果も表示されます。

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

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

「ウェブフックサーバー」フィールドにURLを保存すると、「高度な設定」セクションが表示されます。ここで、ウェブフックで詳細情報を受信 するための権限を付与できます。そのためには、それぞれのトグルをオンに設定してください。各権限の行には、設定によって影響を受けるウェブフックのリスト が表示されます。

トグル 説明
保存された決済アカウントに関する情報を表示する 保存された決済方法に関する情報は、payment_accountカスタムオブジェクト。
保存された決済方法による取引に関する情報を表示する

情報は、パラメータの以下のカスタムパラメータに渡されます：

  • saved_payment_method:
    • 0 — 保存された決済方法は使用されませんでした
    • 1 — 決済方法は現在の支払い時に保存されました
    • 2 — 保存された決済方法は使用されませんでした
  • payment_type:
    • 1 — 一回払い
    • 2 — 定期支払い
注文オブジェクトをウェブフックに追加する 注文に関する情報は、決済ウェブフックのorderオブジェクトに渡されます。
機密データは含まず、必要なユーザーパラメータのみを送信する

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

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

銀行カード番号に関する次の情報がウェブフックで渡されます。

  • card_binパラメータの最初の6桁
  • card_suffixパラメータの最後の4桁
カードブランドを表示する 決済に使用したカードのブランド。例えば、MastercardやVisaなど。

高度な設定

サブスクリプション

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

注

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

注

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

テストするには：

  1. テストセクションで、サブスクリプションタブに移動します。

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

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

ウェブフックリスナー

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

注

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

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

制限：

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

署名の生成

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

  1. リクエスト本文のJSONとプロジェクトの秘密鍵を連結します。
  2. 最初のステップで得られた文字列にSHA-1暗号ハッシュ関数を適用します。
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

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

ウェブフックへの応答の送信

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

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

注文の支払いが完了しましたと注文のキャンセルのウェブフックに対して応答を受信しなかった場合、または 5xx コードの応答を受信した場合、ウェブフックは以下のスケジュールに従って再送信されます：

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

ウェブフックの送信は、最初の送信から12時間以内に最大20回まで試行されます。決済ウェブフックまたは返金ウェブフックのいずれかに対して応答が受信されなかった場合、または5xxコード の応答が受信された場合、ウェブフックは増加した時間間隔で再送信されます。12時間以内に最大12回の試行が行われます。

注意

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

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

エラー

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

コード メッセージ
INVALID_USER 無効なユーザー
INVALID_PARAMETER 無効なパラメータ
INVALID_SIGNATURE 無効な署名
INCORRECT_AMOUNT 不正確な金額
INCORRECT_INVOICE 不正確なインボイス 
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

ウェブフックリスト

注

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

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

Privacy Settings

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