Overview
Xsolla API includes:
Pay Station API — payment UI and tokenization methods.Commerce 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,Commerce API , Publisher Account APIhttps://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 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
- 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.
- http
- curl
- php
- C#
- python
- ruby
- java
- js
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:Action | HTTP Method | Description |
---|---|---|
Create | POST | Creates and saves an entity of the specified type. |
List | GET | Returns 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. |
Retrieve | GET | Provides details on the entity with the specified ID. |
Replace | PUT | Modifies all fields of the entity with the specified ID. |
Update | PATCH | Modifies specified fields of the entity with the specified ID. |
Delete | DELETE | Deletes 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:
Name | Type | Description |
---|---|---|
http_status_code | integer | HTTP code. |
message | string | A 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_message | string | More detailed error description. |
request_id | string | Unique request ID that might be used for troubleshooting. |
- http
{
"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?
Rate this page
Don’t want to answer
Thank you for your feedback!
Found a typo or other text error? Select the text and press Ctrl+Enter.