集成付款解决方案
要跟踪协作推广者带来的引荐数并向其支付佣金,需先集成艾克索拉支付中心。要求:
- 支付中心集成在经过性能优化的着陆页上。
- 支付中心是通过流量联盟活动导流的游戏着陆页上使用的唯一付款方式。
获取令牌
要打开支付UI,您需要先获取令牌。令牌是一个包含游戏和用户加密数据的字符串。您需要实现获取令牌来识别用户身份以允许其进行购买。
在您的应用程序后端,实现获取用户认证令牌。方法是使用包含基本HTTP认证的HTTP POST请求,并在请求正文中传入必需参数。
令牌的有效期是自最后一次调用艾克索拉API后14小时。请实现令牌过期后重新获取令牌的逻辑。建议在后台获取新令牌,这样用户就无须重新登录应用。
基本HTTP认证
艾克索拉API使用基本认证。所有发送到API的请求必须包含Authorization: Basic <your_authorization_basic_key>
头,其中<your_authorization_basic_key>
是按照Base64标准加密的商户ID: API密钥对。请前往发布商帐户找到以下参数:
- 商户ID在以下位置显示:
- 在项目设置 > Webhooks部分。
- 在公司设置 > 公司部分。
- 在发布商帐户任意页面的浏览器地址栏的URL中。URL的格式如下:
https://publisher.xsolla.com/商户ID/发布商帐户部分
。
- API密钥仅在创建它时在发布商帐户中显示一次,必须存储在己侧。您可以在以下部分中创建新的密钥:
- 公司设置 > API密钥
- 项目设置 > API密钥
关于使用API密钥的详细信息,请参阅API参考。
关于密钥的建议:
- 请在己侧保存生成的API密钥。您仅会在创建API密钥时在发布商帐户中看见它一次。
- 请妥善保管API不被泄露。它提供对您的个人帐户及您在发布商帐户中项目的访问权限。
- API密钥必须存储在您的服务器上,切勿保存在代码或前端中。
请求正文
在请求正文中传入以下必要参数:
参数 | 类型 | 描述 |
---|---|---|
user.id | string | 您系统中的唯一用户ID。 |
user.email | string | 接收购买收据的用户邮箱。如未传入此参数,将在支付页面显示一个必填字段要求其输入邮箱地址。 |
settings.project_id | integer | 游戏的艾克索拉ID。可在发布商帐户的项目部分找到该信息。 |
为提升用户体验,还可以传入以下参数:
参数 | 类型 | 描述 |
---|---|---|
user.name | string | 在收据上显示的用户昵称。 |
settings.currency | string | 首选支付货币。 |
settings.language | string | 界面语言。 |
settings.ui.size | string | 支付UI大小。可以是:small (620 x 630 px)、medium (740 x 760 px)和large (820 x 840 px)。 |
获取用户认证令牌请求的示例
curl -i -X POST \
-u 2340:ZHgbSDVP6LtAJVWu \
https://api.xsolla.com/merchant/v2/merchants/<merchant_id>/token \
-H 'Content-Type: application/json' \
-d '{
"settings": {
"currency": "USD",
"language": "en",
"project_id": <project_id>,
"ui": {
"size": "medium"
}
},
"user": {
"email": {
"value": "<user_email>"
},
"id": {
"value": "<user_id>"
},
"name": {
"value": "<user_name>"
}
}
}'
响应中收到的用户认证令牌示例
{
"token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
}
打开支付UI
新建窗口
要在新窗口中打开支付UI,请使用以下URL:https://sandbox-secure.xsolla.com/paystation2/?access_token=TOKEN
,其中TOKEN
是获得的令牌。
https://secure.xsolla.com/paystation2/?access_token=TOKEN
。您也可以通过其他方式打开支付UI:
- 使用Pay Station Embed。缺点:在游戏内浏览器(WebView)中打开可能会有问题。
- 在iframe中打开。缺点:在游戏内浏览器(WebView)或应用程序的移动版本中打开可能会有问题。
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集成到网站的过程。小组件脚本在我们的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=TOKEN
。
如要进行测试,请使用以下URL:https://sandbox-secure.xsolla.com/paystation3/?access_token=TOKEN
。
access_token
参数包含隐私用户数据。请确保获取该参数时使用服务器对服务器通信。Iframe
要在iframe中打开支付UI:
- 实现
postMessage
机制以接收支付UI的事件。 - 在使用支付组中的API调用创建订单时获取令牌。在请求中传入:
- 设备类型(桌面或移动设备)(
settings.ui.version
参数中) - 支付UI大小(
settings.ui.size
参数中):
- 设备类型(桌面或移动设备)(
支付中心大小 | Iframe宽度 |
---|---|
大(默认) | 670–850 px |
中 | 590–740 px |
小 | 510–630 px |
- 使用链接
https://sandbox-secure.xsolla.com/paystation2/?access_token=TOKEN
打开支付UI,其中TOKEN
是收到的令牌。
设置Webhook
如希望接收事件通知(如支付状态变化),请在发布商帐户中设置Webhook:
- 在发布商帐户中打开您的项目。
- 在侧边栏中单击项目设置,然后前往Webhooks。
- 将Webhooks开关设置为开。
- 指定Webhook URL。
- 默认会生成一个用于项目Webhook签名的密钥。如要生成一个新密钥,请单击刷新图标。
- 单击保存设置。
推荐实现以下Webhook:
要确认已收到Webhook,您的服务器必须作出如下响应:
- 不带消息正文的HTTP代码204。
- 描述问题的HTTP代码400(如果指定用户未找到或传入的签名无效)。
测试支付流程
要测试支付过程,您可以使用沙盒模式。沙盒模式是一个独立环境,支持除真实付款和拒绝支付外实时环境的所有功能。获得令牌后,您可以通过发送"mode":"sandbox"
来进入沙盒模式。
在沙盒模式下,可使用以下方式测试付款过程:
测试银行卡支付
如符合以下条件之一,除卡片详细信息外,还需指定邮政编码:
- 用户所在国家是美国或加拿大。
- 发卡行识别码(BIN)显示该卡的发行地在美国。
您可以指定任意有效的邮政编码(如12345)。该信息用于决定销售税税率,不影响测试付款过程。
沙盒模式下的银行卡付款支持以下货币: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。
测试PayPal支付
创建测试用PayPal帐户
要测试支付过程,您需要为PayPal沙盒模式创建一个帐户:
- 打开PayPal开发者网站。
- 登录您的帐户或新建帐户。
- 前往
Sandbox accounts 选项卡。 - 在
Sandbox test accounts 页面上单击Create account 。 - 选择
Personal (Buyer Account) 帐户类型并选择国家/地区。 - 单击
Create 。
创建的帐户在沙盒帐户列表中显示。
您也可以使用现有沙盒帐户的信息:
sb-xmxij16980134@business.example.com | oi9_m_KW |
sb-p7pju16979920@business.example.com | 7%%p8ioS |
进行测试性支付
- 在沙盒模式下打开支付UI。
- 选择PayPal支付方式。
- 在
Mock Response Code 字段中,输入0
或将该字段留空。 - 在邮政编码字段中,任意输入5个数字。

- 点击支付。您将跳转到一个PayPal帐户登录窗口。
- 输入沙盒帐户的信息:输入
Email ID 作为邮箱地址,输入System Generated Password 作为密码。要找到该信息:- 在PayPal开发者网站上登录您的帐户。
- 前往
Sandbox accounts 选项卡。 - 在
Sandbox test accounts 页面上选择一个沙盒帐户。 - 单击•••,然后选择View/Edit account。您将在随后打开的模态窗口中看到该信息。
- 完成测试支付。
上线
完成前面的步骤后,即可开始接收真实付款:
- 请确保已签署艾克索拉许可协议。
- 删除获取令牌时请求正文中的
"mode":"sandbox"
参数。 - 通过以下链接打开支付UI:
https://secure.xsolla.com/paystation3/?access_token=TOKEN
。
发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。