Set up item purchase
Choose the most suitable method for your project to access Xsolla data:
Create order on the client side of application
To create an order with user and item data on the Xsolla side, use the Create order with specified item API call. The method 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.
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.
- 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 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). |
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 | Opacity of the widget’s background (0 — completely transparent, 1 — completely opaque). The default value is 60% (.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. |
https://secure.xsolla.com/paystation4/?token=TOKEN
.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.- 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.
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. You can access sandbox mode by sending “sandbox”: true
when you create an order.
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.
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.
To see transactions made in sandbox mode:
- Open your Publisher Account.
- Go to Accounting > Transaction registry.
- Check the Show test transactions box.
Create order and open payment UI
To create an order with user and product data 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 thedone
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.
When you create an order, Xsolla generates a payment token, which is required to open the payment interface and make a payment.
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.
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
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.
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.
To see transactions made in sandbox mode:
- Open your Publisher Account.
- Go to Accounting > Transaction registry.
- Check the Show test transactions box.
Create order and open payment UI
- To create an order with user and item data on the Xsolla side, call the
createOrderByItemSku
method from the Store library, passing the following parameters to it:
callback
— the successful order creation callback. It receives the payment token that is necessary to open the payment UI and make payment.
itemSku
— the SKU of the item that the user wants to purchase.
options
— payment parameters (optional).
quantity
— the number of items the user wants to purchase (optional). If the quantity is not specified, the default value will be set to1
.
- Implement the logic of payment UI opening:
- kotlin
val intent = XPayments.createIntentBuilder(activity)
.accessToken(AccessToken(<payment token>))
.isSandbox(<isSandbox>)
.build()
startActivityForResult(intent, RC_PAYSTATION)
- Implement payment result handling:
- kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == RC_PAYSTATION) {
val (status, _) = XPayments.Result.fromResultIntent(data)
when (status) {
XPayments.Status.COMPLETED -> Log.d("MainActivity", "Payment completed")
XPayments.Status.CANCELLED -> Log.d("MainActivity", "Payment cancelled")
XPayments.Status.UNKNOWN -> Log.d("MainActivity", "Status unknown")
}
}
}
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 call the isSandbox
method and pass true
as an argument, when creating an IntentBuilder
object.
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.
- 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.
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.
To see transactions made in sandbox mode:
- Open your Publisher Account.
- Go to Accounting > Transaction registry.
- Check the Show test transactions box.
Create order and open payment UI
- To create an order with user and item data on 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
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.
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.
To see transactions made in sandbox mode:
- Open your Publisher Account.
- Go to Accounting > Transaction registry.
- Check the Show test transactions box.
Found a typo or other text error? Select the text and press Ctrl+Enter.