集成付款解决方案
要跟踪协作推广者带来的引荐数并向其支付佣金,需先集成艾克索拉支付中心。要求:
- 支付中心集成在经过性能优化的着陆页上。
- 支付中心是通过流量联盟活动导流的游戏着陆页上使用的唯一付款方式。
获取令牌
需要令牌才能集成支付UI。访问令牌是一个识别游戏、用户和购买参数的字符串。
艾克索拉API使用基本认证。请指定您的商户ID作为用户名,API密钥作为密码。
要找到该数据:
- 在您的发布商帐户前往公司设置。
- 在公司选项卡中,复制商户ID。
- 在API密钥选项卡中,复制API密钥。

获取令牌的URL:
- curl
https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token
user.id
、user.name
、user.email
参数中传入相关用户信息。user.id
参数,请使用用户容易记住的标识符,以便之后其自行在游戏外使用(例如在游戏余额充值等客户发起型支付情境)。请求与响应均为JSON格式。
以下为通过艾克索拉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')
->setPurchase(9.99, 'USD');
$xsollaClient = XsollaClient::factory(array(
'merchant_id' => MERCHANT_ID,
'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
curl -v https://api.xsolla.com/merchant/v2/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"
},
"purchase": {
"checkout": {
"amount": 9.99,
"currency": "USD"
}
}
}'
打开支付UI
有三种打开支付UI的方法:
签署与艾克索拉的协议之前,只支持在沙盒模式下测试支付过程。如遇到错误,请参阅错误描述。
要以沙盒模式打开支付UI,请使用下列URL:https://sandbox-secure.xsolla.com/
。
Pay Station Embed
示例:异步脚本加载
- html
<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>
Pay Station Embed允许通过postMessage获取支付UI事件。您可以将事件发送到分析系统。如要在分析系统中设置事件处理,请联系帐户经理或发送电子邮件至am@xsolla.com。
要轻松在网站上实现该支付UI,请从我们的CDN下载脚本。请使用该URL将脚本集成到您的网站。如需更多信息,请访问我们的GitHub存储库。
用于脚本初始化的参数列表:
参数 | 类型 | 描述 |
---|---|---|
access_token | string | 令牌,通过API接收。 必需。 |
sandbox | boolean | 设置为true 以测试支付流程,将使用sandbox-secure.xsolla.com 而不是secure.xsolla.com 。 |
lightbox | object | 带有选项列表的对象,可用于打开lightbox(桌面版本)。 |
lightbox.width | string | Lightbox框架的高度。如果为null ,则取决于支付中心的高度。默认值为null 。 |
lightbox.height | string | Lightbox框架的高度。如果为null ,则取决于支付中心的高度。默认值为100% 。 |
lightbox.zIndex | integer | 控制垂直堆叠顺序的属性,默认值为1000 。 |
lightbox.overlayOpacity | integer | 浮层不透明度(从0到1),默认值为.6 。 |
lightbox.overlayBackground | string | 浮层背景色,默认值为#000000 。 |
lightbox.modal | boolean | 如为true ,lightbox框架不可关闭,默认值为false 。 |
lightbox.closeByClick | boolean | 如为true ,单击浮层将关闭lightbox,默认值为true 。 |
lightbox.closeByKeyboard | boolean | 如为true ,按ESC键将关闭lightbox,默认值为true 。 |
lightbox.contentBackground | string | 框架的背景,默认值为#ffffff 。请注意,颜色更改不会影响支付中心iframe本身,只会影响容纳iframe的灯箱的设置。 |
lightbox.contentMargin | string | 框架边距,默认值为 10px 。 |
lightbox.spinner | string | 加载指示器的动画类型。可为xsolla 或round 。默认值为xsolla 。 |
lightbox.spinnerColor | string | 旋转加载动画的颜色,非默认设置。 |
childWindow | object | 支付中心UI所在子窗口的选项。适用于移动版本。 |
childWindow.target | string | 指定打开支付中心窗口的位置,可以是_blank 、_self 、_parent ,默认值为_blank 。 |
脚本使您可以跟踪支付UI发生的事件。根据事件的类型,可以在网页上执行各种操作。
事件列表:
参数 | 描述 |
---|---|
init | 小部件初始化事件。 |
open | 打开小部件时的事件。 |
load | 已加载支付UI(支付中心)。 |
close | 已关闭支付UI(支付中心)。 |
status | 用户在状态页面上移动时的事件。 |
status-invoice | 用户在状态页面上移动但支付尚未完成时的事件。 |
status-delivering | 用户在状态页面上移动,支付完成以及我们正在发送支付通知时的事件。 |
status-done | 用户在状态页面上移动且支付已成功完成时的事件。 |
status-troubled | 用户在状态页面上移动但支付失败时的事件。 |
如果您想要自行初始化打开支付UI,请使用此链接:https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
。
如用于测试,请使用以下URL:https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
。
Iframe
需在您的代码侧实现以下机制:
- 检查设备类型(桌面或移动设备)并将其包含在令牌的settings.ui.version参数中发送。
- 通过postMessage获取支付UI的事件。可将这些事件发送给分析系统。要在分析系统中设置事件处理,请联系帐户经理或发送电子邮件至am@xsolla.com。
如要在iframe中打开支付UI,请使用下列链接:https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
,其中ACCESS_TOKEN
是在上一步中获得的令牌。对于测试,请使用此URL:https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
。
新建窗口
如要在新窗口中打开支付UI,请使用下列链接:https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
,其中ACCESS_TOKEN
是在上一步中获得的令牌。对于测试,请使用此URL:https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
。
设置Webhook
通过发送不带消息正文的HTTP代码204来确认收到Webhook。
如要测试Webhook处理程序,请打开项目设置 > Webhook部分。
测试支付流程
要测试付款过程,可:
- 使用沙盒
- 进行真实付款,然后通过发布商帐户发起退款
艾克索拉沙盒是一个独立环境,支持除真实付款外实时环境的所有功能。获得令牌后,您可以通过发送"mode":"sandbox"
来访问沙盒。
- 以沙盒模式打开支付UI。
- 选择信用卡/借记卡付款方式组。
- 输入银行卡详细信息。在其余字段中输入任意值。您也可以指定不正确的细节(卡号、到期日、或CVV)以生成错误。
如满足以下条件之一,除银行卡详细信息外,还需要指定邮政编码:
- 用户所在国家为美国或加拿大。
- 发卡行识别码(BIN)显示该卡的发卡地在美国。
沙盒模式下的银行卡付款支持以下货币:USD、EUR、RUB、GBP、AED、ALL、AMD、ARS、AUD、AZN、BGN、BRL、BYN、CAD、CHF、CLP、CNY、COP、CZK、DKK、DZD、EGP、GEL、HKD、HRK、HUF、IDR、ILS、INR、ISK、JPY、KES、KGS、KRW、KZT、MAD、MDL、MKD、MNT、MXN、MYR、NGN、PEN、PHP、PKR、PLN、RON、RSD、SAR、SEK、SGD、THB、TRY、TWD、UAH、UYU、UZS、VEF、VND、ZAR。
"mode":"sandbox"
部分。如要通过进行真实付款来测试付款过程,同样建议使用银行卡:
- 打开支付UI。
- 选择信用卡/借记卡付款方式组。
- 输入有效的银行卡详细信息。
- 付款完成后,前往发布商帐户中的交易搜索部分。
- 选择该测试交易,然后单击退款(交易状态必须为已完成)。
上线
要开始处理真实付款:
- 确保已经与艾克索拉签订了合约。
- 通过
secure.xsolla.com
链接打开支付中心。或在Pay Station Embed脚本中将sandbox-secure.xsolla.com
改为secure.xsolla.com
。 - 获取令牌时去掉
"mode":"sandbox"
部分。
发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。