日替わり報酬

プレミアムサブスクリプションを購入したユーザーには、日毎の報酬が発行されます。各プレミアムサブスクリプションには独自の報酬が設定されています。

ユーザーフロー

パートナーフロー

統合ガイド

モジュールの統合:

Xsolla パブリッシャ―アカウントに登録する。
プロジェクトを作成する。
モジュールを設定する。
プレミアムサブスクリプション用に報酬を設定する。
トークンを取得する。
ストアインターフェースのオープンを設定する。
ウェブフックハンドリングを設定する。
支払い処理をテストする。
モジュールを起動し、契約書に署名する。

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

Merchant ID - パブリッシャ―アカウントのURLに表示されます:https://publisher.xsolla.com/{merchant_id}/
API Key — Publisher Account > Settings > Companyで生成されます。
Project ID - プロジェクト設定を表示した場合に、パブリッシャ―アカウント URL に表示されます:https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
Project secret key — プロジェクト設定で生成されます。

このガイドでは、モジュールのクイックスタートに必要な最小限の設定について説明します。パラメータの完全なリストはAPI リファレンスをご参照ください。ご不明な点がございましたら、アカウントマネージャーまでご連絡ください。

プロジェクトの作成

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

モジュールの設定

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

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

プレミアムプランの報酬の設定

次の報酬をプレミアムプランに追加することができます：

ゲームストア内の仮想アイテムとゲーム内通貨パッケージの個別割引。
定期的にもらえるゲーム内通貨。
定期的にもらえる仮想アイテム。ユーザーは以下を受け取ることができます： リストからのランダムなアイテム、アイテムの範囲、プロジェクト設定でそれらを取得する確率など。 特定のアイテム（プロジェクト設定で指定された順序）。

重要！選択した報酬に応じて、仮想アイテムまたは仮想通貨モジュールをさらに設定する必要があります。

報酬を設定するには、リクエストをintegration@xsolla.comまでお送りください。

トークンを取得してストアを開く

ストアインターフェースをゲームに統合するには、アクセストークンが必要です。アクセストークンは、ゲーム、ユーザー、および購入パラメータを識別する文字列です。

Xsolla APIはHTTP基本認証を使用します。Merchant IDを基本認証ユーザー名として、APIキーをパスワードとして入力します。

決済処理をテストするには、値を"mode":"sandbox"に設定します。

トークンエンドポイントURL:

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

HTTP POSTリクエストでは、ストアインターフェースにパラメータを使用できます。リクエストとレスポンスのペイロードはJSON形式です。

リクエストの例

以下は、Xsolla PHP SDKを使用してPHPでトークンを取得する方法のサンプルコードです。別のプログラミング言語を使用している場合は、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リファレンスを参照してください。

ストアインターフェースを開く

ストアを開く3つの方法：

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 は以下のウェブフックをプロジェクトに送信します:

決済
サブスクリプションの作成
インベントリコンテンツの変更
サブスクリプションの更新/延長
返金
サブスクリプションのキャンセル

ウェブフック通知を問題なく受信したことを確認するには、サーバは本文なしで204 HTTPステータスコードを返す必要があります。サンプルを使用したウェブフックメカニズムの詳細については、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サーバーは、ユーザーのインベントリが変更されたとき（アイテムが追加または削除されたとき）に、Webサーバーをプロジェクトサーバーに送信します。

リクエストの例

PHP

CURL

$request = array(
     'virtual_currency_balance' => (
             'old_value' => '0',
             'new_value' => '200',
             'diff' => '200'
 ),
     'user' => (
         'name' => 'Xsolla User',
         'id' => '1234567',
         'email' => 'email@example.com'
 ),
     'operation_type' => 'inGamePurchase',
     'notification_type' => 'user_balance_operation',
     'items_operation_type' =>  'add',
          'items' =>  array(
              'sku' =>  '1468',
              'amount' =>  '2'
 ),
     'id_operation' => '66989'
);

curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
     "virtual_currency_balance":{
         "old_value":"0",
         "new_value":"200",
         "diff":"200"
 },
     "user":{
         "name":"Xsolla User",
         "id":"1234567",
         "email":"semail@example.com
 },
     "operation_type":"inGamePurchase",
     "notification_type":"user_balance_operation",
     "items_operation_type": "add",
          "items": [{
          "sku": "1468",
          "amount": "2"
          }],
     "id_operation":"66989"
}'

パラメータの完全なリストは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でのみ実行可能です。

モジュールの起動

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

重要！　実際の支払いを受け入れる前に、次を行う必要があります：

"mode" = "sandbox"の削除。
契約に署名します。