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
You need to obtain a token to integrate 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.
To find this data:
- In your Publisher Account, go to Company settings.
- In the Company tab, copy Merchant ID.
- In the API key tab, copy the API key.

URL to retrieve the token:
- curl
https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token
user.id
, user.name
, and user.email
of the Create token method.user.id
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).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.
- php
- curl
<?php
use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;
$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
->setExternalPaymentId('12345')
->setSandboxMode(true)
->setUserName('USER_NAME')
->setPurchase(9.99, 'USD');
$xsollaClient = XsollaClient::factory(array(
'merchant_id' => MERCHANT_ID,
'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
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"
},
"email": {
"value": "email@example.com"
}
},
"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: https://sandbox-secure.xsolla.com/
.
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.
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:
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 by yourself, use this link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
.
Use the following URL for testing purposes: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
.
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
.
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
.
Set up webhooks
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.
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 an account for PayPal sandbox mode:
- Open the PayPal Developer website.
- Log in to your account or create a new one.
- Go to
Sandbox > Accounts . - In the
Sandbox Account section, clickCreate account . - In the modal window, select the
Personal account type and a country. - Click
Create . The created account will be shown in the list of sandbox accounts.
- Open the payment UI in sandbox mode.
- Choose the PayPal payment method.
- In the payment window, enter required information.
- Click
Pay Now . You will be redirected to a window to log in to your PayPal account.
- To complete the testing payment process, enter information about your sandbox account created in step 1:
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
Sandbox > Accounts . - In the
Sandbox Account section, choose the sandbox account. - Click ••• and select
View/edit account from the drop-down list.
- Click
Pay Now .
You can also use information from existing sandbox accounts:
sb-xmxij16980134@business.example.com | oi9_m_KW |
sb-p7pju16979920@business.example.com | 7%%p8ioS |
Go live
To start processing real payments:
- Make sure that you have signed a contract with Xsolla.
- Open Pay Station by
secure.xsolla.com
link. Or changesandbox-secure.xsolla.com
tosecure.xsolla.com
in Pay Station Embed script. - Remove
"mode":"sandbox"
when getting the token.
Found a typo or other text error? Select the text and press Ctrl+Enter.