打开支付UI
根据项目身份认证设置的不同,可通过如下方式打开支付UI:
通过创建令牌API调用
- 通过以下方式之一获取令牌以打开支付UI:
- 实现支付UI的打开方式:
显示支付方式选择页面
要让支付UI打开时显示支付方式选择页面,请向创建令牌API调用传入含所选计划ID的purchase.subscription.plan_id
参数。如需要,传入自定义补充参数。
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",
"hidden": true
},
"email": {
"value": "user1234@game1234.com"
},
"name": {
"value": "UserName",
"hidden": false
}
},
"settings": {
"project_id": 12345,
"currency": "USD"
},
"purchase": {
"subscription": {
"plan_id": "54321"
}
}
}'
支付方式选择页面示例:

显示支付数据输入页面
要让支付UI打开时显示支付数据输入页面,请将以下参数传入创建令牌API调用:
- 含所选计划ID的
purchase.subscription.plan_id
。 - 含支付方式ID的
settings.payment_method
。要找到项目中的ID列表,可在发布商帐户中前往支付中心 > 付款方式部分,或向您的帐户经理索取。
如需要,传入自定义补充参数。
- curl
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",
"hidden": true
},
"email": {
"value": "user1234@game1234.com"
},
"name": {
"value": "UserName",
"hidden": false
}
},
"settings": {
"project_id": 12345,
"payment_method": 1380,
"currency": "USD"
},
"purchase": {
"subscription": {
"plan_id": "54321"
}
}
}'
支付数据输入页面示例:

显示订阅管理和账单帐户页面
要让支付UI打开时显示订阅和支付帐户管理页面,请将settings.ui.mode = user_account
参数传入创建令牌API调用。
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",
"hidden": true
}
},
"settings": {
"project_id": 146026,
"language": "en",
"currency": "USD",
"ui": {
"mode": "user_account",
"theme": "default_dark",
"desktop": {
"subscription_list": {
"layout": "grid"
}
}
}
}
}
订阅管理页面和账单帐户示例:

通过客户端API方法
- 通过以下方式之一实现打开支付UI的客户端方法:
- 通过以下方式之一实现支付UI的打开:
显示支付方式选择页面或输入支付数据
在应用程序的的客户端侧,请使用HTTP POST请求实现支付UI的打开:https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/buy
。
请求必须包含Authorization: Bearer <client_user_jwt>
头,其中<client_user_jwt>
是用户的JSON Web令牌(JWT),它是一个根据Base64标准编码的Base64编码令牌。要获取该令牌:
- 如应用程序使用用户名和密码认证,请使用
Register new user 和Auth by username and password API调用。 - 如应用程序使用通过社交网络认证,请使用
Auth via social network API调用。
指定项目ID作为projectId
路径参数。可在发布商帐户项目名称旁边找到该参数。
指定country
作为请求参数,值为符合ISO 3166-1 alpha-2标准的用户国家/地区两字母代码。该参数影响区域位置和货币。如未传入该参数,则国家/地区由用户的IP地址决定。
在请求中传入如下参数:
plan_external_id
,以在支付方式选择页面打开支付界面。
支付UI示例:

plan_external_id
和settings.payment_method
,以在输入支付数据页面打开支付界面。
支付UI示例:

请求正文参数:
参数 | 类型 | 描述 |
---|---|---|
| string | 必需。订阅计划的外部ID。可在发布商帐户 > 订阅 > 订阅计划部分找到。 |
| object | 带有自定义项目设置的对象。 |
| object | 带有界面设置相关数据的对象。 |
| string | 支付UI的大小。此参数可拥有以下值之一,具体取决于支付UI的所需大小:
|
| string | 支付UI的外观主题。可以是default 或default_dark 。 |
| string | 设备类型。可以是desktop (默认)或mobile 。 |
| object | 带有对桌面版本有效的界面设置相关数据的对象。 |
| object | 带有标题设置相关数据的对象。 |
| boolean | 是否在支付中心桌面端显示关闭按钮。该按钮将关闭支付中心并将用户重定向到settings.return_url 参数中指定的URL。默认为false 。 |
| boolean | 标题在支付UI上是否可见。 |
| string | 标题外观。可以是compact (游戏名和用户ID不在标题中显示)或normal 。 |
| boolean | 如果为true ,标头中将显示Logo(请先把Logo文件提供给您的项目经理)。 |
| boolean | 标题中是否显示项目名称。 |
| string | 如何显示标题。可以是compact (隐藏项目名称和用户ID)或normal (默认)。 |
| string | 用户仅可以通过他们已保存的付款方式进行付款。可以为saved_accounts 。 |
| boolean | 是否在移动版本的支付UI中隐藏或显示脚注。 |
| boolean | 是否在支付中心移动版中显示关闭按钮。该按钮将关闭支付中心并将用户重定向到settings.return_url 参数中指定的URL。默认为false 。 |
| string | EULA的链接。 |
| string | 支付中心中的界面模式。只能是user_account :标头仅包含帐户导航菜单,而没有用于选择产品或进行付款的任何选项。此模式仅在桌面版中可用。 |
| object | 对象以及有关用户账号的数据。 |
| object | 历史记录子菜单。 |
| integer | 该部分是否应在支付UI的下拉菜单中显示。可以是true 或false 。如未传入此参数,则不显示该部分。 |
| integer | 该部分在支付界面下拉菜单中的位置。 |
| object | 我的帐户页面。 |
| integer | 该部分在支付UI下拉菜单中的位置。 |
| boolean | 该部分是否应在支付UI的下拉菜单中显示。可以是true 或false 。如未传入此参数,则不显示该部分。 |
| object | 我的支付帐户子菜单。 |
| integer | 该部分在支付UI下拉菜单中的位置。 |
| boolean | 是否显示子菜单。可以是true 或false 。如未传入此参数,则显示该部分。 |
| object | 管理订阅子菜单。 |
| boolean | 是否显示子菜单。可以是true 或false 。如未传入此参数,则显示该部分。 |
settings.ui.user_account.subscriptions.order | integer | 该部分在支付UI下拉菜单中的位置。 |
| string | 首选支付币种。参照ISO 4217标准的三字母货币代码。 |
| string | 游戏中的交易ID。值对于每个用户付款必须唯一。 |
| integer | 支付方式ID。要获取支付方式ID列表,您可以前往发布商帐户,或使用获取支付方式API调用。 |
| string | 用户在支付过后重定向到的页面。参数user_id 、foreigninvoice 、invoice_id 和status 将自动添加到链接中。 |
| object | 重定向政策设置(对象)。 |
| string | 支付后将用户重定向到返回URL的支付状态。可以是none 、successful 、successful_or_canceled 或any 。 |
settings.redirect_policy.delay | integer | 延迟时间(单位为秒),经过该时间后用户将自动重定向至返回URL。 |
| string | 支付后将用户重定向到返回URL的支付状态。可以是none 、successful 、successful_or_canceled 或any 。 |
| string | 手动重定向按钮上的文字。 |
如需要,传入自定义补充参数。
curl -X 'POST' \
'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/buy?country=RU ' \
-H 'accept: application/json' \
-H 'Authorization: Bearer client_user_jwt'
{
"plan_external_id": "PlanExternalId",
"settings": {
"ui": {
"size": "large",
"theme": "string",
"version": "desktop",
"desktop": {
"header": {
"is_visible": true,
"visible_logo": true,
"visible_name": true,
"type": "compact",
"close_button": true
}
},
"mobile": {
"mode": "saved_accounts",
"footer": {
"is_visible": true
},
"header": {
"close_button": true
}
},
"license_url": "string",
"mode": "user_account",
"user_account": {
"history": {
"enable": true,
"order": 1
},
"payment_accounts": {
"enable": true,
"order": 1
},
"info": {
"enable": true,
"order": 1
},
"subscriptions": {
"enable": true,
"order": 1
}
}
},
"currency": "string",
"locale": "string",
"external_id": "string",
"payment_method": 1,
"return_url": "string",
"redirect_policy": {
"redirect_conditions": "none",
"delay": 0,
"status_for_manual_redirection": "none",
"redirect_button_caption": "string"
}
}
}
{
"link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
}
显示订阅管理页面和账单帐户
在应用程序的的客户端侧,请使用HTTP POST请求实现支付UI的打开:https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/manage
。
请求必须包含Authorization: Bearer <client_user_jwt>
头,其中<client_user_jwt>
是用户的JSON Web令牌(JWT),它是一个根据Base64标准编码的Base64编码令牌。要获取该令牌:
- 如应用程序使用用户名和密码认证,请使用
Register new user 和Auth by username and password API调用。 - 如应用程序使用通过社交网络认证,请使用
Auth via social network API调用。
指定项目ID作为projectId
路径参数。可在发布商帐户项目名称旁边找到该参数。
指定country
作为请求参数,值为符合ISO 3166-1 alpha-2标准的用户国家/地区两字母代码。该参数影响区域位置和货币。如未传入该参数,则国家/地区由用户的IP地址决定。
如需要,传入自定义补充参数。
请求正文参数:
参数 | 类型 | 描述 |
---|---|---|
| string | 必需。订阅计划的外部ID。可在发布商帐户 > 订阅 > 订阅计划部分找到。 |
| object | 带有自定义项目设置的对象。 |
| object | 带有界面设置相关数据的对象。 |
| string | 支付UI的大小。此参数可拥有以下值之一,具体取决于支付UI的所需大小:
|
| string | 支付UI的外观主题。可以是default 或default_dark 。 |
| string | 设备类型。可以是desktop (默认)或mobile 。 |
| object | 带有对桌面版本有效的界面设置相关数据的对象。 |
| object | 带有标题设置相关数据的对象。 |
| boolean | 是否在支付中心桌面端显示关闭按钮。该按钮将关闭支付中心并将用户重定向到settings.return_url 参数中指定的URL。默认为false 。 |
| boolean | 标题在支付UI上是否可见。 |
| string | 标题外观。可以是compact (游戏名和用户ID不在标题中显示)或normal 。 |
| boolean | 如果为true ,标头中将显示Logo(请先把Logo文件提供给您的项目经理)。 |
| boolean | 标题中是否显示项目名称。 |
| string | 如何显示标题。可以是compact (隐藏项目名称和用户ID)或normal (默认)。 |
| string | 用户仅可以通过他们已保存的付款方式进行付款。可以为saved_accounts 。 |
| boolean | 是否在移动版本的支付UI中隐藏或显示脚注。 |
| boolean | 是否在支付中心移动版中显示关闭按钮。该按钮将关闭支付中心并将用户重定向到settings.return_url 参数中指定的URL。默认为false 。 |
| string | EULA的链接。 |
| string | 支付中心中的界面模式。只能是user_account :标头仅包含帐户导航菜单,而没有用于选择产品或进行付款的任何选项。此模式仅在桌面版中可用。 |
| object | 对象以及有关用户账号的数据。 |
| object | 历史记录子菜单。 |
| integer | 该部分是否应在支付UI的下拉菜单中显示。可以是true 或false 。如未传入此参数,则不显示该部分。 |
| integer | 该部分在支付界面下拉菜单中的位置。 |
| object | 我的帐户页面。 |
| integer | 该部分在支付UI下拉菜单中的位置。 |
| boolean | 该部分是否应在支付UI的下拉菜单中显示。可以是true 或false 。如未传入此参数,则不显示该部分。 |
| object | 我的支付帐户子菜单。 |
| integer | 该部分在支付UI下拉菜单中的位置。 |
| boolean | 是否显示子菜单。可以是true 或false 。如未传入此参数,则显示该部分。 |
| object | 管理订阅子菜单。 |
| boolean | 是否显示子菜单。可以是true 或false 。如未传入此参数,则显示该部分。 |
settings.ui.user_account.subscriptions.order | integer | 该部分在支付UI下拉菜单中的位置。 |
| string | 首选支付币种。参照ISO 4217标准的三字母货币代码。 |
| string | 游戏中的交易ID。值对于每个用户付款必须唯一。 |
| integer | 支付方式ID。要获取支付方式ID列表,您可以前往发布商帐户,或使用获取支付方式API调用。 |
| string | 用户在支付过后重定向到的页面。参数user_id 、foreigninvoice 、invoice_id 和status 将自动添加到链接中。 |
| object | 重定向政策设置(对象)。 |
| string | 支付后将用户重定向到返回URL的支付状态。可以是none 、successful 、successful_or_canceled 或any 。 |
settings.redirect_policy.delay | integer | 延迟时间(单位为秒),经过该时间后用户将自动重定向至返回URL。 |
| string | 支付后将用户重定向到返回URL的支付状态。可以是none 、successful 、successful_or_canceled 或any 。 |
| string | 手动重定向按钮上的文字。 |
如需要,传入自定义补充参数。
curl -X 'POST' \
'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/manage?country=RU ' \
-H 'accept: application/json' \
-H 'Authorization: Bearer client_user_jwt'
{
"settings": {
"ui": {
"size": "large",
"theme": "string",
"version": "desktop",
"desktop": {
"header": {
"is_visible": true,
"visible_logo": true,
"visible_name": true,
"type": "compact",
"close_button": true
}
},
"mobile": {
"mode": "saved_accounts",
"footer": {
"is_visible": true
},
"header": {
"close_button": true
}
},
"license_url": "string",
"mode": "user_account",
"user_account": {
"history": {
"enable": true,
"order": 1
},
"payment_accounts": {
"enable": true,
"order": 1
},
"info": {
"enable": true,
"order": 1
},
"subscriptions": {
"enable": true,
"order": 1
}
}
},
"currency": "str",
"locale": "st",
"external_id": "string",
"payment_method": 1,
"return_url": "string",
"redirect_policy": {
"redirect_conditions": "none",
"delay": 0,
"status_for_manual_redirection": "none",
"redirect_button_caption": "string"
}
}
}
{
"link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
}
支付UI示例:

自定义
在支付UI中,可使用以下自定义选项:
- 向获取令牌调用或打开支付界面的客户端方法传入
settings.ui.theme = default_dark
参数,可将标准浅色界面主题更改为深色。如未传入该参数,则默认使用浅色界面。
深色主题下的支付UI示例:

深色主题的令牌请求示例:
- curl
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",
"hidden": true
},
"email": {
"value": "user1234@game1234.com"
},
"name": {
"value": "UserName",
"hidden": false
}
},
"settings": {
"project_id": 12345,
"currency": "USD"
"ui": {
"theme": "default_dark"
}
}
}
'
- 在订阅部分放置自己的描述。方法是将描述文本放在
ui.desktop.subscription_list.description
参数中传入创建令牌API调用。
支付UI示例:

含订阅管理部分和订阅计划描述部分的浅色主题的令牌请求示例:
- curl
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",
"hidden": true
},
"email": {
"value": "user1234@game1234.com"
},
"name": {
"value": "UserName",
"hidden": false
}
},
"settings": {
"project_id": 12345,
"currency": "USD",
"ui": {
"desktop": {
"subscription_list": {
"description": "Your Description"
}
},
"user_account": {
"subscriptions": {
"order": 1,
"enable": true
}
}
}
}
}
'
- 将标准订阅列表视图更改为区块形式的另一种视图。方法是向创建令牌API调用传入
settings.ui.desktop.subscription_list.layout = grid
参数。该参数默认使用list
作为值。
支付UI示例:

另一种订阅列表视图的令牌请求示例:
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",
"hidden": true
},
"email": {
"value": "user1234@game1234.com"
},
"name": {
"value": "UserName",
"hidden": false
}
},
"settings": {
"project_id": 111111,
"currency": "USD",
"ui": {
"desktop": {
"subscription_list": {
"layout": "grid"
}
}
}
}
}
'
关于自定义及相关参数的更多信息,请参阅如何自定义支付中心指南。
使用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=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
。
发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。