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

实体物品

实体物品 是一种基于 虚拟道具 模块的解决方案,可以让游戏开发员出售游戏周边设备。商店基于Xsolla API创建于游戏端。Xsolla提供支付UI并组织给终端用户送货。

集成指南

若要集成模块,请执行以下操作:

  1. 注册 Xsolla 发布商账户
  2. 创建项目
  3. 设置模块
  4. 实施 实体物品管理。
  5. 启用 送货服务。
  6. 获得令牌
  7. 设置 打开支付UI。
  8. 设置 webhook处理。
  9. 测试支付流程
  10. 发布模块和签署协议

集成需要下列参数:

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

创建项目

  1. 转到项目,然后单击创建新项目
  2. 在项目设置中:
  3. 指定webhook URL。
  4. 生成用来签名项目webhook的秘钥。
  5. 打开 虚拟道具
  6. 前往 用户 并设置 Xsolla中的商店用户数据

设置模块

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

管理实体物品

若要管理实体物品,请执行以下操作:

  1. 使用列出店面虚拟道具 API方法执行市场的产品列表检索。
  2. 使用 获取库存状态 API方法执行库存检查。
  3. 检索打开支付UI的令牌。

启用送货服务

可用的送货服务列表会就每个合作伙伴进行单独讨论。欲知详情,请发送您的交付平台及其ID列表给您的账户经理。

获取支付UI令牌

为了集成支付UI到您的游戏中,您应该获得访问令牌。访问令牌是一个字符串,能识别游戏、用户和购买参数。 Xsolla API使用HTTP基本身份验证。提供您的商务ID为基本身份验证用户名,API秘钥为密码。

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

获取令牌端点:

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

有三种打开支付UI的方法:

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

要以沙盒模式打开支付UI,请使用下列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(
'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. 以沙盒模式打开支付UI。
  2. 单击 信用卡/借记卡.
  3. 在其余字段中输入银行卡详情和任何值。您也可以指定不正确的细节(卡号、到期日、或CVV)以生成错误。

用于测试的银行卡列表

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

发布模块

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

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

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