Overview

Xsolla API includes:

• Pay Station API — payment UI and tokenization methods.
• IGS&BB API — methods for working with In-Game Store and Buy Button modules.
• Subscription API — methods for Subscriptions.
• Publisher Account API — methods for working with Publisher Account projects and users, reports, and support tickets.
• Login API — methods for user authentication using your own interface (see integration guide).

Xsolla API uses the REST architecture. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. The API always responds in the JSON format, including in case of errors.

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.

Xsolla API uses the following endpoint paths:

• https://api.xsolla.com — Pay Station API, IGS&BB API, Publisher Account API
• https://login.xsolla.com/api — Login API

Requests and responses

The requests to Xsolla API must:

• 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

Xsolla may change the API functionality as follows:

• 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

Your client should remain functional regardless of such changes. For example, new JSON parameters that aren’t recognized by your client should not hinder its normal operation.

Versioning

All Xsolla API methods support versioning. We will issue a new version every time there are changes incompatible with the current version. The version is identified by "v1"/"v2"/etc. following the "/merchant" prefix in the URL.

If this is your first time working with the API, use the latest version. If you omit the version, we will use the first version by default.

Authentication

Xsolla API uses basic access authentication. All 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 Project settings > Webhooks section.
  • 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/Publisher Account section.

• 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

Endpoint types

Date format

Pagination

Errors handling

List of supported HTTP errors:

• 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

Xsolla uses conventional HTTP response codes to indicate whether the API request was successful. In general, 2xx indicates success, 4xx indicates an error in the provided information (e.g., a required parameter missing, failed authorization, etc.), and 5xx indicates a problem with Xsolla’s servers.

But not all errors perfectly match HTTP response codes. For example, if a request was valid but failed, the API will return the 422 error code.

All API error responses provide a JSON object with the following fields:

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

Rate limits

General information

To avoid overloading Xsolla systems and protect them from bursts of incoming traffic, Xsolla limits the number of requests received by the Xsolla API within a specified period of time. If the limit is exceeded, the Xsolla API returns an HTTP response with the 429 status code.

Limits vary by method, project, and other factors. The current limits are updated regularly to ensure the stable and uninterrupted operation of Xsolla systems. In some cases, it is possible to adjust the specified limits upon prior request. You can contact your Account Manager or email am@xsolla.com to submit a request.

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

To prevent errors caused by rate limits, we recommend that you:

• 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 IGS&BB 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

To delete an 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.

Deleting an API key ceases:

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

To prevent it:

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.

Rate this page

Is there anything we can improve? Send

Don’t want to answer

Thank you for your feedback!