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

プレオーダー

プレオーダーは Xsolla Pay2Play に基づくソリューションで、ゲーム制作会社が公式リリース前にゲームを発売できるようにするものです。ユーザーがゲームをプレオーダーすると、購入を確認する固有番号が送付されます。ゲームがリリースされると、自動的にPINコードをユーザーに送付し、ユーザーがゲームにアクセスできるようにします。

プロジェクトの作成

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

モジュールの設定

  1. Pay2Play 設定に移動し、以下のパラメータを設定します:
    a.ゲーム名。
    b.ゲームの内容。
    c.システム要件。
    d.SKU — 固有識別子。
    e.リリース日。
    f.画像。
    g.DRM プラットフォーム。
    h.選択された DRM プラットフォームでサポートされるオペレーティングシステム/ゲームコンソールのバージョン。
  2. 次へをクリックする。
  3. 選択された DRM プラットフォームの価格を設定する。

Pay2Play ウィジェットの統合

Pay2Play ウィジェット はストアをライトボックス (デスクトップ画面) または新しいウィンドウに開きます (モバイルまたはタブレットの画面で)。ウィジェットは自動でデバイスの種類を判断します。

ウィジェットコードを取得するには、パブリッシャ―アカウントでモジュール設定を開き、パブリッシュタブに移動します。希望するウィジェットのコードをコピーしてゲームのウェブサイトに追加します。非同期読み込みの使用をお勧めします。

非同期のスクリプト読み込みの例:

 <script>
 var access_data = {"settings":{"project_id":14004,"mode":"sandbox"},"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をご参照ください。

重要! 支払いを受け取る前に、契約に署名する必要があります。

支払い処理のテスト

Xsolla サンドボックスは独立した環境で、実際の決済を除くライブ環境のすべての機能をサポートします。"settings.mode" = "sandbox" をオブジェクト内で access_data 送信することで、サンドボックスにアクセスできます。access_data の JSON 構造やパラメータはトークン リクエストと同じです。

銀行カードでの支払いのテスト:

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

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

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

PIN コードのアップロード

ゲームのリリース後に、Pay2Play モジュール設定を開き、選択された DRM プラットフォームのための PIN コードをコードのアップロードタブでアップロードします。

認証されたユーザーの決済を行う

既存のゲームアカウントのあるユーザーには、認証取引を行うためにユーザー情報を送信することができます。機能の有効化:

  1. プロジェクトを設定する。
  2. トークンを取得する。
  3. ウェブフックハンドリングを設定する。

以下のパラメータが必要となります:

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

プロジェクトの設定

プロジェクトの設定:

  1. ウェブフックオンにする。
  2. ウェブフック URL を指定する。
  3. プロジェクトウェブフックに署名するための秘密キーを生成する。
  4. サーバーレス統合オフにする。

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

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

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

ウェブフックの設定

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

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

ウェブフック通知を問題なく受信したことを確認するには、サーバは本文なしで204 HTTPステータスコードを返す必要があります。サンプルを使用したウェブフックメカニズムの詳細については、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. 有効なリクエストの場合にはテストには緑の印が付き、エラーの場合には赤の印が付く。

開発者へのチップ

購入のごとにプロジェクトにチップが提供されます。この機能を有効にするには、モジュールを開き、料金タブで、Pay2play ウィジェットでチップの使用オンにします。有効な通貨ごとにチップの金額オプションが3つ利用できます。

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

プレオーダー数の限定

すべてのプロジェクトでプレオーダーの数を制限することができます。100件以下のプレオーダーが残っている場合、およびプレオーダーが残っていない場合に、次のEメール通知が届きます。ユーザーがプレオーダー制限を超過する場合、支払いは処理されません。

販売の地域制限

プレオーダーのモジュールでは、プレオーダーの販売に関する地域制限を設定することができます。特に以下を実行できます:

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

プロジェクトが適切に設定されると、制限対象国のユーザーがプレオーダーしようとすると、警告文が表示されます。プレオーダーが禁止された国では、決済は処理されません。

この機能を有効にするには、担当のアカウントマネージャーまでお問合せください。地域制限が適用される各プラットフォームの以下の情報が必要です:

  • 制限の種類: 有効化:PIN コードは特定の国でのみ有効化できる。 発売開始:どの国でも PIN コードは有効化できるけれど、特定の国のみでゲームの発売を開始できる。 *有効化と発売開始:特定の国でのみ PIN コードを有効化し、ゲームを発売開始できる。
  • プレオーダー価格が異なる国グループの一覧。
  • 国のグループの設定: グループ名。 SKU - グループ固有の識別子。 様々な通貨での価格一覧。モジュール設定に規定されている、既定の通貨での価格を必ず含める。 各グループに含まれる国の一覧。
  • プレオーダーが無効な国の一覧(存在する場合)。

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

重要! PIN コードの有効化およびゲームの開始があなた、またはプラットフォームにより実行される場合には、必ず、当社のシステムに PIN コードと地域制限をアップロードするようにしてください。