快速指南

集成过程

要集成付款解决方案：

在发布商帐户中创建项目。一个项目对应一个游戏。如有多个游戏，请为每个游戏各创建一个项目。
将要销售的商品添加到艾克索拉侧的目录。
测试创建模拟用户要支付的订单。
进行测试性购买并设置通知。
在发布商帐户中签署与艾克索拉的协议以开始处理真实支付。

您可以在集成的任意阶段签署许可协议，但请知晓审核过程最长可能需要3个工作日。

创建目录

虚拟物品是用户可使用真实或虚拟货币购买的游戏内内容。在艾克索拉侧创建虚拟物品目录可以自定义区域价格和限制，还可以使用艾克索拉的促销活动系统及定期增加和更新的其他功能。

创建虚拟物品

获取物品列表

要获取物品列表，请调用获取虚拟物品列表API方法：

在请求头中，请传入默认用于授权的艾克索拉登录管理器JWT（持有者令牌）。要测试该API方法的调用，可使用以下测试令牌：Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI。
在project_id路径参数中，请传入可在发布商帐户中找到的项目ID：

在响应中，您将收到项目中创建的虚拟物品的详细信息。后续订单创建中您需要该物品的SKU来传入items.sku参数。

创建订单

订单由用户要在商店中购买的商品组成。支付订单后，用户将收到商品。要进行支付，用户必须授权登入游戏。

选择游戏适合的集成方式，然后查看相应的设置说明。

特点	服务器侧	客户端侧
有服务器	您需要有自己的服务器来获取令牌及控制服务器上的负载。	您无需自己有服务器。
决定用户的国家/地区	您需要在支付令牌中传入国家/地区或IP地址。这会影响可用的支付方式。	艾克索拉根据IP地址决定用户的国家/地区。
决定支付货币	如未在令牌中传入货币，则由国家/地区决定。如在令牌中传入了货币，则用户用该货币进行支付。	货币由国家/地区决定。

调用为购买创建支付令牌API方法，然后在该方法中传入用户和商品信息。您可以使用该API调用一次销售单个或多个商品。

要使用沙盒模式，请在获取令牌的请求正文中传入“sandbox”: true参数。

user_id参数的值：

测试时，可在此参数中传入任何字符。
要接受真实付款，请在此参数中传入您系统中的用户ID。该ID在用户验证Webhook中传入。

请求示例：

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://store.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    },
    "sandbox": true
  }'

集成艾克索拉登录管理器：

使用配置的登录管理器方法创建并保存身份认证令牌以接收支付令牌。支付令牌用于打开支付UI及进行支付。

要测试支付流程，请通过使用指定商品创建订单API调用创建订单：

如要在API文档网站上进行测试，请单击Try it打开创建请求的界面。
在Security区块的Bearer Token字段中，输入完成认证过程时获得的令牌。
在Body区块中，传入商品数量等订单详细信息。要访问沙盒模式，请传入"sandbox": true。
在Parameters区块中，传入：
- project_id — 可在发布商帐户中找到的项目ID。
- item_sku — 商品SKU。

在响应中，您将收到后续操作需要的数据：

token — 支付令牌

请求示例：

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

要调用艾克索拉API，您可以使用针对各游戏引擎和平台的现成SDK：

进行测试性购买

测试不需要从真实银行账户中扣款，您可以使用我们的测试银行卡进行。

与艾克索拉签订合约之前，测试支付过程仅在沙盒模式下可用。

在沙盒模式下打开支付UI

要在新窗口中打开支付UI，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN，其中TOKEN是创建订单时获得的令牌。

要使用其他方法打开支付UI，请参阅文档。

进行测试性支付

在沙盒模式下打开支付UI。
选择银行卡付款方式。
输入银行卡详细信息。对于其他字段（如名称或地址），可输入任意数据。您也可以指定不正确的细节（卡号或到期日）以测试是否会产生错误。
单击支付。

测试银行卡列表

查看测试银行卡列表。

邮政编码信息

如符合以下条件之一，除卡片详细信息外，还需指定邮政编码：

用户所在国家是美国或加拿大。
发卡行识别码(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测试一次性付款和通过保存的支付方式付款。

设置Webhook

如在服务器侧设置集成，需通过在对Webhook的响应中发送相应代码来验证创建的订单。如在服务器侧设置集成，可通过Webhook来接收已配置事件的通知（如支付状态更改等）。

要启用Webhook接收：

在发布商帐户中打开您的项目。
在侧边栏中单击项目设置，然后前往Webhooks选项卡。
在Webhook服务器字段中指定要接收Webhook的服务器URL，格式为https://example.com。您也可以指定在工具中找到的URL来用于测试。
默认会生成一个用于项目Webhook签名的密钥。如要生成新密钥，请点击刷新图标。
单击启用Webhook。

PHP SDK

使用现成的类来处理Webhook。

要测试Webhook，您可以选择任意专门网站（如webhook.site）或平台（如ngrok）。

要接收用户验证和成功支付的通知，请配置以下Webhook：

用户验证 — 通知确认用户已在游戏中注册。
支付 — 通知用户已付款。

关于设置和测试Webhook的详细信息，请参阅文档。

配置Webhook监听器

Webhook监听器是一个程序代码，可以在指定的URL地址接收传入的Webhook、生成签名及向艾克索拉Webhook服务器发送响应。

生成签名及向Webhook发送响应的信息

生成签名

接收Webhook时，应确保数据传输的安全性。为此，必须从Webhook数据生成一个签名并确保它与HTTP请求头中发送的签名匹配。要生成签名：

将请求正文中的JSON与项目密钥串联起来。
对第一步中得到的字符串应用SHA-1加密散列函数。

向Webhook发送响应

要确认收到Webhook，您的服务器必须返回：

200、201或204 HTTP代码（成功响应时）。
带问题描述的400 HTTP代码（如未找到指定用户或传入的签名无效）。

如您的服务器发生临时问题，您的Webhook处理程序也可以返回5xx代码。如果未收到对订单成功支付或订单取消Webhook的响应，或收到了包含5xx代码的响应，将根据以下规则重新发送Webhook：

间隔5分钟尝试2次
间隔15分钟尝试7次
间隔60分钟尝试10次

自首次尝试起，12小时内最多尝试发送Webhook20次。如果未收到对支付Webhook的响应或收到了包含5xx代码的响应，也将尝试重新发送Webhook且重试的间隔逐渐拉长。12小时内最多尝试12次。如果未收到对用户验证Webhook的响应或收到了包含400或5xx代码的响应，将不会重新发送用户验证Webhook。该情况下会向用户显示一个错误，且不会发送支付和订单成功支付Webhook。

发布

签署许可协议之前，只能以沙盒模式打开支付UI。

签署许可协议

签署许可协议后即可通过艾克索拉支持的付款方式接收真实付款。要签署许可协议：

打开您的发布商帐户。
在侧边栏中，前往协议与税务信息 > 协议部分。
在许可协议选项卡中单击填写申请表。
在相应字段中提供您的信息。

您的申请将在3个工作日内进行审核。如在审核过程中有任何问题，艾克索拉将联系申请中所写的联系人。艾克索拉侧的审核程序完成后，您的协议状态将更改为已签署。

切换到生产环境

首次完成真实付款后，严格沙盒付款政策即生效。在沙盒模式下进行支付仅适用于发布商帐户里公司设置 > 用户部分中指定的用户。

完成前面的步骤后，即可开始接收真实付款：

请确保已签署艾克索拉许可协议。
删除获取令牌时请求正文中的“sandbox”: true参数。
通过以下链接打开支付UI：https://secure.xsolla.com/paystation4/?token=TOKEN。

本指南介绍快速开始集成所需的最低设置。如有任何问题，请通过页面右下角的艾克索拉聊天与我们联系，或发送邮件至 csm@xsolla.com联系客户成功经理。

感谢您的反馈！

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

为此页面评分

不想回答

感谢您的反馈！

上次更新时间: 2024年3月18日

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

Your browser is not supported. Please try a different browser

付款

快速指南

集成过程

创建目录

创建虚拟物品

获取物品列表

创建订单

进行测试性购买

在沙盒模式下打开支付UI

进行测试性支付

设置Webhook

配置Webhook监听器

生成签名

向Webhook发送响应

发布

签署许可协议

切换到生产环境

本文对您的有帮助吗？

为此页面评分

感谢您的反馈！