Open payment UI

There are three ways of opening the payment UI:

You can configure the payment UI to display certain information on opening:

With Pay Station Embed

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 Account Manager or send email to am@xsolla.com.

To easily implement the payment UI on your website, download the script from our CDN. Use this URL to integrate the script on your website. For more information visit our GitHub repository.

Script initialization parameters:

ParameterTypeDescription
access_token
stringToken, received via API. 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
integerOverlay opacity (0 to 1). Default is .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.

The script allows you to track payment UI events. Depending on the event type, you can perform various actions on the web page.

List of events:

ParameterDescription
initWidget initialized.
openWidget opened.
loadPayment UI (Pay Station) loaded.
closePayment UI (Pay Station) closed.
statusUser is on the status page.
status-invoiceUser is on the status page; payment in progress.
status-deliveringEvent when the user was moved on the status page, payment was completed, and we’re sending payment notification.
status-doneUser is on the status page; payment credited to the user’s account.
status-troubledEvent when the user was moved on the status page, but the payment failed.

If you want to initialize the opening of the payment UI by yourself, use this link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

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/paystation3/?access_token=ACCESS_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 Account Manager or send email to am@xsolla.com.

To open the payment UI in an iframe, use the following link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained in the previous step. For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

In a new window

To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token obtained in the previous step. For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

With catalog page display

To make the payment UI display only the subscription catalog page when opened, pass true to the settings.ui.components.virtual_currency.hidden and settings.ui.components.virtual_items.hidden parameters in the Create token API call.

Copy
Full screen
Small screen
Request Example:
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": {
      "currency": "USD",
      "project_id": 12345,
      "ui": {
        "components": {
          "virtual_currency": {
            "hidden": true
          },
          "virtual_items": {
            "hidden": true
          }
        }
      }
    }
  }'

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 to the Create token API call:

  • purchase.subscription.plan_id with the ID of the selected plan.
  • settings.payment_method with payment method ID. You can find the list of identifiers in your project in Publisher Account go to Pay Station > Payment methods section, or request it from the account manager of the project.
Copy
Full screen
Small screen
Request Example:
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"
    }
  }
}'

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.

Copy
Full screen
Small screen
Request Example:
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"
    }
  }
}'

Customization

In the payment UI, you can use the following customization options to sell subscriptions:

  • Change the standard light interface theme to dark by passing the settings.ui.theme = default_dark parameter to the Create Token API call. If this parameter is not passed, the light interface is used by default.

An example of a payment UI in a dark theme:

An example of a token request for a dark theme:

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"
    "ui": {
       "theme": "default_dark"
    }
  }
}
'

  • Configure the display of the subscription management section in the payment UI. To do this, pass the ui.user_account.subscriptions.enable = true parameter to the Create Token API call.
  • Place your own description above the list of subscriptions. To do this, pass the description text to the Create Token API call in the ui.desktop.subscription_list.description parameter.

An example of a payment UI with a subscription management section and a description of the plans section (light theme):

An example of token request for a light theme with a subscription management section and description of the plans section:

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",
    "ui": {
       "desktop": {
         "subscription_list": {
           "description": "Your Description"
         }
       },
        "user_account": {
          "subscriptions": {
              "order": 1,
              "enable": true
          }
        }
      }
    }
}
'

  • Change the standard subscriptions list view to an alternative one in the blocks form. To do this, pass the settings.ui.desktop.subscription_list.layout = grid parameter to the Create Token API call. The parameter takes the list value by default.

An example of a payment UI with an alternative subscriptions list view:

An example of token request for an alternative subscriptions list view:

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": 111111,
    "currency": "USD",
    "ui": {
       "desktop": {
         "subscription_list": {
           "layout": "grid"
         }
       }
    }
  }
}
'

You can get more information about customization and the parameters used for this in the How to customize Pay Station guide.

Your progress
Thank you for your feedback!
Last updated: September 19, 2022

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!