To integrate the Payments solution:
- Create a project in Publisher Account. One project corresponds to one game. If you have several games, add a project for each game.
- Add the items you want to sell to a catalog on Xsolla’s side.
- Test creating an order that a user will pay for.
- Test making a test purchase and set up notifications.
- Sign the licensing agreement with Xsolla in Publisher Account to start processing real payments.
Virtual items are in-game content that a user can buy for real and virtual currency. Creating a virtual item catalog on Xsolla’s side will allow you to customize regional prices and restrictions, as well as use Xsolla's system of promotions and other features that are regularly added and updated.
Create virtual items
Get items list
To get the list of items, call the Get virtual items list API method. In the request, pass the
project_id parameter — project ID that you can find in Publisher Account:
In the response, you will receive detailed information about virtual items created in your project. For the subsequent order creation, you need the item SKU that is passed in the
An order consists of items a user wants to buy in the store. After an order is paid, the user receives the items. To make a payment, a user must be authorized in the game.
Select an integration method that suits your game to see the instructions for setting up.
|Characteristics||Server side||Client side|
|Having a server||You need to have your own server to get tokens and control the load on the server.||You do not need your own server.|
|Determining the user’s country||If you don’t pass the country in the payment token, it is determined by the location of the server from which the request was made. This influences the choice of payment methods available to the user.||Xsolla determines the user’s country by IP address.|
|Determining the payment currency||If you don’t pass the currency in the token, it is determined by the country.|
If you pass the currency in the token, but don’t pass the country, the user pays in the currency passed in the token.
|The currency is determined by country.|
Make test purchase
Open payment UI in sandbox mode
To open the payment UI in a new window, use the following URL:
TOKEN is the token obtained when creating an order.
To open the payment UI using other methods, refer to the documentation.
Make test payment
- 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.
Information about ZIP codes
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.
Set up webhooks
To set up webhooks on Xsolla’s side:
- 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.
To receive notifications about user validation and successful payments, configure the following webhooks:
- User validation — for notifications to ensure the user is registered in the game.
- Payment — for notifications that the payment is made.
Configure webhook listener
Information about generation of signature and sending responses to webhook
Generation of signatureWhen receiving a webhook, you should ensure the security of data transmission. To achieve this, a signature must be generated from the webhook data and verified that it matches the signature sent in the HTTP request header. To generate a signature:
- Concatenate the JSON from the request body and the project's secret key.
- Apply the SHA-1 cryptographic hash function to the string obtained in the first step.
Sending responses to webhookTo confirm receipt of the webhook, your server must return:
204HTTP-code with no message body in case of a successful response.
400HTTP-code with description of the problem if the specified user was not found or an invalid signature was passed.
5xxcode in case of temporary issues on your server. If a response was not received for the Successful payment of the order and Order cancellation webhooks or if a response with a
5xxcode was received, the webhooks are resent according to the following schedule:
- 2 attempts with a 5-minute interval
- 7 attempts with a 15-minute interval
- 10 attempts with a 60-minute interval
5xxcode was received, webhooks are also resent with an increased time interval. A maximum of 12 attempts are made within 12 hours. If a response was not received for the User validation webhook or a response with a code of
5xxwas received, the User validation webhook is not resent. In this case, an error is shown to the user and the Payment and Successful payment of the order webhooks are not sent.
Sign licensing agreement
Signing the licensing agreement will allow you to receive real payments via any payment methods supported by Xsolla. To sign the licensing agreement:
- Open your Publisher Account.
- In the side menu, go to Agreements and taxes > Agreements section.
- On the Licensing Agreement tab, click Fill out application form.
- Provide your information in the corresponding fields.
Your application will be reviewed within 3 business days. If there are any questions during the verification process, Xsolla will notify the contact person indicated in the application. After the checking procedure is completed on Xsolla’s side, the status of your agreement will change to Signed.
Switch to production environment
After completing the previous steps, you can start receiving real payments:
- Make sure you signed the licensing agreement with Xsolla.
"sandbox": trueparameter from the request body when obtaining a token.
- Open the payment UI using the following link:
Was this article helpful?
Rate this page
Don’t want to answer
Thank you for your feedback!
Found a typo or other text error? Select the text and press Ctrl+Enter.