集成付款解决方案

要跟踪协作推广者带来的引荐数并向其支付佣金,需先集成艾克索拉支付中心。要求:

  1. 支付中心集成在经过性能优化的着陆页上。
  2. 支付中心是通过流量联盟活动导流的游戏着陆页上使用的唯一付款方式。

获取令牌

要打开支付UI,您需要先获取令牌。令牌是一个包含游戏和用户加密数据的字符串。您需要实现获取令牌来识别用户身份以允许其进行购买。

在您的应用程序后端,实现获取用户认证令牌。方法是使用包含基本HTTP认证的HTTP POST请求,并在请求正文中传入必需参数。

API参考
查看完整参数列表。

令牌的有效期是自最后一次调用艾克索拉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)。

获取用户认证令牌请求的示例

Copy
Full screen
Small screen

    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>"
          }
        }
      }'

    响应中收到的用户认证令牌示例

    Copy
    Full screen
    Small screen

      {
          "token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
      }

      打开支付UI

      注:

      签署与艾克索拉的协议之前,只支持在沙盒模式下测试支付过程。如遇到错误,请参阅错误描述

      要以沙盒模式打开支付UI,请使用下列URLhttps://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN,其中ACCESS_TOKEN是在上一步中获得的令牌。

      新建窗口

      要在新窗口中打开支付UI,请使用以下URL:https://sandbox-secure.xsolla.com/paystation2/?access_token=TOKEN,其中TOKEN是获得的令牌。

      注:
      使用上面的链接在沙盒模式下打开支付UI。项目发布后,请使用此URL:https://secure.xsolla.com/paystation2/?access_token=TOKEN

      您也可以通过其他方式打开支付UI:

      • 使用Pay Station Embed。缺点:在游戏内浏览器(WebView)中打开可能会有问题。
      • 在iframe中打开。缺点:在游戏内浏览器(WebView)或应用程序的移动版本中打开可能会有问题。

      Pay Station Embed

      注意
      此支付UI打开方式不支持销售游戏密钥。要销售游戏密钥,请按照说明进行操作。

      示例:异步脚本加载

      Copy
      Full screen
      Small screen

      <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
      stringLightbox框架的高度。如果为null,则取决于支付中心的高度。默认值为null
      lightbox.height
      stringLightbox框架的高度。如果为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加载指示器的动画类型。可为xsollaround。默认值为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

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

      如要进行测试,请使用以下URL:https://sandbox-secure.xsolla.com/paystation3/?access_token=TOKEN

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

      Iframe

      要在iframe中打开支付UI:

      1. 实现postMessage机制以接收支付UI的事件。
      2. 在使用支付组中的API调用创建订单时获取令牌。在请求中传入:
        • 设备类型(桌面或移动设备)(settings.ui.version参数中)
        • 支付UI大小(settings.ui.size参数中):

      支付中心大小Iframe宽度
      大(默认)670–850 px
      590–740 px
      510–630 px

      1. 使用链接https://sandbox-secure.xsolla.com/paystation2/?access_token=TOKEN打开支付UI,其中TOKEN是收到的令牌。

      设置Webhook

      如希望接收事件通知(如支付状态变化),请在发布商帐户中设置Webhook:

      1. 发布商帐户中打开您的项目。
      2. 在侧边栏中单击项目设置,然后前往Webhooks
      3. Webhooks开关设置为
      4. 指定Webhook URL。
      5. 默认会生成一个用于项目Webhook签名的密钥。如要生成一个新密钥,请单击刷新图标。
      6. 单击保存设置

      推荐实现以下Webhook:

      要确认已收到Webhook,您的服务器必须作出如下响应:

      • 不带消息正文的HTTP代码204。
      • 描述问题的HTTP代码400(如果指定用户未找到或传入的签名无效)。

      注:
      关于Webhook的更多信息,请参阅API参考

      测试支付流程

      要测试支付过程,您可以使用沙盒模式。沙盒模式是一个独立环境,支持除真实付款和拒绝支付外实时环境的所有功能。获得令牌后,您可以通过发送"mode":"sandbox"来进入沙盒模式。

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

      在沙盒模式下,可使用以下方式测试付款过程:

      测试银行卡支付

      1. 以沙盒模式打开支付UI
      2. 选择信用卡/借记卡付款方式组。
      3. 输入银行卡详细信息。在其余字段中输入任意值。您也可以指定不正确的细节(卡号或到期日)以生成错误。
      4. 单击立即支付
      测试银行卡列表
      查看测试银行卡列表。
      注:

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

      • 用户所在国家是美国或加拿大。
      • 发卡行识别码(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沙盒模式创建一个帐户:

      1. 打开PayPal开发者网站
      2. 登录您的帐户或新建帐户。
      3. 前往Sandbox accounts选项卡。
      4. Sandbox test accounts页面上单击Create account
      5. 选择Personal (Buyer Account)帐户类型并选择国家/地区。
      6. 单击Create

      创建的帐户在沙盒帐户列表中显示。

      您也可以使用现有沙盒帐户的信息:

      Email IDSystem Generated Password
      sb-xmxij16980134@business.example.comoi9_m_KW
      sb-p7pju16979920@business.example.com7%%p8ioS

      进行测试性支付

      1. 在沙盒模式下打开支付UI
      2. 选择PayPal支付方式。
      3. Mock Response Code字段中,输入0或将该字段留空。
      4. 邮政编码字段中,任意输入5个数字。

      1. 点击支付。您将跳转到一个PayPal帐户登录窗口。
      2. 输入沙盒帐户的信息:输入Email ID作为邮箱地址,输入System Generated Password作为密码。要找到该信息:
        1. PayPal开发者网站上登录您的帐户。
        2. 前往Sandbox accounts选项卡。
        3. Sandbox test accounts页面上选择一个沙盒帐户。
        4. 单击•••,然后选择View/Edit account。您将在随后打开的模态窗口中看到该信息。
      3. 完成测试支付。

      注意
      请参阅测试单次购买和保存的PayPal帐户的全部可用场景描述

      上线

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

      1. 请确保已签署艾克索拉许可协议
      2. 删除获取令牌时请求正文中的"mode":"sandbox"参数。
      3. 通过以下链接打开支付UI:https://secure.xsolla.com/paystation3/?access_token=TOKEN

      注意
      首次完成真实付款后,严格沙盒付款政策即生效。在沙盒模式下进行支付仅适用于发布商帐户公司设置 > 用户部分中指定的用户。
      您的进度
      感谢您的反馈!
      上次更新时间: 2021年7月5日

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

      报告问题
      我们非常重视内容质量。您的反馈将帮助我们做得更好。
      请留下邮箱以便我们后续跟进
      感谢您的反馈!