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

Lootboxes

Lootboxes 是用户可以购买或作为奖励接收到的游戏道具和/或虚拟货币集。lootbox内容随机生成,在lootbox打开前用户不知道。

lootbox模块有各种集成选项,可以让游戏项目配置以下内容:

  • 选择签发lootbox: 从游戏请求或通过商店购买
  • 选择购买lootbox: 通过真实或虚拟货币
  • 选择打开lootbox: 通过真实或虚拟货币或通过使用以真实或虚拟货币购买的秘钥
  • 选择定义具体道具或虚拟货币包如何在lootbox内衍生
  • 设置任何给定道具的属性出现在lootbox中的概率
  • Lootbox打开动画

集成指南

该模块支持以下功能:

  • 购买游戏事件时添加lootbox到用户库存
  • 添加新道具到用户库存时显示动画序列
  • 打开 lootbox 时显示动画序列
  • 打开 lootbox 后从库存删除

若要启用 lootboxes,请执行以下操作:

  1. 注册 Xsolla 发布商账户
  2. 创建项目
  3. 设置模块
  4. 设置 lootbox
  5. 获得令牌
  6. 设置 打开商店 UI。
  7. 设置 webhook 处理。
  8. 测试 支付流程。
  9. 发布 模块和签署协议。

集成需要下列参数:

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

创建项目

  1. 转到项目,然后单击创建新项目
  2. 在项目设置中:
    a. 指定webhook URL。
    b. 生成用来签名项目webhook的秘钥。
    c. 启用 虚拟道具 模块。
    d. 前往 用户 并设置 Xsolla中的商店用户数据

设置模块

要开始使用 lootboxes, 请首先创建一个可以存储在 lootbox 内的虚拟道具目录。

  1. 为此,请前往 虚拟道具 模块设置然后单击 创建道具组。配置组:
    a. 目录中的位置 (默认为根文件夹)。
    b. 代码。
    c. 名称和描述。
    d. 商店外观。如果您想要组显示在商店中,请勾选 在商店中显示
  2. 单击 创建
  3. 单击 道具列表 返回基本模块并创建您的目录需要的其它组。
  4. 单击 创建道具 并设置以下参数:
    a. 道具所属的组的数量 (一个或多个)。如果未选任何组,道具将不显示在商店中。
    b. SKU — 唯一标识符。
    c. 名称和简短描述。
    d. 真实货币价格。
    e. 图像。
  5. 单击 创建
  6. 单击 道具列表 返回基本模块并创建需要的其它道具。

设置 Lootboxes

一个lootbox由数个槽位组成。当lootbox打开时,每个槽位会填充一件随机道具。您必须提前定义道具范围及其出现的概率。

若要创建和配置lootbox, 请使用“创建 LOOTBOXES”方法,指定以下参数:

  • lootbox 槽位数量。
  • 每个可能的lootbox道具出现在每个槽位中的概率表。
  • 指定属性道具出现在每个槽位中的概率表。
  • 槽位保持空的概率。
  • 重复道具是否可被虚拟货币代替 (作为价格的百分比或具体金额)。

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

获得令牌去开店

为了集成商店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

使用 Xsolla\SDK\API\XsollaClient;
使用 Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = 新建 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 使用上一步中接收到的访问令牌
沙盒: 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(选项);
}, false);
var head = document.getElementsByTagName('head')[0];
head.appendChild(s);
</script>

<button data-xpaystation-widget-open>购买信用</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 '授权:签名 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 '授权:签名 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(
'virtual_currency_balance' => (
'old_value' => '0',
'new_value' => '200',
'diff' => '200'
),
'user' => (
'name' => 'Xsolla 用户',
'id' => '1234567',
'email' => 'email@example.com'
),
'operation_type' => 'inGamePurchase',
'notification_type' => 'user_balance_operation',
'items_operation_type' =>  'add',
'items' =>  array(
'sku' =>  '1468',
'amount' =>  '2'
),
'id_operation' => '66989'
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H '授权:签名 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"200",
"diff":"200"
},
"user":{
"name":"Xsolla 用户",
"id":"1234567",
"email":"semail@example.com
},
"operation_type":"inGamePurchase",
"notification_type":"user_balance_operation",
"items_operation_type":"add",
"items":[{
"sku":"1468",
"amount":"2"
}],
"id_operation":"66989"
}'

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

退款

如果用户取消支付,Xsolla服务器会发送webhook通知,内含支付信息。

请求范例

PHP
CURL
$request = array(
'notification_type' => 'refund',
'purchase' => array(
'virtual_currency' => array(
'name' => '金币',
'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' => '欺诈'
),
'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 '授权:签名 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
"notification_type":"refund",
"purchase":{
"virtual_currency":{
"name":"金币",
"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 用户",
"country":"US"
},
"transaction":{
"id":1,
"external_id":1,
"dry_run":1,
"agreement":1
},
"refund_details":{
"code":1,
"reason":"欺诈"
},
"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. 转到测试选项卡。
  3. 输入测试数据,然后单击测试。Xsolla服务器将发送所有可能的webhook。
  4. 响应有效时,测试标记为绿色,发生错误时标记为红色。

测试支付流程

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

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

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

用于测试的银行卡列表

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

发布模块

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

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

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

在游戏服务器端打开Lootbox

当在游戏服务器端打开 lootbox 时,您可以:

  • 检查用户库存中是否存在 lootbox。
  • 获得掉落道具列表。
  • 添加新道具到用户库存。
  • 打开 lootbox 后从库存删除。

若要启用该功能,请联系您的帐户经理。

Lootbox打开动画

如果lootbox是在Xsolla服务器端打开的,您可以添加动画序列(取决于打开的结果)。要启用此功能,请与您的帐户经理联系。