サブスクリプション

サブスクリプションモジュールを使用すると、ユーザーにサブスクリプションを販売できるようになり、ユーザーが一定期間サービスにアクセスできるようになります。特に以下を実行できます:

ユーザーがダッシュボードからサブスクリプションを管理できるようにする。詳細な契約情報の表示、決済履歴の表示、プランの変更、サブスクリプションの一時停止/再開/キャンセルに変更する。
Xsolla パブリッシャ―アカウントを使用してユーザーのサブスクリプションを管理する。各通貨のプランを作成および設定し、体験期間を設定し、猶予期間を設定し、登録しているユーザーを表示し、特定のユーザーのサブスクリプションステータスを変更する。
保存された決済アカウントを使用して自動更新を有効にする。
手動でサブスクリプションを延長する。

ユーザーフロー

パートナーフロー

サブスクリプションのステータス

サブスクリプションのステータスは、次のいずれかです。

Active.プライマリステータス。サブスクリプションは、最初の決済が成功した後に作成され、有効化されます。有効なサブスクリプションでのみ追加料金が発生します。

Canceled.次のいずれかの理由により、サブスクリプションが直ちにキャンセルされました。
- APIメソッドまたは、Xsolla Publisherアカウントから。 ユーザーによってのキャンセル。 サブスクリプションの期限切れ（有効期限がパラメータに設定されている場合）。 課金の最大回数を超えた（既定では3回、変更が必要な場合はアカウントマネージャーに連絡してください）。 ゲーム内でユーザーが見つからない。 *ユーザーアカウントの削除。
サブスクリプションがキャンセルされると、最終決済を返金することができます。このオプションは、販売者とユーザーの両方が使用できます。
Non renewing.サブスクリプション延長のキャンセル。サブスクリプションは、ステータスがCanceledに変わる前に現在の決済周期が終了するまで続きます。次のいずれかの理由により、延長をキャンセルすることができます。
- APIメソッドまたは、Xsolla Publisherアカウントから。 Eメールリンクを介してユーザーによってキャンセルされた。 ユーザーアカウントの削除。

統合ガイド

モジュールの統合:

Xsolla パブリッシャ―アカウントに登録する。
新しいプロジェクトの作成。
モジュールを設定する。
トークンの取得。
ストアインターフェースの開始の設定。
ウェブフック処理の設定。
支払処理のテスト。
モジュールを起動し、契約書に署名する。

統合には次のパラメータが必要です。

マーチャントID - パブリッシャ―アカウント URL に表示されます：https://publisher.xsolla.com/{merchant_id}/
API キー - パブリッシャ―アカウント > 設定 > 会社で生成されます。
プロジェクト ID - プロジェクト設定を表示した場合に、パブリッシャ―アカウント URL に表示されます:https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
プロジェクト秘密キー - プロジェクト設定で生成されます。

プロジェクトの作成

プロジェクトに移動し、新規プロジェクトの作成をクリックします。
設定モードで：
a.ウェブフック URL を指定する。
b.プロジェクトウェブフックに署名するための秘密キーを生成する。
c.サブスクリプションモジュールを有効にする。

モジュールの設定

サブスクリプションモジュール設定に移動し、新規プランの作成をクリックする。次のパラメータを指定してください： 名前。 決済周期。
作成をクリック。
プランリストに戻るをクリックして、基本モジュール設定に戻り、必要に応じて他のプランを作成。

重要！プランには1つの通貨のみを設定できます。プロジェクト通貨ごとに個別のプランセットを登録する必要があります。

ストアインターフェースのトークンの取得

ストアと統合するには、トークンを取得する必要があります。トークンは、ゲームやユーザーデータと支払設定を含む文字列です。 Xsolla APIは、基本的なHTTP認証を使用します。マーチャントIDをユーザー名、APIキーをパスワードとして指定します。

サンドボックスモードを有効にするには、 "mode" = "sandbox"に設定します。

トークンの取得はこの URL から：

https://api.xsolla.com/merchant/merchants/{merchant_id}/token

決済インターフェースに引き渡すパラメータを含めることによって、HTTP POSTリクエストを変更することができます。リクエストとレスポンスは両方ともJSON形式です。

PHPとXsolla PHP SDKを使用してトークンを取得する例を示します。別の言語を使用する場合は、CURLベースの例（CURLをクリック）をご参照ください。

PHP

CURL

<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);

    curl -v https://api.xsolla.com/merchant/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
        "user":{
            "id":{
                "value":"1234567"
            },
            "email":{
                "value":"email@example.com"
            }
        },
        "settings":{
            "project_id":14004,
            "mode":"sandbox"
        }
    }'

パラメータの完全なリストはAPI リファレンスでご参照ください。

ストアUIを開く

ストアの開き方：

Pay Station埋め込みクリプト、
新しいウィンドウ、または
iframeを使用してください。

サンドボックスモードでストアを開くには、次のURLを使用してください：https://sandbox-secure.xsolla.com/

Pay Station 埋め込み

Pay Station埋め込みスクリプトはデバイスの種類を判断し、ライトボックス（デスクトップ画面）または新しいウィンドウ（モバイル画面とタブレット画面）でストアインターフェースを開きます。非同期スクリプトの読み込みを使用することをお勧めします。

非同期ロードの例

 <script>
     var options = {
         access_token:'ACCESS_TOKEN'、// TODO 前のステップで受信したアクセストークンを使用する
         andbox：true // TODO 稼働時にこの設定を削除することを忘れないでください
     };
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
     s.addEventListener('load', function (e) {
         XPayStationWidget.init(options);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

<button data-xpaystation-widget-open>クレジットの購入</button>

パラメータの完全なリストはAPI リファレンスで参照できます。

新しいウィンドウ

新しいウィンドウで決済インターフェース開くには、次のリンクを使用してください：https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN、ACCESS_TOKENは、前のステップで取得したトークンです。

Iframe

iframeでストアのインターフェースを開くには、次のメカニズムを実装する必要があります。

デバイスタイプ（デスクトップまたはモバイル）を指定し、トークンのsettings.ui.versionパラメータ内で送信します;
postMessage経由で決済インターフェースからイベントを受け取ります。

ウェブフックの設定

Xsolla は以下のウェブフックをプロジェクトに送信します:

決済
サブスクリプションの作成
サブスクリプションの更新/延長
返金
サブスクリプションのキャンセル

メッセージ本体なしでHTTPコード204で応答することによってウェブフックの受信を確認します。ウェブフック処理の詳細と例については、APIリファレンスをご参照ください。

署名の作成

電子署名の作成：

Xsolla サーバーのリクエストで送信されたデータとプロジェクトの秘密キー（プロジェクト設定で生成されたもの）を連結します。
SHA1 アルゴリズムを使用してストリングをハッシュ化。
署名ヘッダーに署名を送信。

ウェブフックを取り扱う際、受信した署名が署名ヘッダーに設定されたものと一致することを確認します。

決済

Xsolla サーバーは、ユーザーが支払いを完了するたびに、支払いの詳細情報を含むウェブフックを送信します。

リクエストの例

PHP

CURL

$request = array(
    'notification_type' => 'payment',
    'purchase' => array(
        'virtual_items' => array(
            'items' => array(
                0 => array(
                    'sku' => 'test_item1',
                    'amount' => 1,
                    ),
                1 => array(
                    'sku' => 'test_item2',
                    'amount' => 1,
                    ),
                2 => array(
                    'sku' => 'test_item3',
                    'amount' => 1,
                    ),
            )
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
)

curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type": "payment",
    "purchase":{
        "virtual_items":{
            "items": [
                {
                    "sku": "test_item1",
                    "amount": 1
                },
                {
                    "sku": "test_item2",
                    "amount": 1
                },
                {
                    "sku": "test_item3",
                    "amount": 2
                },
            ]
        },
        "total":{
            "currency": "USD",
            "amount": 9.99
        }
    },
    "user":{
        "ip":"127.0.0.1",
        "phone":"18777976552",
        "email":"email@example.com",
        "id":"1234567",
        "country":"US"
    },
    "transaction":{
        "id": 87654321,
        "payment_date": "2014-09-23T19:25:25+04:00",
        "payment_method": 1380,
        "dry_run": 1
    },
    "payment_details":{
        "payment":{
            "currency": "USD",
            "amount": 9.99
        },
        "vat":{
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout":{
            "currency": "USD",
            "amount": 9.49
        },
        "xsolla_fee":{
            "currency": "USD",
            "amount": 0.19
        },
        "payment_method_fee":{
            "currency": "USD",
            "amount": 0.31
        }
    }
}'

パラメータの完全な一覧は、API リファレンスをご参照ください。

サブスクリプションの作成

Xsollaサーバーは、ユーザーがサブスクリプションを作成するたびにサブスクリプションの詳細を含むウェブフックを送信します。

PHP

CURL

<?php
$request = array(
    'notification_type' => 'create_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_next_charge' => '2015-01-22T19:25:25+04:00',
        'trial' =>  (
                'value' =>  90,
                'type' =>  'day'
            )
    )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"create_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_next_charge":"2015-01-22T19:25:25+04:00",
            "trial":{
                    "value": 90,
                    "type": "day"
                }
        }
    }'

パラメータの完全なリストはAPI リファレンスをご参照ください。

サブスクリプションの更新/延長

Xsollaサーバーは、ユーザーがサブスクリプションプランを変更したり、サブスクリプションを延長したり、次の請求日が変更されたりするたびにウェブフックを送信します。

リクエストの例

PHP

CURL

<?php
$request = array(
    'notification_type' => 'update_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_next_charge' => '2015-01-22T19:25:25+04:00'
    )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"update_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_next_charge":"2015-01-22T19:25:25+04:00"
        }
    }'

パラメータの完全なリストはAPI リファレンスをご参照ください。

返金

Xsolla サーバーは、ユーザーが支払いをキャンセルするたびに、支払いの詳細情報を含むウェブフックを送信します。

リクエストの例

PHP

CURL

$request = array(
    'notification_type' => 'refund',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => (
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
);

curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"refund",
    "purchase":{
        "virtual_currency":{
            "name": "Coins",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "date_create": "2014-09-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "total":{
            "currency":"USD",
            "amount":200
        }
    },
    "user":{
        "ip":"127.0.0.1",
        "phone":"18777976552",
        "email":"email@example.com",
        "id":"1234567",
        "name": "Xsolla User",
        "country":"US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":1,
        "reason":"Fraud"
    },
    "payment_details":{
        "xsolla_fee":{
            "currency":"USD",
            "amount":"10"
        },
        "payout":{
            "currency":"USD",
            "amount":"200"
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":"20"
        },
        "payment":{
            "currency":"USD",
           "amount":"230"
        }
    }
}'

パラメータの完全なリストは、API リファレンスで参照してください。

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

Xsollaサーバーは、サブスクリプションがキャンセルされるたびにウェブフックを送信します。

リクエストの例

PHP

CURL

<?php
$request = array(
    'notification_type' => 'cancel_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_end' => '2015-01-22T19:25:25+04:00',
    )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"cancel_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_end":"2015-01-22T19:25:25+04:00"
        }
    }'

パラメータの完全なリストはAPI リファレンスをご参照ください。

ウェブフックのテスト

ウェブフックハンドラーのテスト:

モジュールの設定をパブリッシャ―アカウントで開きます。
テスト タブに移動します。
テストデータを入力してテストをクリック。Xsolla サーバーは送信可能なウェブフックをすべて送信。
有効なリクエストの場合にはテストには緑の印が付き、エラーの場合には赤の印が付く。

支払処理のテスト

Xsolla サンドボックスは独立した環境で、実際の決済を除くライブ環境のすべての機能をサポートします。サンドボックスにアクセスするには、トークンを取得する際に"mode" ="sandbox"を送信します。

銀行カードでの決済のテスト:

サンドボックスモードでストアを開く。
購入するアイテムを選択。
クレジットカード/デビットカードをクリック。
下記の表から銀行カードの詳細を入力。その他のフィールドに任意の値を入力。正しくない情報（カード番号、有効期限、CVV等）を入力して、エラーを生成することもできます。

テスト用の銀行カードの一覧

重要！ サンドボックスの銀行カード決済はUSD、EUR、RUB、GBPでのみ実行可能です。

モジュールの起動

テスト成功後にモジュールを起動するには、アカウントで設定を開き、起動タブに移動してオンをクリックします。

重要！ 支払いを受け取る前に、以下を行ってください:

"sandbox"モードを削除する。
契約に署名します。

追加機能

ゲーム内のパラメータを使用する詐欺行為の防止方法

トークンで渡されたcustom_parametersオブジェクトを使用して、ユーザーのゲーム内データを送信し、疑わしいアクティビティを検出することができます。例えば、ゲームに少ししか時間を費やしていないのに高レベルに達しているプレイヤーは、盗まれた銀行カードを使用してキャラクターをレベルアップした後にそれを販売するためにアカウントを作成した詐欺師という可能性があります。

利用可能なパラメータの一覧

アカウントマネージャーに、渡す予定のパラメータと、それぞれのパラメータのトリガー値を知らせてください。この情報を使用して不正防止フィルタを設定します。

選択したメソッドを使用して支払う

ストアを開くと、settings.payment_methodパラメータで支払方法IDを送信することができます。この場合、ユーザーは直ちに、選択した支払方法の支払フォームにリダイレクトされます。

リクエストの例

CURL

    curl -v https://api.xsolla.com/merchant/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
        "user":{
            "id":{
                "value":"1234567"
            },
        },
        "settings":{
            "project_id":14004,
            "payment_method": 24
        }
    }'

決済方法IDの一覧は、パブリッシャーアカウント> 決済システムまたは決済システムの一覧表示APIメソッドを使用して取得できます。

選択したプランの購入

ストアを開くと、purchase.subscription.plan_idパラメータで支払方法IDを送信することができます。この場合、ユーザーはすぐに決済インターフェースにリダイレクトされます。

リクエストの例

CURL

    curl -v https://api.xsolla.com/merchant/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
        "user":{
            "id":{
                "value":"1234567"
            },
        },
        "settings":{
            "project_id": 14004
        },
        "purchase": {
            "subscription": {
                "plan_id": 123
                },
        }
    }'

サブスクリプションがキャンセルされた場合の最終決済のキャンセル

サブスクリプションをキャンセルするときに、最後の決済ををキャンセルすることもできます。これを行うには、サブスクリプションの更新メソッドのcancel_subscription_paymentパラメーターを使用します。サブスクリプションがキャンセル場合、ユーザーが最終決済の返金を選択できるように設定できます。この機能を有効にするには、アカウントマネージャーに連絡してください。

プランの変更

サブスクリプションプランを更新するには、プランの更新メソッドを使用します。新しいプランは、次の期間から開始されます。

次の場合にはプランを変更することはできません。

ユーザーがこのプランで有効なサブスクリプションを持ってる場合、
サブスクリプションのステータスがCanceledまたはNon renewingの場合、
プランが体験版の場合。

プランの変更が失敗した場合、サブスクリプションはキャンセルされます。

サブスクリプション

ユーザーフロー

パートナーフロー

サブスクリプションのステータス

統合ガイド

プロジェクトの作成

モジュールの設定

ストアインターフェースのトークンの取得

ストアUIを開く

Pay Station 埋め込み

新しいウィンドウ

Iframe

ウェブフックの設定

署名の作成

決済

サブスクリプションの作成

サブスクリプションの更新/延長

返金

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

ウェブフックのテスト

支払処理のテスト

モジュールの起動

追加機能

ゲーム内のパラメータを使用する詐欺行為の防止方法

選択したメソッドを使用して支払う

選択したプランの購入

サブスクリプションがキャンセルされた場合の最終決済のキャンセル

プランの変更

サブスクリプションの手動更新

製品の使用

報酬