The following documentation was deprecated. Current version is available at developers.xsolla.com

Pay2Play

Pay2Playモジュールにより、ゲーム開発者はゲームのウェブサイトから直接PINコードを販売することができます。ユーザーはPay2Playウィジェットを使用してストアにアクセスできます。このモジュールにはさまざまな統合オプションがあり、開発者は以下を行うことができます。 様々なDRMプラットフォームの選択、 様々なDRMプラットフォームへの異なる価格の設定、 ウィジェットのサイズと色のテーマの設定、および 開発者へのチップの支払い

統合オプション

モジュールは、高度モードまたは基本モードのいずれかで統合できます。

基本的な統合

基本的な統合:

  • 実装が迅速で、
  • トークンの生成やサーバーの実装が不要で、
  • ユーザーの事前承認を必要としないゲームにも適しています。

高度な統合

高度な統合:

  • ゲーム側でさらにリンクするためにユーザーと購入データを安全に転送することができ、
  • サーバー側の実装が必要です。

基本的な統合方法

基本統合の実装方法:

  1. Xsolla パブリッシャ―アカウントに登録する。
  2. プロジェクトの作成
  3. モジュールの設定
  4. 支払処理のテスト
  5. Pay2Playウィジェットをゲームページに追加。
  6. 契約書に署名してください。

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

  • プロジェクト ID - プロジェクト設定を表示した場合に、パブリッシャ―アカウント URL に表示されます:https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.

プロジェクトの作成

  1. プロジェクトに移動し、新規プロジェクトの作成をクリックします
  2. 設定モードで:
    ウェブフックオフにする。 サーバーレス統合オンにする。 Pay2Play モジュールをオンにする。

モジュールの設定

  1. Pay2Playモジュールの設定に進み、ゲーム用に以下のパラメータを設定します: *名前。
    • 説明文。 動作環境。 SKU - 固有識別子。
    • 発売日。 *画像。
    • DRMプラットフォーム *選択されたDRMプラットフォームのオペレーティングシステムやゲームコンソールのバージョン。
  2. 次へをクリックする。
  3. 選択された DRM プラットフォームの価格を設定する。次へをクリックする。
  4. アップロードされたコードオンにする。
  5. 選択したDRMプラットフォームのPINコードをアップロードする。

支払処理のテスト

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

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

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

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

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

Pay2Play ウィジェットの統合

Pay2Play ウィジェット はストアをライトボックス (デスクトップ画面) または新しいウィンドウに開きます (モバイルまたはタブレットの画面で)。ウィジェットは自動でデバイスの種類を判断します。 ウィジェットコードを取得するには、パブリッシャ―アカウントでモジュール設定を開き、パブリッシュタブに移動します。希望するウィジェットのコードをコピーしてゲームのウェブサイトに追加します。非同期読み込みの使用をお勧めします。

非同期ロードの例

HTML
 <script>
     var access_data = {"settings":{"project_id":14004},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
     var target_element = "#widget-example-element";
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
     s.addEventListener('load', function (e) {
         var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

ウィジェットの初期化パラメータの完全な一覧は、API レファレンスおよびGitHubのインストール手順をご参照ください。

高度な統合ガイド

高度な統合の実装方法:

  1. Xsolla パブリッシャ―アカウントに登録する。
  2. プロジェクトの作成
  3. モジュールの設定
  4. トークンの取得
  5. ウェブフック処理の設定。
  6. 支払処理のテスト
  7. Pay2Playウィジェットをゲームページに追加し、契約書に署名します。

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

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

プロジェクトの作成

  1. プロジェクトに移動し、新規プロジェクトの作成をクリックします
  2. プロジェクト設定で次の操作を行います: ウェブフックオンにする。 ウェブフック URL を指定する。 プロジェクトウェブフックに署名するための秘密キーを生成する。 サーバーレス統合オフにします。 Pay2Play モジュールをオンにする。

モジュールの設定

  1. Pay2Playモジュールの設定に進み、ゲーム用に以下のパラメータを設定します: *名前。
    • 説明文。 動作環境。 SKU - 固有識別子。
    • 発売日。 *画像。
    • DRMプラットフォーム *選択されたDRMプラットフォームのオペレーティングシステムやゲームコンソールのバージョン。
  2. 次へをクリックする。
  3. 選択された DRM プラットフォームの価格を設定する。次へをクリックする。
  4. アップロードされたコードオンにする。
  5. 選択したDRMプラットフォームのPINコードをアップロードする。

ストアトークンの取得

ストアと統合するには、トークンを取得する必要があります。 トークンは、ゲームやユーザーデータと支払設定を含む文字列です。 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 リファレンスでご参照ください。

ウェブフックの設定

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

  • ユーザー認証
  • 決済
  • 返金

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

署名の作成

電子署名の作成:

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

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

ユーザー認証

Xsolla サーバーはプロジェクトのウェブフック URL にリクエストを送信して、ユーザーがゲーム内に存在することを確認します。

リクエストの例

PHP
CURL
$request = array(
    'notification_type' => 'user_validation',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization:Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"user_validation",
    "user":{
        "ip":"127.0.0.1",
        "phone":"18777976552",
        "email":"email@example.com",
        "id":"1234567",
        "country":"US"
    }
}'

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

決済

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
$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 リファレンスをご参照ください。

ウェブフックのテスト

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

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

支払い処理のテスト

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

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

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

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

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

Pay2Play ウィジェットの統合

Pay2Play ウィジェット はストアをライトボックス (デスクトップ画面) または新しいウィンドウに開きます (モバイルまたはタブレットの画面で)。ウィジェットは自動でデバイスの種類を判断します。 ウィジェットコードを取得するには、パブリッシャ―アカウントでモジュール設定を開き、パブリッシュタブに移動します。希望するウィジェットのコードをコピーしてゲームのウェブサイトに追加します。非同期読み込みの使用をお勧めします。

非同期ロードの例

HTML
 <script>
     var access_data = {"settings":{"project_id":14004},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
     var target_element = "#widget-example-element";
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
     s.addEventListener('load', function (e) {
         var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

ウィジェットの初期化パラメータの完全な一覧は、API レファレンスおよびGitHubのインストール手順をご参照ください。

開発者へのチップ

購入ごとにプロジェクトにチップが提供されます。オプションを有効にするには、Pay2Play価格設定を開き、Pay2Playウィジェットでのチップの使用オンに設定して下さい。追加する通貨ごとに、事前定義されたチップ金額3つが利用可能です。

ユーザーはストアに入る前に、提供するチップの金額を選択できます。チップの金額は購入金額に追加されます。

APIを利用したPINコードの配信

PINコードの一覧をファイルにアップロードする代わりに、購入後に毎回PINコードを送信することができます。機能の有効化:

  • PINコードの取得ウェブフックの実装。
  • Pay2Playの設定で、コードのアップロードに進み、オンデマンドオンに、アップロードしたコードオフに設定してください。

PINコード販売の制限

プロジェクトで販売できるPINコードの数を制限することができます。2種類のEメール通知が送信されます: PINコードの残数が100個以下の場合または残数がほとんどない場合と全くない場合の2つです。制限を超えると、ユーザーは支払いを行うことができなくなります。

地域別の販売制限

Pay2Playモジュールでは、PINコードの販売に関する地域制限を設定できます。特に以下を実行できます:

  • 国ごとまたはグループ化した複数の国に異なる価格を設定する。
  • 特定の国への販売を禁止する。

プロジェクトを正しく設定すると、制限された国でPINコードを購入しようとするユーザーに、対応する警告が表示されます。PINコードの販売が禁止されている国では、支払いができません。

この機能を有効にするには、担当のアカウントマネージャーまでお問合せください。地域限定の対象となるプラットフォームごとに、次の情報が必要になります。

  • 制限の種類: 有効化:PIN コードは特定の国でのみ有効化できる。 起動:PINコードはどの国でも有効にできますが、ゲームは特定の国でのみ起動することができます。 *有効化と起動:PINコードを有効にして、特定の国でのみゲームを起動することができます。
  • PINコードの価格が異なる国グループの一覧。
  • 国グループの設定: グループ名。 SKU - グループ固有の識別子。 様々な通貨での価格一覧。モジュール設定で設定されている既定の通貨で価格を含めるようにしてください。 各グループに含まれる国の一覧。
  • PINコードが無効になっている国の一覧(存在する場合)。

どのプラットフォームでも、特定の国を異なる価格のグループまたはプレオーダー無効のグループのいずれかに含めることができます。国がいずれのグループにも含まれていない場合、PINコードはモジュール設定で既定設定された価格で制限なく販売されます。

重要! PINコードの有効化とゲームの起動がDRMプラットフォーム側で行われている場合は、リリース日に地域制限が設定されたPINコードをアップロードしてください。