サブスクリプション情報を取得する

サブスクリプションを利用したアクティビティの情報は、以下の方法で取得できます：

• APIコールを利用して情報をリクエストする（サーバーレス統合に適用する）
• ウェブフックを利用してサブスクリプションのステータスが自動的に変更されたときに情報を取得する（サーバー統合に適用する）

API経由のセットアップ

プロジェクトIDをパスパラメータprojectIdとして指定します。このパラメータは、パブリッシャーアカウントでプロジェクト名の隣に表示されます。

クエリのパラメータとして指定します：

• limit — ページに表示される要素数の上限（デフォルトでは15個の要素が表示されます）。
• offset — リストが生成された要素の番号（カウントは0から始まります）。
• locale — インターフェイスの言語（デフォルトでは英語）。ISO 639-1規格に準拠した値を受け入れます。

1curl -X 'GET' \
2  'https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

 1{
 2  "items": [
 3    {
 4      "id": 11111111,
 5      "plan_id": 11111,
 6      "plan_external_id": "TestChangePlanBase",
 7      "plan_name": "package_recurrent_name_66053",
 8      "plan_description": "package_recurrent_description_66053",
 9      "product_id": null,
10      "product_external_id": null,
11      "product_name": null,
12      "product_description": null,
13      "status": "active",
14      "date_create": "2021-03-11T13:50:11+03:00",
15      "date_next_charge": "2031-04-11T13:51:02+03:00",
16      "date_last_charge": "2021-03-11T13:51:02+03:00",
17      "charge": {
18        "amount": "0.2500",
19        "currency": "USD"
20      },
21      "period": {
22        "value": 1,
23        "unit": "day"
24      }
25    }
26  ],
27  "has_more": true
28}

ウェブフックをセットアップする

サブスクリプションソリューションでは、以下のイベントのウェブフックをサポートしています：

• サブスクリプションを支払う：
  • ユーザーの確認
  • 支払い
  • 作成されたサブスクリプション

• サブスクリプションを更新する：
  • ユーザーの確認
  • 支払い
  • 更新されたサブスクリプション
• サブスクリプションをキャンセルする：キャンセルされたサブスクリプション（パブリッシャーアカウントでサブスクリプションがキャンセルされたか、またはすべての有効期間の支払いがキャンセルされた）

• 返金：
  • 返金（パブリッシャーアカウントで支払いがキャンセルされました）
  • 更新されたサブスクリプション（支払いはキャンセルされましたが、サブスクリプションはまだアクティブです。これは、ユーザーが誤ってサブスクリプションの支払いを2回行い、最後の支払いのみをキャンセルした場合に発生する可能性があります。）
  • キャンセルされたサブスクリプション（パブリッシャーアカウントで支払いがキャンセルされたか、すべての有効期間にわたってすべての支払いがキャンセルされました）

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

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

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

1. 秘密鍵セクションで、「キーを追加」をクリックします。
2. 開いたモーダルウィンドウで、一般リストで識別できるように鍵の名前を入力します。
3. 「キーを作成」をクリックします。
4. 「シークレットをコピー」をクリックし、作成したキーを保存します。
5. 「完了」をクリックします。
6. キーを保存したことを確認し、「OK、閉じる」をクリックします。

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

秘密鍵のローテーション

プロジェクトで最大5つの秘密鍵を作成して、ローテーションを有効にできます。

プロジェクトごとにアクティブな秘密鍵は1つだけです。変更したい場合は、別の鍵の行で「アクティブとして設定」をクリックし、アクションを確認します。新しいキーへの移行が成功したら、非アクティブなキーを削除することをお勧めします。

5. パブリッシャーアカウントでウェブフックをテストします。
6. サブスクリプション購入をテストします。
7. サブスクリプション更新をテストします。
8. サブスクリプションのキャンセルをテストします。

パブリッシャーアカウントでのウェブフックをテストする

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

• ユーザー検証 (user_validation)
• 決済 (payment)

ウェブフックをテストするには：

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

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

サブスクリプション購入をテストする

決済をテストする場合、ユーザー検証、決済、および作成されたサブスクリプションの各ウェブフックは、ウェブフックをセットアップするステップで指定したURLに送信されます。支払いプロセスをテストするには：

• サンドボックスモードを使用します（サブスクリプション試用期間が0日の場合）
• 実際の支払いを行い、パブリッシャーアカウントから返金を開始します（サブスクリプション試用期間が0日を超える場合）

サンドボックスモード

1. サンドボックスモード用のトークンを取得します。試用期間（trial_days）パラメータに0の値を渡します。
2. 決済方法のクレジットカード/デビットカードグループを選択します。
3. テスト環境専用カード番号情報を入力して、残りのフィールドに任意の値を入力してください。誤った情報（カード番号、有効期限、CVV）を指定して、エラーを発生させることもできます。

4. ウェブフックをセットアップするステップで指定されたURLでユーザーの確認、支払いおよび更新されたサブスクリプションのウェブフックを受け取ります。

実際のお支払い

1. パブリッシャーアカウントでのウェブフックのテストを完成します。
2. ライセンス契約に署名します。

3. 実際の決済ソリューションのためのトークンを取得します。

4. 以下のリンクから決済UIを開きます：https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN、そこでACCESS_TOKEN は前のステップで得られたトークンです。
5. 決済方法のクレジットカード/デビットカードグループを選択します。
6. 有効な銀行カード情報を入力してください。

7. ウェブフックを設定するステップで提供されたウェブフックURLでユーザー検証、支払いおよび更新されたサブスクリプションウェブフックを受け取ります。
8. 支払いを返金します。これを行うには、パブリッシャーアカウント > プレイヤーサポート > トランザクション検索にアクセスしてください。
9. テスト取引を選択し、その他（•••）メニューボタンをクリックします。ポップアップメニューの返金をクリックします（取引のステータスは完了である必要があります）。これはキャンセルされたサブスクリプションと返金ウェブフックを送信します。

サブスクリプションの更新をテストする

1. サンドボックスモードのトークンを取得します。試用期間（trial_days）パラメータに0の値を渡します。
2. 任意の決済方法を使用してサブスクリプションの支払いを行います。
3. サンドボックスモードで支払いインターフェースを再度開きます。
4. 任意の決済方法を使用してサブスクリプションを更新するには、再度支払います。
5. ウェブフックを設定するステップで指定したウェブフックURLでユーザーの確認、支払いおよび更新されたサブスクリプションのウェブフックを取得します。

テストサブスクリプションのキャンセル

サブスクリプションのキャンセルをテストするには、以下を使用します：

• サブスクリプションで検索する
• 最近の取引で検索する
• APIコール

サブスクリプションで検索する

1. パブリッシャーアカウントを開き、プレイヤーサポート > 登録者セクションに移動します。
2. キャンセルしたいサブスクリプションを探します。
3. サブスクリプションのステータスメニューを開き、以下を選択します：
   1. キャンセルと返金はキャンセルされたサブスクリプションと返金ウェブフックを受け取ります。
   2. 返金なしでキャンセルはキャンセルされたサブスクリプションウェブフックを受け取ります。

最近の取引で検索する

1. パブリッシャーアカウントを開き、プレイヤーサポート > トランザクション検索セクションに移動します。
2. キャンセルされた最後の取引を検索します。
3. その他（•••）アイコンをクリックします。ポップアップメニューの返金をクリックして、キャンセルされたサブスクリプションおよび返金のウェブフックを受け取ります。

APIコールを使用する

サンドボックスモードで決済UIを開く

サンドボックス決済UIを開くには、アクティブなsandboxモードのトークンを取得します。必要なトークンを使用してリンクを取得する方法は次の通り：

• パブリッシャーアカウントを使用する
• APIコールを使用する

パブリッシャーアカウント経由

1. パブリッシャーアカウントでウェブフックをテストします。試用期間がないサブスクリプションをテストする場合は、試用期間フィールドに値を0に指定します。テストが成功したときの確認メッセージを受け取ると、サンドボックスのURLのヘッダーの下に、必要なトークンを含むリンクが表示されます。

2. サンドボックスURLリンクをたどります。

APIコール経由

1. "settings":{"mode":"sandbox"}パラメータをトークンを作成するメソッドに渡します。"purchase": {"subscription":{"trial_days": 0}}パラメータを渡して、試用期間のないサブスクリプションをテストします。
2. 以下のリンクを使用します：https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN、ここでACCESS_TOKENは前のステップで取得したトークンです。