设置订阅目录显示和购买功能

订阅目录的实现方式取决于您的项目集成方案：

如果将订阅销售集成到自己的应用或网站，您可以：
- 使用艾克索拉API提供的订阅计划数据或本地数据，完全在己侧构建目录UI。
- 直接使用艾克索拉的支付UI显示订阅目录 — 无需另外获取订阅计划数据。
如果使用艾克索拉建站器创建网站，目录UI应直接放置在网站布局中，无需另外获取订阅计划数据或实现支付UI。

选择订阅目录的显示位置：

选择订阅购买的身份认证方式：

在此方案中，您在己侧实现订阅目录显示并通过自己的服务器管理购买流程。所有与艾克索拉的交互均通过艾克索拉API服务器侧调用完成。

要实现订阅目录显示和支付UI的打开：

使用服务器侧列示所有计划调用获取订阅计划列表（可选）。

您可以本地存储计划列表并用这些数据构建目录，无需额外调用API获取计划列表。

在己侧实现目录显示。
通过以下方式之一生成令牌以打开订阅购买的支付UI：
- 在支付方式选择页面上
- 在输入支付数据页面上
实现支付UI的打开。

生成令牌以在支付方式选择页面打开支付UI

要让支付UI打开时显示支付方式选择页面，请向创建令牌API调用传入含所选计划ID的purchase.subscription.plan_id参数。如需要，传入自定义补充参数。

如果项目中设置了订阅费用与首笔支付关联的计划，还需要传入以下参数：

purchase.checkout.amount，包含订阅计划的价格
purchase.checkout.currency，包含货币值

Copy

Full screen

Small screen

 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "currency": "USD"
24  },
25  "purchase": {
26    "subscription": {
27      "plan_id": "54321"
28    }
29  }
30}'

支付方式选择页面示例：

生成令牌以在输入支付数据页面打开支付UI

要让支付UI打开时显示支付数据输入页面，请将以下参数传入创建令牌API调用：

含所选计划ID的purchase.subscription.plan_id。
含支付方式ID的settings.payment_method。要找到项目中的ID列表，可在发布商帐户中前往付款 > 付款方式部分，或向您的客户成功经理索取。

如果项目中设置了订阅费用与首笔支付关联的计划，还需要传入以下参数：

purchase.checkout.amount，包含订阅计划的价格
purchase.checkout.currency，包含货币值

如需要，传入自定义补充参数。

Copy

Full screen

Small screen

 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "payment_method": 1380,
24    "currency": "USD"
25  },
26  "purchase": {
27    "subscription": {
28      "plan_id": "54321"
29    }
30  }
31}'

支付数据输入页面示例：

打开支付UI

如需允许用户切换订阅计划，请在项目中配置相关设置，并按照如何允许用户更改订阅计划的说明实现支付UI的打开。

示例：异步脚本加载

Copy

Full screen

Small screen

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

Pay Station Embed允许通过postMessage获取支付UI事件。您可以将事件发送到分析系统。如要在分析系统中设置事件处理，请联系您的客户成功经理或发送邮件至 csm@xsolla.com。

艾克索拉团队创建了一个小组件，帮助您简化将支付UI集成到网站的过程。小组件脚本在我们的GitHub存储库中提供。

用于脚本初始化的参数列表：

参数	类型	描述
access_token	string	令牌，通过API接收。必需。
sandbox	boolean	设置为`true`以测试支付流程，将使用`sandbox-secure.xsolla.com`而不是`secure.xsolla.com`。
lightbox	object	带有选项列表的对象，可用于打开lightbox（桌面版本）。
payment_widget_ui.lightbox.width	string	Lightbox框架的高度。如果为`null`，则取决于支付中心的高度。默认值为`null`。
payment_widget_ui.lightbox.height	string	Lightbox框架的高度。如果为`null`，则取决于支付中心的高度。默认值为`100%`。
payment_widget_ui.lightbox.zIndex	integer	控制垂直堆叠顺序的属性，默认值为`1000`。
payment_widget_ui.lightbox.overlayOpacity	integer	小组件背景的不透明度（`0` — 完全透明，`1` — 完全不透明）。默认值为60% (`.6`)。
payment_widget_ui.lightbox.overlayBackground	string	浮层背景色，默认值为`#000000`。
payment_widget_ui.lightbox.modal	boolean	如为`true`，lightbox框架不可关闭，默认值为`false`。
lightbox.closeByClick	boolean	如为`true`，单击浮层将关闭lightbox，默认值为`true`。
lightbox.closeByKeyboard	boolean	如为`true`，按ESC键将关闭lightbox，默认值为`true`。
payment_widget_ui.lightbox.contentBackground	string	框架的背景，默认值为`#ffffff`。请注意，颜色更改不会影响支付中心iframe本身，只会影响容纳iframe的灯箱的设置。
payment_widget_ui.lightbox.contentMargin	string	框架边距，默认值为`10px`。
payment_widget_ui.lightbox.spinner	string	加载指示器的动画类型。可为`xsolla`或`round`。默认值为`xsolla`。
payment_widget_ui.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/paystation4/?token=TOKEN。

打开支付UI的链接只能使用https://前缀。

如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN。

access_token参数包含隐私用户数据。请确保获取该参数时使用服务器对服务器通信。

要在iframe中打开支付UI：

实现postMessage机制从支付UI接收事件。
通过https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN链接打开支付UI，其中TOKEN是收到的令牌。

潜在问题：在iframe中打开支付UI时如果未显示某些支付系统要求的付款验证码复制按钮，请向iframe传入allow=“clipboard-read; clipboard-write; payment”属性。

示例：

Copy

Full screen

Small screen

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

在此方案中，所有订阅计划数据操作通过艾克索拉API客户端侧调用处理。这使您能直接从客户端获取计划列表、显示目录并启动支付UI。

如果您的项目包含订阅费用与首笔支付关联的订阅计划，请使用服务器侧方案获取支付UI打开链接。

要实现订阅目录显示和支付UI的打开：

使用客户端侧调用获取订阅计划列表（可选）：
- 如项目配置了基于订阅的产品，请使用按产品获取订阅计划的方法
- 如项目未配置基于订阅的产品，请使用获取订阅计划列表的方法

您可以本地存储计划列表并用这些数据构建目录，无需额外调用API获取计划列表。您也可以使用SDK库在自有界面中实现目录。现成的库提供可直接使用的数据结构和方法来与艾克索拉API交互，便于将艾克索拉产品集成到您的项目中。

在己侧实现目录显示。
实现令牌生成以打开订阅购买的支付UI。请使用获取支付UI链接的客户端侧调用完成此操作。
实现支付UI的打开。

按产品获取订阅计划的客户端侧方法

在应用程序的的客户端侧，请使用HTTP GET请求实现获取订阅计划列表：https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/products/{productId}/plans。

请求必须包含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调用。

以路径参数的形式指定：

projectId — 项目ID。可在发布商帐户项目名称旁边找到该参数。

productID — 基于订阅的产品ID。要获取该值，请联系您的客户成功经理或发送邮件至 csm@xsolla.com。

以请求参数的形式指定：

参数	类型	描述
plan_id	array of integers	计划ID。
plan_external_id	array of strings	计划的外部ID。可在发布商帐户中的商品目录 > 订阅 > 订阅计划 > 您的计划部分找到或通过列示所有计划API调用找到。
limit	integer	页面上元素数量的限制。默认显示15项。
offset	integer	元素编号，从该元素开始生成列表。默认从0开始数。
locale	string	接口语言使用符合ISO 639-1标准的两位小写字母表示。如果未传递此参数，则语言将根据用户的IP地址确定。如果传递的地理位置不在艾克索拉列表中，则默认使用英语。
country	string	用于识别用户国家/地区的ISO 3166-1 alpha-2两字母代码。此参数影响区域位置和货币的选择。如未传入此参数，则国家/地区由用户的IP地址决定。

Copy

Full screen

Small screen

1curl -X 'GET' \
2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/products/{productId}/plans?country=RU  ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

Copy

Full screen

Small screen

 1{
 2  "items": [
 3    {
 4      "plan_id": 54321,
 5      "plan_external_id": "PlanExternalId",
 6      "plan_group_id": "TestGroupId",
 7      "plan_type": "all",
 8      "plan_name": "Localized plan name",
 9      "plan_description": "Localized plan description",
10      "plan_start_date": "2021-04-11T13:51:02+03:00",
11      "plan_end_date": "2031-04-11T13:51:02+03:00",
12      "trial_period": 7,
13      "period": {
14        "value": 1,
15        "unit": "month"
16      },
17      "charge": {
18        "amount": 4.99,
19        "setup_fee": 0.99,
20        "currency": "USD"
21      },
22      "promotion": {
23        "promotion_charge_amount": 3.99,
24        "promotion_remaining_charges": 3
25      }
26    }
27  ],
28  "has_more": false
29}

获取订阅计划列表的客户端侧方法

在应用程序的的客户端侧，请使用HTTP GET请求实现获取订阅计划列表：https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/plans。

如应用程序使用用户名和密码认证，请使用Register new user和Auth by username and password API调用。
如应用程序使用通过社交网络认证，请使用Auth via social network API调用。

指定项目ID作为projectId路径参数。可在发布商帐户项目名称旁边找到该参数。

以请求参数的形式指定：

参数	类型	描述
plan_id	array of integers	计划ID。
plan_external_id	array of strings	计划的外部ID。可在发布商帐户中的商品目录 > 订阅 > 订阅计划 > 您的计划部分找到或通过列示所有计划API调用找到。
limit	integer	页面上元素数量的限制。默认显示15项。
offset	integer	元素编号，从该元素开始生成列表。默认从0开始数。
locale	string	接口语言使用符合ISO 639-1标准的两位小写字母表示。如果未传递此参数，则语言将根据用户的IP地址确定。如果传递的地理位置不在艾克索拉列表中，则默认使用英语。
country	string	用于识别用户国家/地区的ISO 3166-1 alpha-2两字母代码。此参数影响区域位置和货币的选择。如未传入此参数，则国家/地区由用户的IP地址决定。

Copy

Full screen

Small screen

1curl -X 'GET' \
2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/plans?country=RU  ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

Copy

Full screen

Small screen

 1{
 2  "items": [
 3    {
 4      "plan_id": 54321,
 5      "plan_external_id": "PlanExternalId",
 6      "plan_group_id": "TestGroupId",
 7      "plan_type": "all",
 8      "plan_name": "Localized plan name",
 9      "plan_description": "Localized plan description",
10      "plan_start_date": "2021-04-11T13:51:02+03:00",
11      "plan_end_date": "2031-04-11T13:51:02+03:00",
12      "trial_period": 7,
13      "period": {
14        "value": 1,
15        "unit": "month"
16      },
17      "charge": {
18        "amount": 4.99,
19        "setup_fee": 0.99,
20        "currency": "USD"
21      },
22      "promotion": {
23        "promotion_charge_amount": 3.99,
24        "promotion_remaining_charges": 3
25      }
26    }
27  ],
28  "has_more": false
29}

获取链接来打开支付UI的客户端方法

在应用程序的的客户端侧，请使用HTTP POST请求实现支付UI的打开：https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions/buy。

如应用程序使用用户名和密码认证，请使用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示例：

请求正文参数：

参数	类型	描述
plan_external_id	string	必需。订阅计划的外部ID。可在发布商帐户 > 商品目录 > 订阅 > 订阅计划部分找到。
settings	object	带有自定义项目设置的对象。
settings.ui	object	带有界面设置相关数据的对象。
settings.ui.theme	string	支付UI的外观主题。可以是`default`、`default_dark`或自定义主题ID。
settings.ui.version	string	设备类型。可以是`desktop`（默认）或`mobile`。
settings.ui.desktop	object	带有对桌面版本有效的界面设置相关数据的对象。
settings.ui.desktop.header	object	带有标题设置相关数据的对象。
settings.ui.desktop.header.close_button	boolean	是否在支付中心桌面端显示关闭按钮。该按钮将关闭支付中心并将用户重定向到`settings.return_url`参数中指定的URL。默认为`false`。
settings.ui.desktop.header.is_visible	boolean	标题在支付UI上是否可见。
settings.ui.desktop.header.type	string	标头外观。可以是`compact`（游戏名和用户ID不在标头中显示）或`normal`。
settings.ui.desctop.header.visible_logo	boolean	如果为`true`，标题中将显示Logo（请先把Logo文件提供给您的客户成功经理）。
settings.ui.desktop.header.visible_name	boolean	标题中是否显示项目名称。
settings.ui.desktop.header.type	string	如何显示标题。可以是`compact`（隐藏项目名称和用户ID）或`normal`（默认）。
settings.ui.mobile.header.close_button	boolean	是否在支付中心移动版中显示关闭按钮。该按钮将关闭支付中心并将用户重定向到`settings.return_url`参数中指定的URL。默认为`false`。
settings.ui.mode	string	支付中心中的界面模式。只能是`user_account`：标头仅包含帐户导航菜单，而没有用于选择产品或进行付款的任何选项。此模式仅在桌面版中可用。
settings.currency	string	首选支付币种。三字母ISO 4217货币代码。
settings.external_id	string	游戏中的交易ID。值对于每个用户付款必须唯一。
settings.payment_method	integer	支付方式ID。要获取支付方式ID列表，您可以前往发布商帐户。
settings.return_url	string	用户在支付过后重定向到的页面。参数`user_id`、`foreigninvoice`、`invoice_id`和`status`将自动添加到链接中。
settings.redirect_policy	object	重定向政策设置（对象）。
settings.redirect_policy.redirect_conditions	string	支付后将用户重定向到返回URL的支付状态。可以是`none`、`successful`、`successful_or_canceled`或`any`。
settings.redirect_policy.delay	integer	延迟时间（单位为秒），经过该时间后用户将自动重定向至返回URL。
settings.redirect_policy.status_for_manual_redirection	string	支付后将用户重定向到返回URL的支付状态。可以是`none`、`successful`、`successful_or_canceled`或`any`。
settings.redirect_policy.redirect_button_caption	string	手动重定向按钮上的文字。

如需要，传入自定义补充参数。

Copy

Full screen

Small screen

 1curl -X 'POST' \
 2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/buy?country=RU  ' \
 3  -H 'accept: application/json' \
 4  -H 'Authorization: Bearer client_user_jwt'
 5
 6  {
 7    "plan_external_id": "PlanExternalId",
 8    "settings": {
 9      "ui": {
10        "size": "large",
11        "theme": "string",
12        "version": "desktop",
13        "desktop": {
14          "header": {
15            "is_visible": true,
16            "visible_logo": true,
17            "visible_name": true,
18            "type": "compact",
19            "close_button": true
20          }
21        },
22        "mobile": {
23          "mode": "saved_accounts",
24          "footer": {
25            "is_visible": true
26          },
27          "header": {
28            "close_button": true
29          }
30        },
31        "mode": "user_account"
32        }
33      },
34      "currency": "string",
35      "locale": "string",
36      "external_id": "string",
37      "payment_method": 1,
38      "return_url": "string",
39      "redirect_policy": {
40        "redirect_conditions": "none",
41        "delay": 0,
42        "status_for_manual_redirection": "none",
43        "redirect_button_caption": "string"
44      }
45    }

Copy

Full screen

Small screen

1{
2  "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
3}

打开支付UI

如需允许用户切换订阅计划，请在项目中配置相关设置，并按照如何允许用户更改订阅计划的说明实现支付UI的打开。

示例：异步脚本加载

Copy

Full screen

Small screen

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

艾克索拉团队创建了一个小组件，帮助您简化将支付UI集成到网站的过程。小组件脚本在我们的GitHub存储库中提供。

用于脚本初始化的参数列表：

参数	类型	描述
access_token	string	令牌，通过API接收。必需。
sandbox	boolean	设置为`true`以测试支付流程，将使用`sandbox-secure.xsolla.com`而不是`secure.xsolla.com`。
lightbox	object	带有选项列表的对象，可用于打开lightbox（桌面版本）。
payment_widget_ui.lightbox.width	string	Lightbox框架的高度。如果为`null`，则取决于支付中心的高度。默认值为`null`。
payment_widget_ui.lightbox.height	string	Lightbox框架的高度。如果为`null`，则取决于支付中心的高度。默认值为`100%`。
payment_widget_ui.lightbox.zIndex	integer	控制垂直堆叠顺序的属性，默认值为`1000`。
payment_widget_ui.lightbox.overlayOpacity	integer	小组件背景的不透明度（`0` — 完全透明，`1` — 完全不透明）。默认值为60% (`.6`)。
payment_widget_ui.lightbox.overlayBackground	string	浮层背景色，默认值为`#000000`。
payment_widget_ui.lightbox.modal	boolean	如为`true`，lightbox框架不可关闭，默认值为`false`。
lightbox.closeByClick	boolean	如为`true`，单击浮层将关闭lightbox，默认值为`true`。
lightbox.closeByKeyboard	boolean	如为`true`，按ESC键将关闭lightbox，默认值为`true`。
payment_widget_ui.lightbox.contentBackground	string	框架的背景，默认值为`#ffffff`。请注意，颜色更改不会影响支付中心iframe本身，只会影响容纳iframe的灯箱的设置。
payment_widget_ui.lightbox.contentMargin	string	框架边距，默认值为`10px`。
payment_widget_ui.lightbox.spinner	string	加载指示器的动画类型。可为`xsolla`或`round`。默认值为`xsolla`。
payment_widget_ui.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/paystation4/?token=TOKEN。

打开支付UI的链接只能使用https://前缀。

如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN。

access_token参数包含隐私用户数据。请确保获取该参数时使用服务器对服务器通信。

要在iframe中打开支付UI：

实现postMessage机制从支付UI接收事件。
通过https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN链接打开支付UI，其中TOKEN是收到的令牌。

示例：

Copy

Full screen

Small screen

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

在此方案中，订阅目录直接显示在艾克索拉支付UI中，无需为订阅计划列表开发自定义界面。这种方式简化了集成流程，并确保订阅计划数据自动更新。

如需允许用户切换订阅计划，请在项目中配置相关设置，并按照如何允许用户更改订阅计划的说明实现支付UI的打开。

要设置令牌生成并打开包含订阅目录的支付UI：

实现通过服务器侧创建令牌API调用获取令牌。在请求中传入以下参数：
- user.id — 授权系统中的用户ID。
- user.email — 用户邮箱。必须符合RFC 822协议的标准。
- settings.project_id — 项目ID。可在发布商帐户中项目名称旁边找到此参数。

请求示例：

Copy

Full screen

Small screen

 1{
 2    "user": {
 3        "name": {
 4            "value": "j.smith@email.com"
 5        },
 6        "id": {
 7            "value": "123a345b678c091d"
 8        }
 9    },
10    "settings": {
11        "project_id": 177226
12    }
13}

通过以下方式之一实现支付UI的打开：

示例：异步脚本加载

Copy

Full screen

Small screen

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

艾克索拉团队创建了一个小组件，帮助您简化将支付UI集成到网站的过程。小组件脚本在我们的GitHub存储库中提供。

用于脚本初始化的参数列表：

参数	类型	描述
access_token	string	令牌，通过API接收。必需。
sandbox	boolean	设置为`true`以测试支付流程，将使用`sandbox-secure.xsolla.com`而不是`secure.xsolla.com`。
lightbox	object	带有选项列表的对象，可用于打开lightbox（桌面版本）。
payment_widget_ui.lightbox.width	string	Lightbox框架的高度。如果为`null`，则取决于支付中心的高度。默认值为`null`。
payment_widget_ui.lightbox.height	string	Lightbox框架的高度。如果为`null`，则取决于支付中心的高度。默认值为`100%`。
payment_widget_ui.lightbox.zIndex	integer	控制垂直堆叠顺序的属性，默认值为`1000`。
payment_widget_ui.lightbox.overlayOpacity	integer	小组件背景的不透明度（`0` — 完全透明，`1` — 完全不透明）。默认值为60% (`.6`)。
payment_widget_ui.lightbox.overlayBackground	string	浮层背景色，默认值为`#000000`。
payment_widget_ui.lightbox.modal	boolean	如为`true`，lightbox框架不可关闭，默认值为`false`。
lightbox.closeByClick	boolean	如为`true`，单击浮层将关闭lightbox，默认值为`true`。
lightbox.closeByKeyboard	boolean	如为`true`，按ESC键将关闭lightbox，默认值为`true`。
payment_widget_ui.lightbox.contentBackground	string	框架的背景，默认值为`#ffffff`。请注意，颜色更改不会影响支付中心iframe本身，只会影响容纳iframe的灯箱的设置。
payment_widget_ui.lightbox.contentMargin	string	框架边距，默认值为`10px`。
payment_widget_ui.lightbox.spinner	string	加载指示器的动画类型。可为`xsolla`或`round`。默认值为`xsolla`。
payment_widget_ui.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/paystation4/?token=TOKEN。

打开支付UI的链接只能使用https://前缀。

如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN。

access_token参数包含隐私用户数据。请确保获取该参数时使用服务器对服务器通信。

要在iframe中打开支付UI：

实现postMessage机制从支付UI接收事件。
通过https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN链接打开支付UI，其中TOKEN是收到的令牌。

示例：

Copy

Full screen

Small screen

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

在艾克索拉支付中心里显示订阅目录的示例：

在此方案中，所有目录元素和购买逻辑都直接在建站器中配置，无需使用API。

要添加订阅销售，您需要在网站上添加一个按钮并为其配置购买订阅操作。可以在页眉、卡片网格和游戏版本区块中使用可自定义的按钮。

建议使用卡片网格区块进行订阅销售，因为它为卡片本身及其布局提供了丰富的自定义选项。

在网站上启用订阅购买功能：

在发布商帐户中打开您的项目，然后前往商店 > 网站部分。
选择您的网站并点击打开建站器。
在建站器的主区域，选择想添加新区块的位置并点击添加区块。
添加卡片网格区块并进行设置。例如，指定标题、设置背景及添加文本。
在建站器的主区域，配置卡片网格：

1. 要垂直或水平拆分任何网格区域，单击区域左上角的垂直或水平线图标。

1. 要设置区域的高度或宽度，请拖动║或═图标。

进入卡片设置。方法是点击⚙图标。

向卡片添加订阅购买按钮：

1. 单击添加按钮。

1. 在操作下拉列表中，选择购买订阅。
2. 在订阅计划下拉列表中，选择您之前创建的计划。

列表中只显示定期付费计划类型的订阅。

如果需要的计划不在列表中，请单击添加新计划并在发布商帐户中设置订阅计划。

1. 更改按钮样式（可选）。

自定义订阅购买按钮文本（可选）：

1. 在建站器的主区域，点击按钮文本。
2. 输入所需文本。默认情况下，按钮显示订阅价格或试用天数（如果在所选订阅计划中设置了试用期）。编辑文本时，您还可以使用以下变量来提供订阅价格或试用期：

1. - {priceDefault}— 基础价格。如有折扣，此值将显示删除线。
  - {pricePromo} — 折扣后的最终订阅价格。
  - {trial} — 试用天数。

默认情况下，文本按以下规则自动确定：

{trial} day(s) for free — 如果订阅有试用期。
{priceDefault} {pricePromo} per month — 如果订阅没有试用期，但有折扣。
{priceDefault} per month — 如果订阅没有试用期且无折扣。
Manage plan — 如果当前已认证用户有活跃订阅。此文本无法在建站器中更改，即使手动为按钮设置了自定义文本也会如此显示。

要恢复默认文本，点击按钮文本，删除自定义内容后点击页面空白处。

配置其他卡片设置。例如，添加文本、图片和背景。
配置网格中的其他卡片。

定期循环订阅示例：

带试用期的订阅示例：

带折扣的订阅示例：

订阅价格表示例：

完成网站设置：
- 配置网站视觉主题。
- 添加其他网站区块。方法是单击添加区块并选择要显示的区块。完整区块列表可参阅相关说明。
- 编辑区块内容。方法是在建站器主界面中添加图片并编辑用户将看到的文本。
- 设置SEO和本地化设置（可选）。
- 添加更多网站页面（可选）。
发布网站使其公开可访问：

1. 在建站器右上角，单击发布。

1. 勾选需要发布的页面。

1. 确认网站已准备就绪，然后单击发布。

如果无法发布网站，请确保满足以下所有条件：

网站上没有空白区段（红色标记的部分）。
已签署与艾克索拉的许可协议。
主页已发布或已勾选待发布。主页发布前无法发布子页面。

高级设置（可选）：
1. 1. 前往商店 > 网站部分，在您的网站窗格上单击配置。
1. 1. 要连接自定义域名：前往网站设置 > 域名部分，修改艾克索拉域名或连接您自己的域名。
1. 1. 要监控网站成效：前往网站设置 > 应用部分，选择并连接推广和分析服务。

感谢您的反馈！

我们会查看您的留言并运用它改进用户体验。

上次更新时间: 2025年12月12日

发现了错别字或其他内容错误？请选择文本，然后按Ctrl+Enter。

生成令牌以在支付方式选择页面打开支付UI
生成令牌以在输入支付数据页面打开支付UI
打开支付UI
按产品获取订阅计划的客户端侧方法
获取订阅计划列表的客户端侧方法
获取链接来打开支付UI的客户端方法
打开支付UI

Your browser is not supported. Please try a different browser

设置订阅目录显示和购买功能

生成令牌以在支付方式选择页面打开支付UI

生成令牌以在输入支付数据页面打开支付UI

打开支付UI

access_token

sandbox

lightbox

payment_widget_ui.lightbox.width

payment_widget_ui.lightbox.height

payment_widget_ui.lightbox.zIndex

payment_widget_ui.lightbox.overlayOpacity

payment_widget_ui.lightbox.overlayBackground

payment_widget_ui.lightbox.modal

lightbox.closeByClick

lightbox.closeByKeyboard

payment_widget_ui.lightbox.contentBackground

payment_widget_ui.lightbox.contentMargin

payment_widget_ui.lightbox.spinner

payment_widget_ui.lightbox.spinnerColor

childWindow

childWindow.target

按产品获取订阅计划的客户端侧方法

plan_id

plan_external_id

limit

offset

locale

country

获取订阅计划列表的客户端侧方法

plan_id

plan_external_id

limit

offset

locale

country

获取链接来打开支付UI的客户端方法

plan_external_id

settings

settings.ui

settings.ui.theme

settings.ui.version

settings.ui.desktop

settings.ui.desktop.header

settings.ui.desktop.header.close_button

settings.ui.desktop.header.is_visible

settings.ui.desktop.header.type

settings.ui.desctop.header.visible_logo

settings.ui.desktop.header.visible_name

settings.ui.desktop.header.type

settings.ui.mobile.header.close_button

settings.ui.mode

settings.currency

settings.external_id

settings.payment_method

settings.return_url

settings.redirect_policy

settings.redirect_policy.redirect_conditions

settings.redirect_policy.delay

settings.redirect_policy.status_for_manual_redirection

settings.redirect_policy.redirect_button_caption

打开支付UI

access_token

sandbox

lightbox

payment_widget_ui.lightbox.width

payment_widget_ui.lightbox.height

payment_widget_ui.lightbox.zIndex

payment_widget_ui.lightbox.overlayOpacity

payment_widget_ui.lightbox.overlayBackground

payment_widget_ui.lightbox.modal

lightbox.closeByClick

lightbox.closeByKeyboard

payment_widget_ui.lightbox.contentBackground

payment_widget_ui.lightbox.contentMargin

payment_widget_ui.lightbox.spinner

payment_widget_ui.lightbox.spinnerColor

childWindow

childWindow.target

access_token