Pay Station

Xsolla Pay Station allows partners to monetize their product by providing users with a convenient UI to pay for in-game purchases in the game store. Key features:

  • 700+ payment methods in 200+ geographies, including bank cards, eWallets, mobile payments, cash kiosks, gift cards, special offers, and cryptocurrencies
  • 130+ currencies
  • UI localized in 20+ languages
  • Desktop/mobile browser and Smart TV versions
  • Support of campaigns, coupons, tax charges, and payment method commissions when calculating the purchase price
  • Automatic suggestion of payment methods most relevant for the user via the PayRank algorithm
  • Fraud protection
  • Management via Xsolla Publisher Account: configure gateways, re-order payment methods, view transaction history & stats, reconcile calculations, export reports, view support tickets, cancel payments, etc.

Note: If you have integrated Store, no separate Pay Station integration is needed — it will be enabled automatically.

How It Works

Step 1

Step 2

Step 3

Glossary

PayRank

PayRank is an algorithm that orders payment methods according to their relevance to the user. It considers various parameters such as location, payment history, payment amount, etc. It is used when building the lists of popular and all payment methods in Pay Station’s payment UI. You can flexibly configure PayRank from your Publisher Account.

Gateways

Gateways allow receiving payouts directly from payment systems available within the Pay Station interface. You can use this model if you want to receive direct payouts from payment systems of your choice. Under this model, the interface will not change, but Xsolla serves only as a Technical Service Provider and takes a reduced revenue share.

To have a gateway displayed in the Pay Station interface, you should first configure it in your Publisher Account and sign the agreement.

Offerwall

Offerwall allows you to improve users’ loyalty via special offers displayed as a widget within the payment UI. The widget encourages the user to complete certain tasks — such as signup, survey, purchase, etc. — to get a bonus credited to their Xsolla balance.

Gift Cards

Gift cards are discount cards from certain stores that allow users to buy game content via a widget inside the payment UI. If the purchase amount is less than the card’s face value, the remainder is credited to the user’s Xsolla balance.

User Flow

Integration Flow

To enable Pay Station:

  1. Register an Xsolla Publisher Account.
  2. Create a project.
  3. Get a token.
  4. Set up the opening of the payment UI.
  5. Set up webhook handling.

You will need the following parameters for the integration:

  • Merchant ID, shown in Project settings > Webhooks
  • API key. Parameter is generated in the Company settings > API key section
  • Project ID, shown in Project settings > Webhooks
  • Secret key. Parameter is generated in the Project settings > Webhooks section

Note: This guide describes the minimum settings required to quick-start the module. In case of any questions, please contact your Account Manager.

Creating a Project

  1. Go to Projects and click Create new project.
  2. In setup mode:
    1. Specify the webhook URL.
    2. Generate a secret key to sign project webhooks.

Getting a Token

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 HTTP authentication. Specify your merchant ID as the username and the API key as the password.

URL to retrieve the token:

https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Requesting a Token

You can alter the HTTP POST request by including the parameters you want to pass on to the payment UI. 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, please take a look at the CURL example by clicking on the CURL tab.

Copy
Full screen
  • 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"
            }
    }
}'

You can find the full list of parameters in the API Reference.

Testing the 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 standalone environment that supports all features of the live environment, except real payments. You can access the Sandbox by sending “mode”:“sandbox” when getting 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.

List of bank cards to be used for testing

Note: 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.
Notice: To start receiving real payments, please remove “mode”:“sandbox” first.

To test the payment process by making real payments, it is 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).

Note: It is recommended to use Visa and MasterCard cards to test the payment process.

Opening the Payment UI

There are three ways of opening the payment UI:

Note: To open the payment UI in sandbox mode, use the following URL: https://sandbox-secure.xsolla.com/.

Pay Station Embed

The Pay Station Embed script determines the type of device and opens the payment UI in a lightbox (on desktop screens) or in a new window (on mobile and tablet screens). We recommend using asynchronous script loading.

EXAMPLE: ASYNCHRONOUS SCRIPT LOADING

<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>

You can find the full list of script initialization parameters in the API reference.

New Window

To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation2/?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/paystation2/?access_token=ACCESS_TOKEN.

Iframe

To open the payment UI in an iframe, you must implement the following mechanisms on your side:

  • Checking the device type (desktop vs mobile) and sending it within the token’s settings.ui.version parameter
  • Getting events from the payment UI via postMessage

To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation2/?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/paystation2/?access_token=ACCESS_TOKEN.

Setting up Webhooks

You need to implement the following webhooks for Pay Station:

Acknowledge the receipt of a webhook by responding with HTTP code 204 without a message body. You can read more about webhooks, including examples, in the API Reference.

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

Note: After having set up the webhooks, open Pay Station settings and set Checkout to On.

Recipes

Our Recipes will help you try out some of Pay Station’s advanced features: