Quick start

Integration flow

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.

You can sign the licensing agreement at any integration step, but keep in mind that the review process can take up to 3 business days.

Create catalog

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 header, pass the Xsolla Login JWT (Bearer token) used for authorization by default. To test calling this API method, you can use the following test token: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI.
In the project_id path-parameter, pass the 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 items.sku parameter.

Create order

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	You need to pass either the country or the IP address in the payment token. This influences the availability of payment methods.	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, the user pays in this currency.	The currency is determined by country.

Call the Create payment token for purchase API method and pass information about a user and items in this method. You can use this API call to sell single and multiple items.

To use sandbox mode, pass the “sandbox”: true parameter in the body of the request for getting a token.

The value of the user_id parameter:

When testing, you can pass any symbol in this parameter.
To accept real payments, pass the user ID from your system in this parameter. This ID is passed in the User validation webhook.

Request example:

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://store.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    },
    "sandbox": true
  }'

Integrate Xsolla Login:

Using the configured Login method, create and save the authentication token to receive a payment token. The payment token is used for opening the payment UI and making the payment.

To test the payment flow, create an order using the Create order with specified item API call:

If you want to perform a test on the API documentation website, click Try it to open the interface for creating a request.
In the Security block, in the Bearer Token field, enter the token obtained while passing the authentication procedure.
In the Body block, pass order details, e.g., quantity of item quantity. To access sandbox mode, pass "sandbox": true.
In the Parameters block, pass:
- project_id — project ID that you can find in Publisher Account.
- item_sku — item SKU.

In the response, you will receive data you need for further work:

token — payment token

Request example:

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Make test purchase

Testing does not require withdrawing money from real bank accounts — you can use one of our test cards.

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

Open payment UI in sandbox mode

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

Test cards list

See the list of test bank cards.

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.

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

Set up webhooks

If you set up integration on the server side, you need to validate created orders by sending the respective code in response to webhooks. If you set up integration on the client side, webhooks will allow you receive notifications about configured events (e.g., change of payment status).

To enable receiving webhooks:

Open your project in Publisher Account.
Click Project settings in the side menu and go to the Webhooks tab.
In the Webhook server field, specify the URL of your server where you want to receive webhooks in the https://example.com format. You can also specify the URL you find in a tool for testing webhooks.
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 Enable webhooks.

PHP SDK

Use ready classes for processing webhooks.

To test webhooks, you can select any dedicated website, such as webhook.site, or a platform, such as ngrok.

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.

Refer to the documentation for detailed information about setting up and testing webhooks.

Configure webhook listener

Webhook listener is program code that allows receiving incoming webhooks at a specified URL address, generating a signature, and sending a response to the Xsolla webhook server.

Information about generation of signature and sending responses to webhook

Generation of signature

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

To confirm receipt of the webhook, your server must return:

200, 201, or 204 HTTP code in case of a successful response.
400 HTTP-code with description of the problem if the specified user was not found or an invalid signature was passed.

Your webhook handler may also return a 5xx code 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 5xx code 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

Maximum of 20 attempts to send webhooks are made within 12 hours from the first attempt. If for the Payment webhook a response was not received or if a response with a 5xx code 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 400 or 5xx was 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.

Launch

Before you sign the licensing agreement, you can open the payment UI only in sandbox mode.

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 the first real payment is made, a strict sandbox payment policy takes effect. Payments made in sandbox mode are available only to users who are specified in Publisher Account in the Company settings > Users section.

After completing the previous steps, you can start receiving real payments:

Make sure you signed the licensing agreement with Xsolla.
Remove “sandbox”: true parameter from the request body when obtaining a token.
Open the payment UI using the following link: https://secure.xsolla.com/paystation4/?token=TOKEN.

This guide describes the minimum settings required to quick-start the integration. If you have any questions, contact us via Xsolla Chat in the bottom right corner of the page or email a Customer Success Manager at csm@xsolla.com.

Thank you for your feedback!

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

Rate this page

Don’t want to answer

Thank you for your feedback!

Last updated: March 18, 2024

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

Your browser is not supported. Please try a different browser

Payments

Quick start

Integration flow

Create catalog

Create virtual items

Get items list

Create order

Make test purchase

Open payment UI in sandbox mode

Make test payment

Set up webhooks

Configure webhook listener

Generation of signature

Sending responses to webhook

Launch

Sign licensing agreement

Switch to production environment

Was this article helpful?

Rate this page

Thank you for your feedback!