Getting started

Overview

Xsolla API includes:

• Pay Station API — payment UI and tokenization methods.
• Shop Builder API — methods for working with Shop Builder module.
• Subscriptions API — methods for Subscriptions.
• Login API — methods for user authentication using your own interface (see integration guide).

The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.

• https://api.xsolla.com — Pay Station API, Subscriptions API
• https://login.xsolla.com/api — Login API
• https://store.xsolla.com/api — Shop Builder API

Requests and responses

• be sent over HTTPS,
• use TLS 1.2 or higher,
• contain authentication parameters,
• contain an additional header: Content-Type: application/json for PUT and POST requests.

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

By default, all requests return a response with JSON data in the body and Content-Type: application/json in the header.

API changes

• Add new API resources
• Add optional request parameters
• Add new properties to existing API responses
• Add new values for existing parameters with enumerable values
• Add new webhook types and JSON parameters
• Add optional HTTP request headers
• Reject any request in which valid parameters contain invalid values
• Reject improperly formed requests that were previously accepted due to lenient parsing, if the parsing logic is changed
• Add, change, or remove undocumented functionality at any time

Versioning

Authentication

• Basic access authentication. Such requests to API must contain the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant ID:API key pair, encoded according to the Base64 standard. Go to Publisher Account to find these parameters:
  • Merchant ID is shown:
    • In the Company settings > Company section.
    • In the URL in the browser address bar on any Publisher Account page. The URL has the following format: https://publisher.xsolla.com/<merchant_ID>/.
  • API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
    • Company settings > API keys.
    • Project settings > API keys.
• Authentication using the user JWT. Such requests to API must contain the Authorization: Bearer <user_JWT> header, where <user_JWT> is the user token.
• Authentication using the server JWT. Such API methods must contain the X-SERVER-AUTHORIZATION: <server_JWT> header, where <server_JWT> is the server token.
• Without authentication.

API calls by interaction model

• Client-side API calls — API calls for interaction between the client part of the partner’s application and the Xsolla server. User actions on the client initiate the request of these API calls. Example of client-side API calls: getting a list of items, user authentication, obtaining a payment token on the client.
• Server-side API calls — API calls for interaction between the partner’s server and the Xsolla server, which are intended for the following tasks:
  • Implementation of the user flow.
    User actions on the client trigger the invocation of the partner’s client-side API call, and then the Xsolla server-side API call is invoked on the partner’s server. Examples of server API calls for implementing the user flow: updating user attributes on the server, obtaining a payment token on the server.
  • Administrative tasks, or setup of Xsolla products by the partner.
    User actions on the client cannot initiate a call to these methods. Examples of admin server API calls: creating and editing an item or promotion.

• Exceeding rate limits:
  • The rate limits for server-side API calls are stricter than for client-side API calls.
  • The rate limits for administrator server-side API calls are stricter than for user flow implementation API calls.
• Receiving irrelevant information in response. For example, when using server-side API calls of getting a list of items for the administrator instead of client-side API calls of getting a list of items to build a catalog.
• Unauthorized data changes by users. For example, when using client-side API calls to update attributes instead of server-side API calls.
• Incorrect country and currency determination in the payment interface.

You can determine whether an API call is client or server-side by the scheme of authentication:

• Client-side — are called without authentication or with the Authorization header: Bearer <user_JWT> header, where <user_JWT> — is the user token.
• Server-side API calls for implementing the user flow — are called with the header:
  • X-SERVER-AUTHORIZATION: <server_JWT>, where <server_JWT> — is the server token.
  • Authorization: Basic <your_authorization_basic_key>, where <your_authorization_basic_key> — project_id:api_key pair, encoded according to the Base64 standard.
• Server-side API calls for administrative tasks — are called with the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> — project_id:api_key pair, encoded according to the Base64 standard.

Example of a server-side API calls with server-side authentication:

Example of a client-side API calls with client-side authentication:

Depending on your requirements, you can choose how to set up the integration when implementing the user flow — with server-side or client-side API calls. Server administrative API calls should not be used to implement user flow.

Implementation example of a user flow using client-side API calls:

1. The user performs actions on the client. For example: fills the cart, makes an item purchase.
2. The game client sends a request with data to the Xsolla server.
3. The Xsolla server sends a response to the game client.
4. The game client displays the result to the user.

In this flow, authentication via user JWT is used.

Example of implementing a user flow using server-side API calls:

1. The user performs actions on the client. For example: fills the cart, makes an item purchase.
2. The game client sends a request to the game server.
3. If necessary, the partner implements additional data processing on the game server.
4. The game server sends a request to the Xsolla server.
5. The Xsolla server sends a response to the game server.
6. The game server processes the data and sends a response to the game client.
7. The game client displays the result to the user.

In this flow, basic access authentication or a server token is used.

Interaction flow when using server-side admin API calls:

1. The partner sends a request from the client or server of their application to the Xsolla server.
2. The Xsolla server returns a response with the result of processing the request.

Endpoint types

Date format

Pagination

Errors handling

• 200, 201, 204 — No error
• 400 Bad Request — This often indicates a required parameter missing. Refer to the response body for details
• 401 Unauthorized — No valid API key provided
• 402 Request Failed — Request failed despite valid parameters
• 403 Forbidden — No permission. Refer to the response body for details
• 404 Not Found — The requested item doesn’t exist
• 409, 422 — Invalid request parameters
• 412 Precondition Failed — The project has not been activated yet (used in the Create token method)
• 415 Unsupported Media Type — Content-Type: application/json missing in HTTP header
• 500, 502, 503, 504 Server Errors — Something went wrong

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

Rate limits

General information

Common causes of exceeding rate limits

• A sudden increase in traffic on the partner’s side as a result of:
  • seasonal sales
  • start of closed and open testing
• Sudden increase in traffic as a result of DDoS attacks on the partner’s side.
• Incorrectly configured integration, for example:
  • using the Admin subsection’s methods that are not intended for frequent use instead of the Catalog subsection’s methods
  • frequent call of the Get order method to get the status of an order and the list of items in it. For example: 1 per second when the recommended delay between requests should be 3 seconds
• Launching an excessively large number of requests in a given period. For example: more than 200 calls per second to the Get virtual items list method to display an item catalog.

Rate limits handling

• Track the 429 status codes and create a retry mechanism. You can use the Retry pattern with fixed or exponential backoff between retries instead of continuous retries.
• Optimize code to get only required data. Make sure you only make requests that your application requires and avoid any unnecessary API calls. If you are using the Shop Builder API, you can use the WebSocket API to reduce the number of calls.
• Cache data that is frequently used by your application. You can keep the static data on your side and reduce the number of requests to the external API.
• Prevent DDoS attacks that can break your API.
• Adjust the rate of your requests for a smoother distribution. If the 429 error occurs regularly, consider including a process in your code that regulates the rate of your requests and allows them to be distributed more evenly.

API keys

An API key is a unique key that is used for user data encryption and API request authentication. In Publisher Account, you can create API keys for all the projects of the company and an individual project.

Create API key

1. Open Publisher Account.
2. Go to the Company settings > API keys or Project settings > API keys section.
3. Click Create API key.
4. Fill in the fields:
   • Key name that will be displayed in the list of keys. Set a name that would allow you to easily identify the key.
   • Key type — permanent or temporary.
   • Expiration date — only for a temporary key. After the expiration date, the key is no longer valid, and you need to create a new key.
   • Project where the key is valid (the field is not displayed when you create an API key on the project page). All projects are selected by default.
5. Click Create.
6. In the window that opens, click Copy API key and save the created API key on your side.

Delete API key

1. Open Publisher Account.
2. Go to the Company settings > API keys or Project settings > API keys section.
3. In the API key row, click the bin icon and confirm the action.

• receiving payments in the projects where this API key was used
• calling API methods that used this API key

1. Create a new API key.
2. Change your application to use the new API key.
3. Delete the initial API key.

Webhooks

Webhooks allow you to receive instant notifications of configured events on Xsolla’s side. You can set up processing webhooks to automate your application. Refer to our documentation for the list of available webhooks and detailed descriptions of how they work.