Overview

Generation of payment token on client side

Generation of payment token on server side

Testing

Catalog configuration

Customization

Promotions

Payment UI management

Anti-fraud

Set up item purchase

Choose the most suitable method for your project to access Xsolla data:

Use test web applications as an implementation example:

Create order on the client side of application

You can sell both an item with one SKU in any quantity, or a cart of items with different SKUs pre-filled by a user. To create an order with data about a user and items on the Xsolla side, use one of the following API calls:

The API call used will return a payment token, which is required to open the payment UI and make a payment. To use sandbox mode, pass the “sandbox”: true parameter in the body of the request for getting a token.

By default, the token lifetime is 24 hours. If you want to change this value, contact your Customer Success Manager or send an email to csm@xsolla.com. The new value will be enabled for all your company’s projects created in Publisher Account.

Open payment UI

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.

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.

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

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://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/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 Customer Success Manager or email to csm@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).
payment_widget_ui.lightbox.width	string	Lightbox frame width. If `null`, depends on Pay Station width. Default is `null`.
payment_widget_ui.lightbox.height	string	Lightbox frame height. If `null`, depends on Pay Station height. Default is `100%`.
payment_widget_ui.lightbox.zIndex	integer	Defines arrangement order. Default is `1000`.
payment_widget_ui.lightbox.overlayOpacity	integer	Opacity of the widget’s background (`0` — completely transparent, `1` — completely opaque). The default value is 60% (`.6`).
payment_widget_ui.lightbox.overlayBackground	string	Overlay background color. Default is `#000000`.
payment_widget_ui.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`.
payment_widget_ui.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.
payment_widget_ui.lightbox.contentMargin	string	Frame margin. Default is `10px`.
payment_widget_ui.lightbox.spinner	string	Type of animated loading indicator. Can be `xsolla` or `round`. Default is `xsolla`.
payment_widget_ui.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.

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/paystation4/?token=TOKEN.

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

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, where TOKEN is the received token.

Potential issue: If a button for copying a payment confirmation code required by some payment systems is not displayed when opening the payment UI in an iframe, pass the allow=“clipboard-read; clipboard-write; payment” attribute to the iframe.

Example:

Copy

Full screen

Small screen

<iframe
  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
  width="800"
  height="700"
  allow="clipboard-read; clipboard-write; payment"
></iframe>

Make test payment

Before you sign a contract with Xsolla, testing the payment process is only available in sandbox mode.

Testing does not require withdrawing money from real bank accounts.

Open the payment UI in sandbox mode.
Choose the Bank card payment method.
Enter the bank card details. In other fields (e.g., name or address), you can enter any data. You can also specify incorrect details (card number or expiration date) to test if an error is generated.
Click Pay.

Test cards list

See the list of test bank cards.

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.

In sandbox mode, you can test a one-time payment and payment with saved payment methods using bank cards and PayPal.

To see detailed information, including fees, about transactions made in sandbox mode:

Open your Publisher Account.
Go to Accounting > Transaction registry.
Check the Show test transactions box.

Additionally, you can see the transactions’ details and request refunds in Publisher Account in the Support > Transaction search section.

Create order and open payment UI

You can sell both an item with one SKU in any quantity, or a cart of items with different SKUs pre-filled by a user.

To create an order with data about a user and an item with one SKU on the Xsolla side, call the XsollaCatalog.Purchase SDK method, passing the following parameters to it:

itemSku — the SKU of the item that the user wants to purchase.
onSuccess — the successful purchase callback, triggered when the order transitions to the done status.
onError — the request error callback.
onBrowseClosed — the browser closing callback (optional). The event is tracked only when opening the user payment interface in the built-in browser. External browser events are not tracked.
purchaseParams — purchase parameters and user payment UI settings, such as locale and currency (optional).
customHeaders — custom web request headers (optional).

The XsollaCatalog.Purchase method initiates the purchase process for the specified item, including creating the order, opening the user payment UI, and tracking the order status. In the onSuccess parameter pass a function, that is called when the order transitions to the done status.

To create an order with data about a user and a cart of items on the Xsolla side, you first need to implement the logic of filling and editing the cart, as well as getting its content. Refer to the instructions for detailed information about purchase via a shopping cart.

When you create an order, Xsolla generates a payment token, which is required to open the payment interface and make a payment.

Make test payment

To test the payment process, you can use sandbox mode. Sandbox mode is a standalone environment that supports all features of a live environment, except real and declined payments. To have access to the sandbox mode, you should have the Test Payments Mode box checked in the Unity Editor in the Inspector panel (checked by default).

Before you sign a contract with Xsolla, testing the payment process is only available in sandbox mode.

Testing does not require withdrawing money from real bank accounts.

Run your application or scene in the Unity Editor.
Choose the Bank card payment method.
Enter the bank card details. In other fields (e.g., name or address), you can enter any data. You can also specify incorrect details (card number or expiration date) to test if an error is generated.
Click Pay.

Test cards list

See the list of test bank cards.

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.

In sandbox mode, you can test a one-time payment and payment with saved payment methods using bank cards and PayPal.

To see detailed information, including fees, about transactions made in sandbox mode:

Open your Publisher Account.
Go to Accounting > Transaction registry.
Check the Show test transactions box.

Additionally, you can see the transactions’ details and request refunds in Publisher Account in the Support > Transaction search section.

Create order and open payment UI

You can sell both an item with one SKU in any quantity, or a cart of items with different SKUs pre-filled by a user.

To create an order with data about a user and an item with one SKU the Xsolla side, call the FetchPaymentToken SDK method, passing the following parameters to it:

- AuthToken — the user authentication token, obtained during authentication using Xsolla Login.

- ItemSKU — the SKU of the item that the user wants to purchase.

- SuccessCallback - the callback triggered when successfully receiving the payment token.

- ErrorCallback — the request error callback.

- PurchaseParams — purchase and user payment interface parameters, such as locale and currency (optional).

Implement the opening of the payment interface. To do this, call the LaunchPaymentConsole SDK method, passing the following parameters to it:

- WorldContextObject — the world context object (for C++ call).

- OrderId — the order ID.

- AccessToken — the payment token.

- SuccessCallback — the callback triggered when successfully receiving the payment token.

- ErrorCallback — the request error callback.

- BrowserClosedCallback — the browser closing callback. The event is tracked only when opening the user payment interface in the built-in browser. External browser events are not tracked.

- PayStationVersion — the Pay Station version. By default, version 4 is used.

Make test payment

To test the payment process, you can use sandbox mode. Sandbox mode is a standalone environment that supports all features of a live environment, except real and declined payments. To have access to the sandbox mode, you should have the Enable Sandbox box checked in Unreal Editor in Settings > Project Settings > Plugins > Xsolla Settings > Purchases section (checked by default).

Before you sign a contract with Xsolla, testing the payment process is only available in sandbox mode.

Testing does not require withdrawing money from real bank accounts.

Run your application or map in the Unreal Editor.
Choose the Bank card payment method.
Enter the bank card details. In other fields (e.g., name or address), you can enter any data. You can also specify incorrect details (card number or expiration date) to test if an error is generated.
Click Pay.

Test cards list

See the list of test bank cards.

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.

In sandbox mode, you can test a one-time payment and payment with saved payment methods using bank cards and PayPal.

To see detailed information, including fees, about transactions made in sandbox mode:

Open your Publisher Account.
Go to Accounting > Transaction registry.
Check the Show test transactions box.

Additionally, you can see the transactions’ details and request refunds in Publisher Account in the Support > Transaction search section.

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: December 20, 2024

Found a typo or other text error? Select the text and press Ctrl+Enter.

Contents

Create order on the client side of application
Open payment UI
Make test payment
Create order and open payment UI
Make test payment
Create order and open payment UI
Make test payment

Your browser is not supported. Please try a different browser

Payments

Set up item purchase

Create order on the client side of application

Open payment UI

access_token

sandbox

lightbox

payment_widget_ui.lightbox.width

payment_widget_ui.lightbox.height

payment_widget_ui.lightbox.zIndex

payment_widget_ui.lightbox.overlayOpacity

payment_widget_ui.lightbox.overlayBackground

payment_widget_ui.lightbox.modal

lightbox.closeByClick

lightbox.closeByKeyboard

payment_widget_ui.lightbox.contentBackground

payment_widget_ui.lightbox.contentMargin

payment_widget_ui.lightbox.spinner

payment_widget_ui.lightbox.spinnerColor

childWindow

childWindow.target

Make test payment

Create order and open payment UI

Make test payment

Create order and open payment UI

Make test payment