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

物品

物品は、ゲーム開発者がゲーム関連用品を売ることを可能にする仮想アイテムモジュールに基づく解決策です。ストアは、Xsolla APIに基づいてゲーム側で作成されます。Xsollaは決済インターフェースを提供し、エンドユーザーへの配送を可能にします。

統合ガイド

モジュールの統合:

  1. Xsolla パブリッシャ―アカウントに登録する。
  2. プロジェクトの作成
  3. モジュールを設定する
  4. 物品の管理を実装する。
  5. 配送サービスを有効にする
  6. トークンを取得する
  7. 決済インターフェースのオープンを設定する。
  8. ウェブフックハンドリングを設定する。
  9. 支払い処理をテストする
  10. モジュールを起動し、契約書に署名する

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

  • 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 を指定する。 プロジェクトウェブフックに署名するための秘密鍵を生成する。 仮想アイテムをオンにする。 ユーザーに移動し、Xsollaのストアユーザーのデータオンに設定する。

モジュールの設定

  1. 仮想アイテムモジュールの設定に移動し、アイテムのグループを作成をクリック。グループの設定。 カタログ内の場所(既定ではルートフォルダー)。 コード。 名前と説明文。 グループをストアに表示する場合は、ストアで表示を確認する。
  2. 作成をクリック。
  3. 基本モジュールの設定に戻り、必要に応じてカタログに他のグループを作成するには、アイテムリストをクリックする。
  4. アイテムの作成をクリックし、そのパラメータを指定する。 アイテムが属するグループの数(1つまたは複数)。グループが選択されていない場合、アイテムはストアに表示されません。 SKU - 固有識別子。 名前と短い説明文。 現金通貨での価格。 *画像。
  5. 物品オンに設定する。
  6. 作成をクリック。
  7. 基本モジュール設定に戻り、必要に応じて他の項目を作成するには、アイテムリストをクリックする。

物品の管理

物品の管理方法:

  1. ストアフロント仮想アイテムの一覧表示 APIメソッドを使用してマーケットプレイスの製品リストの取得を実装します。
  2. インベントリステータスの取得APIメソッドを使用してインベントリチェックを実装します。
  3. トークンを取得して決済インターフェースを開く。

配送サービスの有効化

利用可能な配送サービスのリストは、各パートナーごとに個別に説明されています。詳細については、フルフィルメントプラットフォームのリストとそのIDをアカウントマネージャーに送信してください。

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

決済インターフェースをゲームに統合するには、アクセストークンが必要です。アクセストークンは、ゲーム、ユーザー、および購入パラメータを識別する文字列です。 Xsolla APIはHTTP基本認証を使用します。Merchant IDを基本認証ユーザー名として、APIキーをパスワードとして入力します。

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

トークンエンドポイントの取得:

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_TOKENACCESS_TOKEN前のステップで取得したトークンです。

Iframe

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

  • デバイスタイプ(デスクトップ対モバイル)を指定し、トークンのsettings.ui.versionパラメータ内で送信;
  • postMessage経由で決済インターフェースからイベントを受け取る。

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

ウェブフックの設定

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. 有効なリクエストの場合にはテストには緑の印が付き、エラーの場合には赤の印が付く。

支払い処理のテスト

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

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

  1. サンドボックスモードで決済インターフェースを開く。
  2. クレジット/デビットカードをクリック。
  3. 銀行カードの詳細と残りのフィールドに値を入力。正しくない情報(カード番号、有効期限、CVV等)を入力して、エラーを生成することもできます。

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

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

モジュールの起動

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

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

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