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

用户生成的内容

用户生成的内容 (UGC) 模块服务于能够销售游戏玩家创建的游戏内容的游戏。该方案涉及以下参与者:

  • 内容创建者 - 其创建内容、设定价格和向游戏提供内容
  • 游戏 - 提供内容管理服务 (内容创建者的仪表盘), 接受来自用户的内容
  • 市场 - 内容商店
  • 客户 - 在市场上购买内容并可以在游戏中使用的用户

集成指南

若要集成模块,请执行以下操作: 注册 Xsolla 发布商账户

  1. 创建项目
  2. 集成用于建立内容创建者仪表盘的API
  3. 集成用于建立市场的API
  4. 设置 商店UI.
  5. 设置webhook处理
  6. 测试 支付流程。
  7. 发布 模块和签署协议。

集成需要下列参数:

  • 商户ID — 显示在发布商账户URL中:https://publisher.xsolla.com/{merchant_id}/.
  • API 秘钥 — 在 发布商账户 > 设置 > 公司中生成。
  • 项目ID — 查看项目设置时将显示在发布商帐户URL中:https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
  • 项目秘钥 — 在项目设置中生成。

创建项目

  1. 转到项目,然后单击创建新项目
  2. 在项目设置中:
    a.生成用来签名项目webhook的秘钥。
    b.启用 虚拟道具 模块。

建立内容创建者仪表盘

界面应该包含以下页面:

  1. 注册和登录
  2. 法律协议 - 用于签署协议的页面
  3. 资产提交 - 用于内容创建的页面
  4. 批准 - 用于内容批准的页面
  5. 交易 - 交易列表页面
  6. 税务约谈 - 填写税单接收付款的页面
  7. 银行账号 - 接收付款所需的信息
  8. 付款 - 付款列表

注册和登录

我们推荐使用Xsolla Login来注册和登录。请参阅 Xsolla Login 集成指南 了解实施详情。

注册成功后,您应该在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状态筛选付款。 付款状态应该为:

  • 保留 - 等待付款请求
  • 就绪 - 等待付款
  • 已付款 - 成功付款

所有 状态="保留" 的付款可以请求支付。

$ 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. 结算 - 这会显示内容的详细信息,并让用户可以确认付款。

市场

市场将显示所有可供购买的道具或产品。要获得道具列表,请使用方法 获取道具列表

结算

结算页面为用户提供道具的详细信息。要获得该信息,请使用 获取道具信息 方法。

获得令牌去打开商店

为了集成商店UI到您的游戏中,您需要访问令牌。访问令牌是一个字符串,能识别游戏、用户和购买参数。

Xsolla API使用HTTP基本身份验证。提供您的商务ID为基本身份验证用户名,API秘钥为密码。

设置值为 "mode":"sandbox" 以测试支付流程。

令牌端点URL:

https://api.xsolla.com/merchant/merchants/{merchant_id}/token

在HTTP POST请求中,您可以使用商店UI的参数。请求和响应负载格式为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参考中找到参数的完整列表。

打开商店UI

有三种打开商店的方法:

  • 使用 Pay Station 嵌入脚本。
  • 新建窗口。
  • Iframe.

要以沙盒模式打开商店,请使用下列URL:https://sandbox-secure.xsolla.com/.

Pay Station 嵌入

Pay Station 嵌入脚本 将确定设备类型并在光盒(桌面屏幕)或新建窗口(移动或平板电脑屏幕)中打开商店UI。我们推荐使用异步脚本加载。

异步脚本加载范例:

 <script>
     var options = {
         access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
         sandbox: true //TODO please do not forget to remove this setting when going live
     };
     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>Buy Credits</button>

您可以在 API参考中找到参数的完整列表。

新建窗口

若要在新建窗口中打开商店UI,请使用下列链接:https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, 其中ACCESS_TOKEN 是在上一步中获得的令牌 .

Iframe

若要在iframe中打开商店UI,您必须在您的一端实施下列机制:

  • 指定设备类型 (桌面或移动) 并在令牌的 settings.ui.version 参数内发送它;
  • 通过 postMessage从支付UI接收事件。

若要在新建窗口中打开商店UI,请使用下列链接:https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, 其中ACCESS_TOKEN 是在上一步中获得的令牌 .

设置Webhooks

Xsolla将向您的项目发送以下webhook:

  • 用户验证
  • 支付
  • 退款

为了确认您完好收到了webhook通知,您的服务器应该返回一个没有正文的204 HTTP状态代码。关于带样本的webhook机制的完整描述的详细说明,请参阅API参考

创建签名

若要创建签名,请执行以下操作:

  1. 连接Xsolla服务器请求中发送的数据和项目秘钥(在项目设置中生成)。
  2. 使用SHA1算法对字符串进行散列。
  3. 发送签名标头中的签名。

处理webhook时,请确保收到的签名与签名标头中设置的签名相符。

用户验证

Xsolla服务器会向项目的webhook 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服务器将发送一个包含支付详情的webhook。

请求范例

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服务器会发送webhook通知,内含支付信息。

请求范例

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参考中找到参数的完整列表。

测试webhook

若要测试webhook处理器,请执行以下操作:

  1. 在发布商账户中,打开模块设置。
  2. 转到测试选项卡。 输入测试数据,然后单击测试。Xsolla服务器将发送所有可能的webhook。
  3. 有效响应时测试将标记为绿色,发生错误时将标记为红色。

测试支付流程

Xsolla Sandbox是一个独立环境,支持除真实付款外实时环境的所有功能。您可以通过在获得令牌时发送 "模式 = "sandbox"来访问沙盒

若要测试银行卡支付,请执行以下操作:

  1. 在沙盒模式中打开商店
  2. 选择要购买的物品。
  3. 单击 信用卡/借记卡
  4. 在其余字段中输入银行卡详情和任何值。您也可以指定不正确的细节(卡号、到期日、或CVV)以生成错误。

用于测试的银行卡列表

重要事项!沙盒模式下银行卡支付只能使用美元、欧元、卢布或英镑。

发布模块

若要在成功测试后发布模块,请在发布商账户中打开其设置,前往 发布 选项卡,然后单击

重要事项! 你必须先执行以下操作才能接受真实支付:

  1. 删除 "mode" = "sandbox"
  2. 签署协议。