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

每日奖励

每日奖励颁发给购买高级订购的用户。每个高级订购有自己的奖励集。

集成指南

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

  1. 注册 Xsolla 发布商账户
  2. 创建新项目
  3. 配置模块
  4. 配置高级订购奖励
  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}/.
  • 项目秘钥 — 在项目设置中生成。

该指南描述了快速启动模块所需的最少设置集合。您可以在API参考中找到参数的完整列表。如有任何问题,请联系您的账户经理。

创建项目

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

设置模块

  1. 转到订购模块设置,然后单击创建新计划。指定以下参数:
    a. 名称。
    b. 支付周期。
  2. 单击 创建
  3. 单击 返回计划列表 返回基本模块设置并创建需要的其它计划。

重要事项! 一项计划只能用一种货币。您必须为每个项目货币创建单独计划。

设置高级计划奖励

您可以添加以下奖励到高级计划:

  1. 游戏商店中的虚拟道具单独折扣和游戏货币套餐。
  2. 重复累计游戏货币。
  3. 重复累计虚拟道具。用户可以接收:
  4. 列表上的随机道具,道具范围和在项目设置中对其进行配置的机会。
  5. 具体道具,在项目设置中指定的序列中。

重要事项! 取决于您选择的奖励,您需要进一步设置 虚拟道具 和/或 虚拟货币 模块。

若要设置奖励,请提交请求到 integration@xsolla.com

获得令牌去开店

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

请求范例

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
<?php
$request = array(
'notification_type' => 'create_subscription',
'user' => (
'id' => '1234567',
'name' => 'Xsolla 用户'
),
'subscription' => (
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => '展示品',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_next_charge' => '2015-01-22T19:25:25+04:00',
'trial' =>  (
'value' =>  90,
'type' =>  'day'
)
)
);
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H '授权:签名 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"create_subscription",
"user":{
"id":"1234567",
"name":"Xsolla 用户"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"展示品",
"date_create":"2014-09-22T19:25:25+04:00",
"date_next_charge":"2015-01-22T19:25:25+04:00",
"trial":{
"value":90,
"type":"day"
}
}
}'

您可以在 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
<?php
$request = array(
'notification_type' => 'update_subscription',
'user' => (
'id' => '1234567',
'name' => 'Xsolla 用户'
),
'subscription' => (
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => '展示品',
'date_next_charge' => '2015-01-22T19:25:25+04:00'
)
);
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H '授权:签名 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"update_subscription",
"user":{
"id":"1234567",
"name":"Xsolla 用户"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"展示品",
"date_next_charge":"2015-01-22T19:25:25+04:00"
}
}'

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

订购已取消

订购被取消时Xsolla服务器会发送webhook。

请求范例

PHP
CURL
<?php
$request = array(
'notification_type' => 'cancel_subscription',
'user' => (
'id' => '1234567',
'name' => 'Xsolla 用户'
),
'subscription' => (
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => '展示品',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_end' => '2015-01-22T19:25:25+04:00',
)
);
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H '授权:签名 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"cancel_subscription",
"user":{
"id":"1234567",
"name":"Xsolla 用户"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"展示品",
"date_create":"2014-09-22T19:25:25+04:00",
"date_end":"2015-01-22T19:25:25+04:00"
}
}'

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

测试webhook

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

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

测试支付流程

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

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

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

用于测试的银行卡列表

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

发布模块

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

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

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