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

トークン化

トークン化とは、決済インターフェースを開くことなく、ユーザーの関与もなく、安全に決済を処理できる一連のAPIメソッドを指します。このモジュールでは、

  • 保存された決済アカウントの一覧を取得し、
  • 保存された決済アカウントを使用して決済を行い、
  • 決済アカウントを削除することができます。

トークン化は、次の決済方法でサポートされています。

  • クレジットカード
  • PayPal
  • Amazon
  • Skrill
  • Yandex
  • Webmoney
  • Qiwi
  • Liqpay Privat Bank

統合ガイド

ユーザーは、Pay Stationインターフェース経由で最初の決済を行わなければなりません。決済が完了すると、Playstationはトークン(保存された決済アカウントID)を生成し使用することができます。ユーザーを関与させることも、インターフェースを開くこともありません。

モジュールの統合:

  1. Xsolla パブリッシャ―アカウントに登録する。
  2. 新しいプロジェクトの作成
  3. トークンの取得
  4. 決済インターフェースの開始を設定する。
  5. ウェブフック処理を設定する。
  6. 支払い処理をテストする。
  7. モジュールを起動し、契約書に署名する。
  8. 保存されたアカウントに関連するプロセスを実装する。

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

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

プロジェクトの作成

  1. プロジェクトに移動し、新規プロジェクトの作成をクリックします
  2. 設定モードで:
    a.ウェブフック URL を指定する。
    b.プロジェクトウェブフックに署名するための秘密キーを生成する。
    c.Payment Wallモジュールをオンにする。

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

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

決済インターフェースを開く

決済インターフェースの開き方: *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 は以下のウェブフックをプロジェクトに送信します: ユーザー認証 決済 *返金

メッセージ本体なしで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. 下記の表から銀行カードの詳細を入力。その他のフィールドに任意の値を入力。正しくない情報(カード番号、有効期限、CVV等)を入力して、エラーを生成することもできます。

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

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

モジュールの起動

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

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

  1. "sandbox"モードを削除する。
  2. 契約書に署名してください。

決済アカウントでの作業方法

ユーザーが決済インターフェイスを使用して初めて決済を行った後、決済アカウントが保存され、ユーザーの関与やインターフェースを開くことなく、その後の決済を行うことができます。

保存された決済アカウントの一覧の取得

リクエストの例

CURL
curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payment_accounts' \
-X GET \
-u merchant_id:merchant_api_key

レスポンスの例

CURL
[
    {
        "type": "card",
        "id": 1,
        "name": "411111******1111",
        "payment_system":{
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]

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

保存された決済アカウントを使用した決済

リクエストの例

CURL
$ curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user":{
        "ip":"127.0.0.1",
        "name": "John Smith"
    },
    "purchase":{
        "virtual_currency":{
            "quantity": 100
        },
        "description":{
            "value": "Test Purchase"
        }
    },
    "settings":{
        "mode":"sandbox"
    }
}'

レスポンスの例

<div class = "content-code">
    <div class="language-switcher">
        <div class="languages">
                <div class="lang" data-lang="shell">CURL</div>
            </div>
    </div>

```shell
{
    "transaction_id": 119478390
}

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

保存された決済アカウントの削除

リクエストの例

CURL
$ curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

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