Set up opening of the payment UI

Depending on project authentication settings, you can use one of the following to open the payment UI:

Notice
Since the client-side method of getting a link to open a payment UI does not allow you to manage prices on your side and set the subscription price for a specific user, do not use it to sell a subscription with a subscription fee associated with the first payment.
Note
If you want to allow the user to change the plan in your project, contact your Customer Success Manager or email to csm@xsolla.com to set up the correct operation of the payment UI.

Via server-side Create token API call

  1. Implement getting a token to open the payment UI in one of the following ways:
  2. Implement how the payment UI is opened:

With the display of the payment method selection page

To make the payment UI display the payment method selection page when opened, pass the purchase.subscription.plan_id parameter with the ID of the selected plan to the Create token API call. Pass additional customization parameters if needed.
Note
If plans with a subscription fee associated with the first payment are set in your project, you also need to pass the following parameters:
  • purchase.checkout.amount with the price of the subscription plan
  • purchase.checkout.currency with the currency value
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"
        }
      }
    }'
    

    Example of payment method selection page:

    With the display of payment data entry page

    To make the payment UI display the payment data entry page when opened, pass the following parameters in the Create token API call:
    • purchase.subscription.plan_id with the ID of the selected plan.
    • settings.payment_method with the payment method ID. To find the list of identifiers, in your project in Publisher Account, go to the Pay Station > Payment methods section, or request it from your Customer Success Manager.
    Note
    If plans with a subscription fee associated with the first payment are set in your project, you also need to pass the following parameters:
    • purchase.checkout.amount with the price of the subscription plan
    • purchase.checkout.currency with the currency value
    Pass additional parameters for customization if needed.
    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"
        }
      }
    }'
    

    Example of payment data entry page:

    Via client API method

    1. Implement getting a link to open the payment UI using the client API method.
    2. Implement opening the payment UI in one of the following ways:

    Client method for getting a link to open a payment UI

    On the client side of your application, use an HTTP POST request to implement opening the payment UI: https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/buy.

    The request must contain an Authorization: Bearer <client_user_jwt> header, where <client_user_jwt> is user’s JSON Web Token (JWT) — a unique, Base64-encoded token encoded according to the Base64 standard. To get the token:

    Specify the project ID as the projectId path parameter. You can find this parameter in your Publisher Account next to the name of the project.

    Specify country as the query parameter — the two-letter designation of the user’s country according to the ISO 3166-1 alpha-2 standard. Affects the choice of locale and currency. If this parameter is not passed, the country is determined by the user’s IP address.

    Pass the following parameters in the request:

    • plan_external_id to open the payment interface on the payment method selection page.

    An example of a payment UI:
    An example of a payment UI:

    Request body parameters:

    ParameterTypeDescription
    plan_external_id
    stringRequired. The external ID of the subscription plan. You can find it in the Publisher Account > Subscriptions > Subscription Plans section.
    settings
    objectCustom project settings (object).
    settings.ui
    objectInterface settings (object).
    settings.ui.theme
    stringPayment UI theme. Can be default, default_dark or custom theme ID.
    settings.ui.version
    stringDevice type. Can be desktop (default) or mobile.
    settings.ui.desktop
    objectInterface settings for the desktop version (object).
    settings.ui.desktop.header
    objectHeader settings (object).
    settings.ui.desktop.header.close_button
    booleanWhether to show a Close button in Pay Station desktop. The button closes Pay Station and redirects the user to the URL specified in the settings.return_url parameter. false by default.
    settings.ui.desktop.header.is_visible
    booleanWhether to show the header in the payment UI.
    settings.ui.desktop.header.type
    stringHeader appearance. Can be compact (in which case the game name and user ID is not shown in the header) or normal.
    booleanIf true, the header shows your logo (first provide the image to your Customer Success Manager).
    settings.ui.desktop.header.visible_name
    booleanWhether to show the project name in the header.
    settings.ui.desktop.header.type
    stringHow to show the header. Can be compact (hides project name and user ID) or normal (default).
    settings.ui.mobile.header.close_button
    booleanWhether to show a Close button in Pay Station mobile. The button closes Pay Station and redirects the user to the URL specified in the settings.return_url parameter. false by default.
    settings.ui.mode
    stringInterface mode in Pay Station. Can be user_account only: The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop.
    settings.currency
    stringPreferred payment currency. Three-letter ISO 4217 currency code.
    settings.external_id
    stringTransaction ID in the game. Has to be unique for each user payment.
    settings.payment_method
    integerPayment method ID. You can get the list of payment method IDs in Publisher Account or using the Get payment methods API call.
    settings.return_url
    stringPage to redirect the user to after payment. Parameters user_id, foreigninvoice, invoice_id and status will be automatically added to the link.
    settings.redirect_policy
    objectRedirect policy settings (object).
    settings.redirect_policy.redirect_conditions
    stringA payment status that redirects the user to a return URL after making a payment. Can be none, successful, successful_or_canceled, or any.
    settings.redirect_policy.delay
    integerDelay (in seconds) after which a user is automatically redirected to the return URL.
    settings.redirect_policy.status_for_manual_redirection
    stringA payment status that redirects the user to a return URL after making a payment. Can be none, successful, successful_or_canceled, or any.
    settings.redirect_policy.redirect_button_caption
    stringText on the button for manual redirection.
    Pass additional parameters for customization if needed.
    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>"
        }
        

        With Pay Station Embed

        Add a script to your website page to open the payment UI widget. A full description of the script is available in the GitHub repository.

        EXAMPLE: ASYNCHRONOUS SCRIPT LOADING

        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 allows getting events from the payment UI via postMessage. You can send these events to analytics systems. To set up events processing in your analytics system, contact your Customer Success Manager or email to csm@xsolla.com.

        Script initialization parameters:

        ParameterTypeDescription
        access_token
        stringToken, received via server-side Create token API call or received in a link when the client API call is used. Required.
        sandbox
        booleanSet to true to test the payment process: sandbox-secure.xsolla.com will be used instead of secure.xsolla.com.
        lightbox
        objectLightbox parameters (object; desktop version only).
        lightbox.width
        stringLightbox frame width. If null, depends on Pay Station width. Default is null.
        lightbox.height
        stringLightbox frame height. If null, depends on Pay Station height. Default is 100%.
        lightbox.zIndex
        integerDefines arrangement order. Default is 1000.
        lightbox.overlayOpacity
        integerOpacity of the widget’s background (0 — completely ​​transparent, 1 — completely opaque). The default value is 60% (.6).
        lightbox.overlayBackground
        stringOverlay background color. Default is #000000.
        lightbox.modal
        booleanIf true, the lightbox frame cannot be closed. Default is false.
        lightbox.closeByClick
        booleanIf true, clicking the overlay will close the lightbox. Default is true.
        lightbox.closeByKeyboard
        booleanIf true, pressing ESC will close the lightbox. Default is true.
        lightbox.contentBackground
        stringFrame background color. Default is #ffffff. Note that these color changes do not affect the Pay Station iframe itself, only the settings of the lightbox that hold it.
        lightbox.contentMargin
        stringFrame margin. Default is 10px.
        lightbox.spinner
        stringType of animated loading indicator. Can be xsolla or round. Default is xsolla.
        lightbox.spinnerColor
        stringSpinner color. No default value.
        childWindow
        objectOptions for the child window containing the Pay Station UI. Supported in the mobile version.
        childWindow.target
        stringWhere to open the Pay Station window. Can be _blank, _self, _parent. Default is _blank.
        If you want to initialize the opening of the payment UI, use this link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained with the Create token method. You can also get a ready-made link with a token when implementing the client method for opening the payment interface.
        Note
        It is necessary to use the link with the https:// prefix only for the payment UI opening.
        Use the following URL for testing purposes: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.
        Notice
        Parameter access_token contains private user data. Make sure that you use server-to-server communication when getting this parameter.

        In an Iframe

        You need to implement the following mechanisms on your side:

        • Check the device type (desktop vs. mobile) and send it within the token’s settings.ui.version parameter.
        • Get events from the payment UI via postMessage. You can send these events to analytics systems. To set up events processing in your analytics system, contact your Customer Success Manager or email to csm@xsolla.com.

        To open the payment UI in an iframe, use the following link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained with the Create token method. You can also get a ready-made link with a token when implementing the client method for opening the payment interface.

        For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN.

        In a new window

        To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained with the Create token method. You can also get a ready-made link with a token when implementing the client method for opening the payment interface.

        For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN.

        Your progress
        Thank you for your feedback!
        Last updated: January 22, 2024

        Found a typo or other text error? Select the text and press Ctrl+Enter.

        Report a problem
        We always review our content. Your feedback helps us improve it.
        Provide an email so we can follow up
        Thank you for your feedback!