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

ユーザー生成コンテンツ

ユーザー生成コンテンツ(UGC)モジュールは、ゲーマーによって作成されたゲーム内コンテンツを販売できるゲーム用に設計されていますこのスキームには次のユーザーが必要です:

  • コンテンツ制作者 - コンテンツを作成し、価格を設定してゲームにコンテンツを提供するユーザー
  • ゲーム - コンテンツ管理サービス(コンテンツ作成者のダッシュボード)を提供し、ユーザーからのコンテンツを受け入れる
  • マーケットプレイス - コンテンツストア
  • 顧客 -マーケットプレイスでコンテンツを購入してゲームで使用できるユーザー

統合ガイド

モジュールの統合:

  1. Xsolla パブリッシャ―アカウントに登録する。
  2. プロジェクトの作成
  3. コンテンツ制作者のダッシュボードを構築するためにAPIを統合する。
  4. マーケットプレイスを構築するためにAPIを統合する。
  5. ストアインターフェースを設定する。
  6. ウェブフックハンドリングの設定
  7. 決済処理をテストする。
  8. モジュールを起動し、契約書に署名する。

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

  • 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. プロジェクト設定で次の操作を行います:
    a.プロジェクトウェブフックに署名するための秘密鍵を生成する。
    b.仮想アイテムモジュールを有効にする。

コンテンツ制作者のダッシュボードを作成する

インターフェースには次のページが含まれています:

  1. 登録とログイン
  2. 契約書- 契約に署名用のページ 
  3. アセット申請 - コンテンツ制作用のページ 
  4. 承認 - コンテンツ承認用のページ 
  5. トランザクション - トランザクション一覧を含むページ 
  6. 税務調査 - 配当を受け取るために納税申告用紙に記入するためのページ 
  7. 銀行口座 - 配当を受け取るために必要な情報 
  8. 配当 - 配当の一覧

登録とログイン

登録とログインにXsolla Lログインを使用することをお勧めします。実装の詳細については、Xsolla ログイン統合ガイドを参照してください。

登録成功後に、Xsolla システムにコンテンツ制作者レコードを作成してください。これを行うには、開発者の作成法人エンティティAPIメソッドの作成を使用してください。

すべてのコンテンツ制作者が契約書に署名する必要があります。契約書ページを開くには、APIメソッド「契約書へのリンクを取得する」を使用してください。リンクは、iframeまたは新しいウィンドウで契約書ページを開くために使用されます。

### アセット申請

コンテンツ制作者が新しいUGCをアップロードする際には、Xsollaシステムで作成し、仮想アイテムの作成メソッドを使用してファイルをアップロードしてください。

コンテンツ用のファイルをアップロードするリクエスト

$ curl -v 'https://api.xsolla.com/merchant/merchants/project/{project_id}/virtual_items/items/{item_id}/files' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: image/png' \
-H 'Accept: application/json' \
-d '[image data]

承認

承認後、ユーザーが作成したコンテンツはコンテンツストアに表示されます。アイテムを表示するには、JSON本体で "enabled"をtrueに設定して仮想アイテムの更新メソッドを呼び出します。

トランザクション

コンテンツ制作者は、自分のコンテンツに対して行われたすべてのトランザクションを確認する必要があります。トランザクションの一覧表示メソッドを使用して、トランザクションの一覧を取得できます。これにより、トランザクションの詳細な一覧が返されます。

税務調査

各コンテンツ制作者は、配当を受けるために税務情報を税務関係書類に入力する必要があります。税務調査のページへのリンクにアクセスするには、税務申告フォームへのリンクを取得するを使用してください。リンクは、iframeまたは新しいウィンドウで税務調査ページを開くために使用されます。

銀行口座

コンテンツ制作者の銀行口座の詳細を用意してください。Xsollaは銀行口座へ配当を支払います。情報をXsollaシステムに追加するには、支払方法の作成メソッドを使用してください。

配当

このページでは、コンテンツ制作者用に配当が一覧表示されます。配当の一覧を取得するには、[配当の一覧表示]メソッドを使用してください。 配当は、legal_entity_idまたはステータスでフィルタリングできます。 配当のステータスは次の通りです:

  • 保留 - 配当リクエスト待ち
  • 準備完了 - 配当待ち
  • 支払済み - 配当の成功 

Status="Hold"の配当はすべて、リクエストによって支払うことができます

$ curl -v 'https://api.xsolla.com/merchant/merchants/{merchant_id}/legal_entities/{legal_entity_id}/transfers/payout' \
-X POST \
-u merchant_id:merchant_api_key
-d '{
        "draft_ids": [ 23, 45, 34]
 }
'

マーケットプレイスの作成

ストアには次のページが含まれています:

  1. マーケットプレイス- ユーザーが生成したすべてのコンテンツが一覧表示。
  2. チェックアウト- コンテンツの詳細情報を表示。ユーザーが支払いを確認できる。

マーケットプレイス

マーケットプレイスには、購入可能なすべてのアイテムまたは商品が表示されます。アイテムの一覧を取得するには、[仮想アイテムの一覧表示]メソッドを使用してください。

チェックアウト

チェックアウトページには、ユーザー用にアイテムに関する詳細情報が表示されます。この情報を取得するには、[仮想アイテムの取得]メソッドを使用してください。

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

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

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_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. クレジット/デビットカードをクリック。
  4. 銀行カードの詳細と残りのフィールドに値を入力。正しくない情報(カード番号、有効期限、CVV等)を入力して、エラーを生成することもできます。

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

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

モジュールの起動

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

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

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