Integrate payment solution
To track referrals and make payouts for collaborators, you first need to integrate Xsolla Pay Station. Requirements:
- Pay Station is integrated on a performance-optimized landing page.
- Pay Station is the only payment method used on the game’s landing page that drives traffic through the Partner Network program.
Get token
To open the payment UI, you need to get a token. A token is a string that includes encrypted data about a game and a user. You need to implement the getting of a token to identify the user to allow the purchase.
In the back-end of your application, implement getting a user authentication token. To do so, use an HTTP POST request that includes basic HTTP authentication and pass the required parameters in the request body.
The lifetime of the token is 14 hours after the last call to the Xsolla API. Implement the logic of receiving a new token after its expiration. It is recommended that you get a new token in the background, so the user doesn’t have to log in to the application again.
Basic HTTP authentication
Xsolla API uses basic access authentication. All requests to API must contain the Authorization: Basic <your_authorization_basic_key>
header, where <your_authorization_basic_key>
is the merchant ID:API key pair, encoded according to the Base64 standard. Go to Publisher Account to find these parameters:
- Merchant ID is shown:
- In the Project settings > Webhooks section.
- In the Company settings > Company section.
- In the URL in the browser address bar on any Publisher Account page. The URL has the following format:
https://publisher.xsolla.com/merchant ID/Publisher Account section
.
- API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
- Company settings > API keys
- Project settings > API keys
For more information about working with API keys, see the API reference.
Key recommendations:
- Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
- Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
- The API key must be stored on your server and never in binaries or on the frontend.
Request body
In the request body, pass the following required parameters:
Parameter | Type | Description |
---|---|---|
user.id | string | Unique user ID in your system. |
user.email | string | User email to send purchase receipts. If the parameter is not passed, a required field for entering an email appears on the payment page. |
settings.project_id | integer | Game’s Xsolla ID. You can find this information in your project section in Publisher Account. |
To improve user experience, you can also pass the following parameters:
Parameter | Type | Description |
---|---|---|
user.name | string | User screen name displayed on receipts. |
settings.currency | string | Preferred payment currency. |
settings.language | string | Interface language. |
Example of the request for obtaining a user authentication token
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>
}
},
"user": {
"email": {
"value": "<user_email>"
},
"id": {
"value": "<user_id>"
},
"name": {
"value": "<user_name>"
}
}
}'
Example of a user authentication token received in response
{
"token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
}
Open 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: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN
, where ACCESS_TOKEN
is the token obtained in the previous step.
New window
To open the payment UI in a new window, use the following URL: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN
, where TOKEN
is the obtained token.
https://secure.xsolla.com/paystation4/?token=TOKEN
.You can also open the payment UI using other options:
- With Pay Station Embed. Limitation: there might be problems when opening it in the in-game browser (WebView).
- In iframe. Limitation: there might be problems when opening it in the in-game browser (WebView) and in the mobile version of your application.
Pay Station Embed
EXAMPLE: ASYNCHRONOUS SCRIPT LOADING
- html
<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.
The Xsolla team created a widget that simplifies the integration of the payment UI into your website. The widget script is available in our GitHub repository.
Script initialization parameters:
Parameter | Type | Description |
---|---|---|
access_token | string | Token, received via API. Required. |
sandbox | boolean | Set to true to test the payment process: sandbox-secure.xsolla.com will be used instead of secure.xsolla.com . |
lightbox | object | Lightbox parameters (object; desktop version only). |
lightbox.width | string | Lightbox frame width. If null , depends on Pay Station width. Default is null . |
lightbox.height | string | Lightbox frame height. If null , depends on Pay Station height. Default is 100% . |
lightbox.zIndex | integer | Defines arrangement order. Default is 1000 . |
lightbox.overlayOpacity | integer | Overlay opacity (0 to 1). Default is .6 . |
lightbox.overlayBackground | string | Overlay background color. Default is #000000 . |
lightbox.modal | boolean | If true , the lightbox frame cannot be closed. Default is false . |
lightbox.closeByClick | boolean | If true , clicking the overlay will close the lightbox. Default is true . |
lightbox.closeByKeyboard | boolean | If true , pressing ESC will close the lightbox. Default is true . |
lightbox.contentBackground | string | Frame 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 | string | Frame margin. Default is 10px . |
lightbox.spinner | string | Type of animated loading indicator. Can be xsolla or round . Default is xsolla . |
lightbox.spinnerColor | string | Spinner color. No default value. |
childWindow | object | Options for the child window containing the Pay Station UI. Supported in the mobile version. |
childWindow.target | string | Where 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:
Parameter | Description |
---|---|
init | Widget initialized. |
open | Widget opened. |
load | Payment UI (Pay Station) loaded. |
close | Payment UI (Pay Station) closed. |
status | User is on the status page. |
status-invoice | User is on the status page; payment in progress. |
status-delivering | Event when the user was moved on the status page, payment was completed, and we’re sending payment notification. |
status-done | User is on the status page; payment credited to the user’s account. |
status-troubled | Event when the user was moved on the status page, but the payment failed. |
If you want to initialize the opening of the payment UI, use the following link: https://secure.xsolla.com/paystation4/?token=TOKEN
.
Use the following URL for testing purposes: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN
.
access_token
parameter contains private user data. Make sure that you use server-to-server communication when getting this parameter.Iframe
To open the payment UI in an iframe:
- Implement the
postMessage
mechanism to receive events from the payment UI. - Open the payment UI by following the link
https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN
, whereTOKEN
is the received token.
Set up webhooks
If you want to receive notifications about events (e.g. change of the payment status), set up webhooks in Publisher Account:
- Open your project in Publisher Account.
- Click Project settings in the side menu and go to Webhooks.
- Set the Webhooks toggle to On.
- Specify the webhook URL.
- A secret key to sign project webhooks is generated by default. If you want to generate a new secret key, click the refresh icon.
- Click Save settings.
It is recommended to implement the following webhooks:
To confirm that the webhook is received, your server must respond with:
- HTTP code 204 without a message body.
- HTTP code 400 describing the problem if the specified user was not found or if an invalid signature was passed.
Test payment process
To test the payment process, you can use the sandbox mode. Sandbox mode is a stand-alone environment that supports all features of a live environment, except real and declined payments. You can access sandbox mode by sending "mode":"sandbox"
when you get the token.
In sandbox mode, you can test the payment process with:
Test bank card payment
- Open the payment UI in sandbox mode.
- Choose the Credit/Debit cards group of payment methods.
- Enter the bank card details. Enter any values in the remaining fields. You can also specify incorrect details (card number or expiration date) to generate an error.
- Click Pay now.
In addition to card details, you need to specify the ZIP code if at least one of the following conditions is true:
- The user’s country is the US or Canada.
- The 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.
Test PayPal payment
Create test PayPal account
To test the payment process, you need to create an account for PayPal sandbox mode:
- Open the PayPal Developer website.
- Log in to your account or create a new one.
- Go to the
Sandbox accounts tab. - On the
Sandbox test accounts page, clickCreate account . - Select the
Personal (Buyer Account) account type and choose the country. - Click
Create .
The created account is shown in the list of sandbox accounts.
You can also use information from existing sandbox accounts:
sb-xmxij16980134@business.example.com | oi9_m_KW |
sb-p7pju16979920@business.example.com | 7%%p8ioS |
Make test payment
- Open the payment UI in sandbox mode.
- Choose the PayPal payment method.
- In the
Mock Response Code field, enter0
or leave the field empty. - In the ZIP Code field, enter any 5 digits.

- Click Pay. You will be redirected to a window to log in to your PayPal account.
- Enter information about your sandbox account:
Email ID as the email address andSystem Generated Password as the password. To find this information:- Log in to your account on the PayPal Developer website.
- Go to the
Sandbox accounts tab. - On the
Sandbox test accounts page, choose a sandbox account. - Click ••• and select View/Edit account from the drop-down list. You will see the data in the modal window that opens.
- Complete the test payment.
Go live
After completing the previous steps, you can start receiving real payments:
- Make sure you signed the licensing agreement with Xsolla.
- Remove
"sandbox": true
parameter from the request body when obtaining a token. - Open the payment UI using the following link:
https://secure.xsolla.com/paystation4/?token=TOKEN
.
Found a typo or other text error? Select the text and press Ctrl+Enter.