设置支付UI的打开

根据具体项目身份认证设置,您可以使用以下方式之一打开支付UI:

注意
由于获取链接来打开支付UI的客户端侧方法不允许在己侧管理价格及针对特定用户设置订阅价格,请勿使用它来销售订阅费用与首笔支付关联的订阅计划。
注:
如要允许用户在您的项目中更改订阅计划,请联系您的客户成功经理或发送邮件至csm@xsolla.com来设置正确的支付UI操作。

通过服务器创建令牌API调用

  1. 通过以下方式之一获取令牌以打开支付UI:
  2. 实现支付UI的打开方式:

显示支付方式选择页面

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

注:
如果项目中设置了订阅费用与首笔支付关联的计划,还需要传入以下参数:
  • purchase.checkout.amount,包含订阅计划的价格
  • purchase.checkout.currency,包含货币值
Copy
Full screen
Small screen

    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列表,可在发布商帐户中前往支付中心 > 付款方式部分,或向您的客户成功经理索取。
    注:
    如果项目中设置了订阅费用与首笔支付关联的计划,还需要传入以下参数:
    • purchase.checkout.amount,包含订阅计划的价格
    • purchase.checkout.currency,包含货币值

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

    Copy
    Full screen
    Small screen

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

    支付数据输入页面示例:

    通过客户端API方法

    1. 使用客户端API方法实现获取链接来打开支付UI。
    2. 通过以下方式之一实现支付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编码令牌。要获取该令牌:

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

    指定country作为请求参数,值为符合ISO 3166-1 alpha-2标准的用户国家/地区两字母代码。该参数影响区域位置和货币。如未传入该参数,则国家/地区由用户的IP地址决定。

    在请求中传入如下参数:

    支付UI示例:

    支付UI示例:

    请求正文参数:

    参数类型描述
    plan_external_id
    string必需。订阅计划的外部ID。可在发布商帐户 > 订阅 > 订阅计划部分找到。
    settings
    object带有自定义项目设置的对象。
    settings.ui
    object带有界面设置相关数据的对象。
    settings.ui.theme
    string支付UI的外观主题。可以是defaultdefault_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
    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列表,您可以前往发布商帐户,或使用获取支付方式API调用。
    settings.return_url
    string用户在支付过后重定向到的页面。参数user_idforeigninvoiceinvoice_idstatus将自动添加到链接中。
    settings.redirect_policy
    object重定向政策设置(对象)。
    settings.redirect_policy.redirect_conditions
    string支付后将用户重定向到返回URL的支付状态。可以是nonesuccessfulsuccessful_or_canceledany
    settings.redirect_policy.delay
    integer延迟时间(单位为秒),经过该时间后用户将自动重定向至返回URL。
    settings.redirect_policy.status_for_manual_redirection
    string支付后将用户重定向到返回URL的支付状态。可以是nonesuccessfulsuccessful_or_canceledany
    settings.redirect_policy.redirect_button_caption
    string手动重定向按钮上的文字。

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

    Copy
    Full screen
    Small screen

      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
                }
              },
              "mode": "user_account"
              }
            },
            "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"
            }
          }

      Copy
      Full screen
      Small screen

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

        使用Pay Station Embed

        在网站页面上添加一个脚本来打开支付UI小组件。脚本的详细描述可在GitHub存储库中找到。

        示例:异步脚本加载

        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事件。您可以将事件发送到分析系统。如要在分析系统中设置事件处理,请联系您的客户成功经理或发送邮件至csm@xsolla.com

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

        参数类型描述
        access_token
        string令牌,通过服务器创建令牌API调用接收或通过链接接收(如使用客户端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的打开,请使用此链接:https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN,其中ACCESS_TOKEN是通过创建令牌方法获取的令牌。实现打开支付界面的客户端方法时也可获得一个含令牌的现成链接。

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

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

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

        在Iframe中

        需在您的代码侧实现以下机制:

        • 检查设备类型(桌面或移动设备)并将其包含在令牌的settings.ui.version参数中发送。
        • 通过postMessage获取支付UI的事件。可将这些事件发送给分析系统。要在分析系统中设置事件处理,请联系您的客户成功经理或发送邮件至csm@xsolla.com

        要在iframe中打开支付UI,请使用以下链接:https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN,其中ACCESS_TOKEN是通过创建令牌方法获取的令牌。实现打开支付界面的客户端方法时也可获得一个含令牌的现成链接。

        测试目的请使用此URL:https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN

        在新窗口中

        要在新窗口中打开支付UI,请使用以下链接:https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN,其中ACCESS_TOKEN是通过创建令牌方法获取的令牌。实现打开支付界面的客户端方法时也可获得一个含令牌的现成链接。

        测试目的请使用此URL:https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN

        您的进度
        感谢您的反馈!
        上次更新时间: 2023年10月10日

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

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