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, Commerce API, Publisher Account API
  • https://login.xsolla.com/api — Login 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.

    Info: 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 Xsolla Publisher Account to find values of the merchant_id and api_key parameters:

    • merchant_id: Company settings > Company > Merchant ID
    • api_key: Company settings > API key

    Notice:
    • Keep your API key in secret. It provides access to your personal account and your projects in Publisher Account.
    • Changing the API key may stop payments to all your projects. API calls that use your current key will stop working until you update them with your new key.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    Example
    GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
    Headers:
      Authorization: Basic <your_authorization_basic_key>
    curl --request GET \
    --url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
    --header 'authorization: Basic <your_authorization_basic_key>'
    <?php
    
    // if you use Xsolla SDK for PHP
    use Xsolla\SDK\API\XsollaClient;
    $xsollaClient = XsollaClient::factory(array(
        'merchant_id' => MERCHANT_ID,
        'api_key' => API_KEY
    ));
    $eventsList = $client->ListEvents(array());
    
    // if you don’t use Xsolla SDK for PHP
    $client = new http\Client;
    $request = new http\Client\Request;
    
    $request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
    $request->setRequestMethod('GET');
    $request->setHeaders(array(
      'authorization' => 'Basic <your_authorization_basic_key>'
    ));
    
    $client->enqueue($request)->send();
    $response = $client->getResponse();
    
    echo $response->getBody();
    
    var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    var request = new RestRequest(Method.GET);
    request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
    IRestResponse response = client.Execute(request);
    
    import http.client
    
    conn = http.client.HTTPSConnection("api.xsolla.com")
    
    headers = { 'authorization': "Basic <your_authorization_basic_key>" }
    
    conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    require 'uri'
    require 'net/http'
    
    url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
    
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    
    request = Net::HTTP::Get.new(url)
    request["authorization"] = 'Basic <your_authorization_basic_key>'
    
    response = http.request(request)
    puts response.read_body
    OkHttpClient client = new OkHttpClient();
    
    Request request = new Request.Builder()
      .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
      .get()
      .addHeader("authorization", "Basic <your_authorization_basic_key>")
      .build();
    
    Response response = client.newCall(request).execute();
    var data = null;
    
    var xhr = new XMLHttpRequest();
    xhr.withCredentials = true;
    
    xhr.addEventListener("readystatechange", function () {
      if (this.readyState === this.DONE) {
        console.log(this.responseText);
      }
    });
    
    xhr.open("GET", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
    
    xhr.send(data);
    

    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"
    }

    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: August 16, 2021

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