Integrate payment solution

To track referrals and make payouts for collaborators, you first need to integrate Xsolla Pay Station. Requirements:

  1. Pay Station is integrated on a performance-optimized landing page.
  2. Pay Station is the only payment method used on the game’s landing page that drives traffic through the Partner Network program.

Get token

If authorized users will make purchases on your website, implement getting a token. If you plan to sell to unauthorized users, connect the Buy Button product.

You need to obtain a token to integrate with the payment UI. An access token is a string that identifies game, user, and purchase parameters.

Xsolla API uses basic access authentication. Specify your merchant ID as the username and the API key as the password.

URL to retrieve the token:

Full screen
Small screen{merchant_id}/token

You can alter the HTTP POST request by including the parameters you want to pass on to the payment UI. Pass the information about the user in the parameters,, and of the Create token method.
For the parameter, use an identifier that users can remember and later use outside the game by themselves (e.g., when replenishing the game balance using push payments).
API reference
See the full list of parameters.

Both the request and the response are in JSON format.

Below you can find sample code of how to get a token in PHP with the help of Xsolla PHP SDK. If you are using another programming language, take a look at the CURL example by clicking on the CURL tab.

Full screen
Small screen
  • php
  • curl

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
    ->setPurchase(9.99, 'USD');

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
curl -v{merchant_id}/token \
-u your_merchant_id:merchant_api_key \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-d '
    "user": {
        "id": {
            "value": "1234567"
        "email": {
            "value": ""
    "settings": {
        "project_id": 14004,
        "mode": "sandbox"
    "purchase": {
            "checkout": {
                "amount": 9.99,
                "currency": "USD"

Open payment UI

There are three ways of opening the payment UI:


Before you sign a contract with Xsolla, testing your payment process is only available in sandbox mode. In case of any errors, see their descriptions.

To open the payment UI in sandbox mode, use the following URL:

Pay Station Embed

This way of opening payment UI doesn’t support selling game keys. To sell game keys, follow the instruction.


Full screen
Small screen
   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 = "";
   s.addEventListener('load', function (e) {
   }, false);
   var head = document.getElementsByTagName('head')[0];

<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

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:

stringToken, received via API. Required.
booleanSet to true to test the payment process: will be used instead of
objectLightbox parameters (object; desktop version only).
stringLightbox frame width. If null, depends on Pay Station width. Default is null.
stringLightbox frame height. If null, depends on Pay Station height. Default is 100%.
integerDefines arrangement order. Default is 1000.
integerOverlay opacity (0 to 1). Default is .6.
stringOverlay background color. Default is #000000.
booleanIf true, the lightbox frame cannot be closed. Default is false.
booleanIf true, clicking the overlay will close the lightbox. Default is true.
booleanIf true, pressing ESC will close the lightbox. Default is true.
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.
stringFrame margin. Default is 10px.
stringType of animated loading indicator. Can be xsolla or round. Default is xsolla.
stringSpinner color. No default value.
objectOptions for the child window containing the Pay Station UI. Supported in the mobile version.
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:

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:

It is necessary to use the link with the https:// prefix only for the payment UI opening.

Use the following URL for testing purposes:

Parameter access_token contains private user data. Make sure that you use server-to-server communication when getting this parameter.


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

To open the payment UI in an iframe, use the following link:, where ACCESS_TOKEN is the token obtained in the previous step. For testing purposes, use this URL:

New window

To open the payment UI in a new window, use the following link:, where ACCESS_TOKEN is the token obtained in the previous step. For testing purposes, use this URL:

Set up webhooks

You need to implement the following webhooks for Pay Station:
Webhooks list
Read more about webhooks, including examples.

Acknowledge the receipt of a webhook by responding with HTTP code 204 without a message body.

To test the webhook handler, open Project settings > Webhooks section.

After setting up the webhooks, open Pay Station settings and set Checkout to On.

Test payment process

To test the payment process, you can:

  • Use the Sandbox
  • Make a real payment and then initiate a refund via Publisher Account

Xsolla Sandbox is a stand-alone environment that supports all features of the live environment, except real payments. You can access the Sandbox by sending "mode":"sandbox" when you get the token.

To test a bank card payment:
  1. Open the payment UI in sandbox mode.
  2. Choose the Credit/Debit cards group of payment methods.
  3. Enter the bank card details. Enter any values in the remaining fields. You can also specify incorrect details (card number, expiration date, or CVV) in order to generate an error.
Test cards list
See the list of test bank cards.

In addition to the card details, you need to specify the ZIP code if at least one of the conditions is true:

  • The user’s country is the US or Canada.
  • Bank identification number (BIN) indicates that a card was issued in the US.
You can specify any valid ZIP code (e.g., 12345). This determines the sales tax rate and does not affect the progress of the test payment.

Sandbox bank card payments can be made in the following currencies: 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.

To start receiving real payments, remove "mode":"sandbox" first.

To test the payment process by making real payments, it’s also recommended to use a bank card:

  1. Open the payment UI.
  2. Choose the Credit/Debit cards group of payment methods.
  3. Enter valid bank card details.
  4. After the payment is made, go to the Transaction search section in Publisher Account.
  5. Select your test transaction and click Refund (the transaction must be in the Completed status).

It’s recommended to use Visa and MasterCard cards to test the payment process.

Go live

To start processing real payments:

  1. Make sure that you have signed a contract with Xsolla.
  2. Open Pay Station by link. Or change to in Pay Station Embed script.
  3. Remove "mode":"sandbox" when getting the token.

Your progress
Thank you for your feedback!
Last updated: July 5, 2021

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!