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

预订

“预订”是基于Xsolla Pay2Play的一项解决方案,可以让发布者在正式发布日期前出售游戏。用户预订游戏后,将收到一个唯一编号作为购买凭证。一旦游戏发布,我们将自动向用户发送访问游戏的PIN码。

集成指南

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

  1. 注册Xsolla发布商帐户
  2. 创建项目
  3. 配置模块
  4. 集成Pay2Play小组件
  5. 测试支付流程
  6. 签署协议。
  7. 在发布当日上传PIN码

创建项目

  1. 转到项目,然后单击创建新项目
  2. 在设置模式中:
    a. 将Webhooks设置为
    b. 将无服务器集成设置为
  3. 开启Pay2Play模块。

配置模块

  1. 转到Pay2Play设置并配置以下参数:
    a. 游戏名称。
    b. 游戏说明。
    c. 系统要求。
    d. SKU — 唯一标识符。
    e. 发布日期。
    f. 图像。
    g. DRM平台。
    h. 所选DRM平台支持的操作系统/游戏控制台版本。
  2. 单击下一步
  3. 为所选DRM平台设置价格。

集成Pay2Play小组件

Pay2Play小组件将以灯箱模式(桌面屏幕上)或在新窗口(手机或平板电脑屏幕上)中打开您的商店。该小组件会自动确定设备类型。

要获得小组件代码,请在您的发布商帐户中打开模块设置,然后转到发布选项卡。复制所需小组件的代码并添加到您的游戏网站。我们推荐使用异步加载。

异步脚本加载范例:

<script>
var access_data = {"settings":{"project_id":14004,"mode":"sandbox"},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
var target_element = "#widget-example-element";
var s = document.createElement('script');
s.type = "text/javascript";
s.async = true;
s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
s.addEventListener('load', function (e) {
var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
}, false);
var head = document.getElementsByTagName('head')[0];
head.appendChild(s);
</script>

您可以在API参考中找到小组件初始化参数的完整列表。有关小组件的安装说明,请访问: GitHub

重要事项!您需要签署协议后才能接受真实付款。

测试支付流程

Xsolla Sandbox是一个独立环境,支持除真实付款外实时环境的所有功能。您可通过以下方式访问Sandbox:在access_data对象中发送"settings.mode" = "sandbox"access_data中的JSON结构和参数与<a href="../api_v2.html#token target="_blank">令牌请求中的一样。

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

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

用于测试的银行卡列表

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

上传PIN码

一旦游戏发布,请打开Pay2Play模块设置,然后在代码上传选项卡中上传所选DRM平台的PIN代码。

对授权用户进行支付

对于已有游戏账户的用户来说,您可以发送用户信息进行授权交易。若要启用该功能,请执行以下操作:

  1. 设置项目。
  2. 获取令牌。
  3. 设置webhook处理。

您将需要以下参数:

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

设置项目

若要设置项目,请执行以下操作:

  1. Webhooks设置为
  2. 指定webhook URL。
  3. 生成用来签名项目webhook的秘钥。
  4. 无服务器集成设置为

获得令牌去开店

为了集成商店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参考中找到参数的完整列表。

设置 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. 响应有效时,测试标记为绿色,发生错误时标记为红色。

开发者打赏

用户购买时可对项目进行打赏。若要启用该功能,请打开模块设置,转到价格选项卡,然后将在Pay2play小组件中使用打赏设置为。每种启用的货币有三种打赏金额选项可用。

用户可以在进入商店前选择打赏金额。打赏金额将添加到购买价。

限制预订数量

您可以限制指定项目的预订数量。您将收到以下电子邮件通知:只剩100或100件以下可预订;预订已售空。若用户预订的数量超出限制,将无法支付。

销售区域限制

预订 模块允许您限制预订的销售区域。具体如下:

  • 为单个国家/地区或国家/地区组设置不同价格;
  • 禁止在某些国家/地区销售。

一旦项目配置成功,试图在受限国家/地区进行预订的用户将会看到相应的警告。在禁止预订的国家/地区中,用户将无法支付。

若要启用该功能,请联系您的帐户经理。对于应用区域限制的平台,我们需要以下信息:

  • 限制类型:
    • 激活:PIN码只能在某些国家/地区激活。
    • 启动:PIN码可以在任何国家/地区激活,但是游戏只能在某些国家/地区中启动;
    • 激活和启动:只能在某些国家/地区激活PIN码和启动游戏。
  • 不同预订价格的国家/地区组列表。
  • 每组国家/地区的设置:
    • 组名称。
    • SKU — 唯一组标识符。
    • 不同币种的价格列表。务必包含模块设置中设定的默认货币的价格。
    • 每组内的国家/地区列表。
  • 预订被禁用(如有)的国家/地区列表。

对于任何单一平台,一个国家/地区要么属于不同价格组,要么属于预订被禁用组。如果某个国家/地区不属于任何组,则预订不受任何限制,价格为默认模块设置中的价格。

重要事项!如果PIN码激活和游戏启动由您或平台执行,请务必将区域限制配置完毕后再将PIN码上传到我们的系统。