エクソーラデータにアクセスするために、プロジェクトに最も適した方法を選択してください：

 1const client = new Centrifuge(
 2connectionURL,
 3{
 4data: {
 5  user_external_id: user_external_id,
 6  auth: auth,
 7  project_id: project_id
 8}
 9}
10)
11connectionURL - wss://ws-store.xsolla.com/connection/websocket
12auth - user JWT token

1client.on('publication', (ctx) => {
2   //handle the status
3});

1client.connect()

 1client.on('subscribed', function (ctx) {
 2   client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
 3resp.publications.forEach((ctx) => {
 4   /handle the status
 5});
 6
 7   }, function (err) {
 8       //handle the status
 9   });
10});

1{
2order_id: 59614241,
3status: "new"
4}

作成された注文のステータスを追跡して検証するには、アプリケーションのサーバー側でウェブフック処理を構成する必要があります。

PHP SDK

ウェブフック処理には既製のクラスを使用する

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

以下のスキームは、集約ウェブフックを使用してアイテムを購入して返品するプロセスを示しています。

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

アイテムカタログのパーソナライゼーションがアプリケーション側で実装されている場合は、パートナー側でカタログのパーソナライゼーションの処理を設定します。

ウェブフックの完全なリストと、ウェブフックの操作に関する一般情報については、ウェブフックに関するドキュメントを参照してください。

ウェブフックの送信を設定する

エクソーラ側でウェブフックを構成するには：

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

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

ウェブフックリスナーを追加する

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

署名の生成

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

署名を生成するには：

1. リクエスト本文のJSONとプロジェクトの秘密鍵を連結します。
2. 最初のステップで取得した文字列にSHA-1暗号化ハッシュ関数を適用します。

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

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

• 成功した応答の場合は200、201、または204 HTTPコード。
• 指定したユーザーが見つからなかったり、無効な署名が渡された場合、問題に関する説明が記載された400 HTTPコードが表示されます。

ウェブフックハンドラーは、サーバーに一時的な問題が発生した場合に5xxコードを返すこともあります。

エクソーラサーバーが「注文支払い完了」と「注文のキャンセル」のウェブフックで応答を受信しなかった場合、または5xxコードの応答を受信した場合、以下のスケジュールでウェブフックを再送信します：

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

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

決済および返金のウェブフックにおけるリトライロジックについては、それぞれのウェブフック詳細ページに記載されています。

エクソーラサーバーがユーザー検証ウェブフックに対する応答が受信されなかった場合、400または5xxのコードを含む応答が受信された場合、ユーザー検証ウェブフックは再送信されません。

この場合、ユーザーにはエラーが表示され、「決済」と「注文支払い完了」のウェブフックは送信されません。

ウェブフックにおけるアイテム情報の構成

注文支払い完了と注文のキャンセルのウェブフックで送信されるアイテムデータは、items配列を通じて設定できます。

追加パラメータの包含の有効化

以下の情報を示す追加パラメータの包含を有効にします：

• アイテムが無料かどう（is_free）
• アイテムがボーナスかどうか（is_bonus）
• アイテムがバンドルの一部かどうか（is_bundle_content）

これらのパラメータを受け取るには、ウェブフック設定に関する情報を更新するAPIコールを使用してウェブフックのバージョンを2に変更してください。バージョン1（デフォルト）では、これらのパラメータは提供されていません。

追加パラメータを含むアイテム配列の例：

 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のアイテムは除外されます。

バンドルコンテンツが無効になっている場合のアイテム配列の例：

 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に電子メールを送信してください。