Getting Started

Overview

Xsolla API includes:

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, Publisher Account API, Subscriptions API
  • https://login.xsolla.com/api — Login API
  • https://store.xsolla.com/api — IGS&BB API
Most endpoint paths include the merchant_id parameter. This indicates that the requesting application is running on your behalf.

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.
Copy
Full screen
Small screen
    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.
    Note
    Keep in mind that we can only guarantee API integrity within the same version.

    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
    Notice

    For more information about working with API keys, see the API reference.

    Key recommendations:

    • Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
    • Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
    • The API key must be stored on your server and never in binaries or on the frontend.

    Endpoint types

    The type of an endpoint indicates what kind of data it handles and what action it performs on it. The most common actions are:
    ActionHTTP MethodDescription
    CreatePOSTCreates and saves an entity of the specified type.
    ListGETReturns a list of entities matching the query. To get details on an entity, first find out its ID using the corresponding List endpoint, and then provide this ID to the corresponding Retrieve endpoint.
    RetrieveGETProvides details on the entity with the specified ID.
    ReplacePUTModifies all fields of the entity with the specified ID.
    UpdatePATCHModifies specified fields of the entity with the specified ID.
    DeleteDELETEDeletes the entity with the specified ID.

    Date format

    All dates are specified as strings according to ISO 8601. You can specify date strings either in UTC (e.g., 2013-01-15T00:00:00Z), or indicating the UTC offset (e.g., 2013-01-15T00:00:00-08:00 for eight hours behind UTC). In the latter case, make sure to take into account the daylight saving time, if applicable.

    Pagination

    List endpoints might paginate the results they return. This means that, instead of returning all results in a single response, these endpoints might return some of the results, along with a response header that links to the next set of results. For this purpose we use offset and limit parameters.

    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:
    NameTypeDescription
    http_status_codeintegerHTTP code.
    messagestringA human-readable message describing the error. This message is always in English. Do not rely on this value for any particular error, because it might change in the future.
    extended_messagestringMore detailed error description.
    request_idstringUnique request ID that might be used for troubleshooting.
    Copy
    Full screen
    Small screen
    {
        "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 Customer Success Manager or email csm@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.

    Note
    API keys that are valid in all the company’s projects are not displayed on the pages of individual projects.
    Notice

    You can work with API keys (view the list, create, and delete) if you have one of the following roles:

    • developer
    • owner

    Only a project owner can change roles in Publisher Account in the Company settings > Users section.

    Create API key

    To create an 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.
    Note
    If you create an API key on the project page, the key is valid only in this particular project.
    Notice
    Key recommendations:
    • Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
    • Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
    • The API key must be stored on your server and never in binaries or on the frontend.

    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.

    Was this article helpful?
    Thank you!
    Is there anything we can improve? Message
    We’re sorry to hear that
    Please explain why this article wasn’t helpful to you. Message
    Thank you for your feedback!
    We’ll review your message and use it to help us improve your experience.
    Rate this page
    Rate this page
    Is there anything we can improve?

    Don’t want to answer

    Thank you for your feedback!
    Last updated: January 24, 2024

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