Overview
Xsolla API includes:
- Pay Station API — payment UI and tokenization methods
- Store API — methods for working with Store modules: Virtual Currency, Virtual Items, Subscriptions, Game Keys, Promotions, Coupons
- 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, Store API, Publisher Account API
- https://login.xsolla.com/api — Login API
Release Notes
Changes in version 2.0:- New URL to export transactions: https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/registry.{format}
- Changed response format:
- Canceled transactions now have negative values in the following fields:
- Payment system fee, fixed
- Xsolla revenue share, fixed
- Sales Tax
- Virtual currency purchase amount
- Simple checkout purchase amount
- Items purchase amount
- Repatriation costs, total
- Fees covered, fixed
- Fees covered by Balance
- Payout amount from payment system
- Payment amount from Balance
- Payout amount from Balance
- Pin codes purchase amount
- New fields added:
- Payment system type - Payment type
- VAT - VAT shown to the user
- VAT, % - VAT percentage in that country
- Refund reason comment - Comments on the refund reason
- Direct account - Whether this is a direct account or not
- Fields removed:
- Payment system external fee (%)
- Payment system external fee amount
- Payment system external fee currency
- Deducted VAT, % is set to 0 if Deducted VAT is 0
- Fields renamed:
- VAT -> Deducted VAT
- VAT (%) -> Deducted VAT, %
- The following fields are not filled in if equal to 0:
- Virtual currency amount
- Virtual currency purchase amount
- Simple checkout purchase amount
- Pin codes purchase amount
- Virtual currency purchase currency is not filled in if Virtual currency purchase amount equals 0
- Simple checkout purchase currency is not filled in if Simple checkout purchase amount equals 0
- Pin codes purchase currency is not filled in if Pin codes purchase amount equals 0. Pin codes purchase cart content remains empty
- Canceled transactions now have negative values in the following fields:
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
-
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 Get 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:
{< T "api_table_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_status_code": 500,
"message": "Internal Server Error",
"extended_message": null,
"request_id": "6445b85"
}
Token
In order to enable secure payments, Xsolla API handles payment parameters within a token instead of receiving them directly through GET requests to the payment page. You have to obtain a new token before rendering the payment page. A token is valid for 24 hours.
Get Token
HTTP REQUEST
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token
You can create a token with arbitrary user parameters. You send these parameters when obtaining the token, and we send them back to you after a successful payment. A token can only contain parameters either described in this document or predefined by the partner.
Parameter | Type | Description |
---|---|---|
user |
object | User details (object). |
user.id |
object | User ID (object). Required. |
user.id.value |
string | User ID. |
user.name |
object | User screen name (object). |
user.name.value |
string | User screen name. |
user.email |
object | User email (object). |
user.email.value |
string | User email. Must be valid according to the RFC 822 protocol. |
user.phone |
object | User phone number (object). |
user.phone.value |
string | User phone number. |
user.country |
object | User country (object). |
user.country.value |
string | Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.country.allow_modify |
boolean | Whether or not user can change the country on payment UI. 'false' by default. |
user.attributes |
object | User attributes for filtering the item list, represented as a valid JSON set of key-value pairs. |
user.steam_id |
object | User's Steam ID (object). |
user.steam_id.value |
string | Steam ID. |
user.tracking_id |
object | User tracking ID (object). |
user.tracking_id.value |
string | Unique tracking ID (used in marketing campaigns). |
user.public_id.value |
string | Parameter that uniquely identifies the user and is known to the user (email, screen name, etc). Allows the user to make purchases outside the game store (e.g., via cash kiosks). |
user.utm |
object | Traffic attributes (object). |
user.utm.utm_source |
string | Traffic source. |
user.utm.utm_medium |
string | Traffic channel (contextual ads, media ads, email lists, etc.). |
user.utm.utm_campaign |
string | Campaign title, transliterated or translated to English. |
user.utm.utm_term |
string | Campaign keyword. If set, statistics will be based on the keywords used for ad targeting rather than on specific search queries. In Google Analytics, the specified 'utm_term' is part of the general search terms report. |
user.utm.utm_content |
string | Campaign content. |
user.is_legal |
boolean | Whether the user is a legal entity. |
user.legal |
object | Object with legal entity details. Object and all its parameters are required if user.is_legal is ‘true’. |
user.legal.name |
string | Full legal name. |
user.legal.address |
string | Full legal address. |
user.legal.vat_id |
string | Individual taxpayer identifier. |
user.legal.country |
string | Country of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used. |
settings |
object | Custom project settings (object). |
settings.external_id |
string | Transaction’s external ID. |
settings.project_id |
integer | Game’s Xsolla ID. Can be found in Publisher Account. Required. |
settings.language |
string | Interface language. Two-letter lowercase language code per ISO 639-1. |
settings.return_url |
string | Page to redirect the user to after payment. Parameters 'user_id', 'foreigninvoice', 'invoice_id' and 'status' will be automatically added to the link. |
settings.currency |
string | Preferred payment currency. Three-letter currency code per ISO 4217. |
settings.mode |
string | Set to 'sandbox' to test out the payment process. In this case, use https://sandbox-secure.xsolla.com to access the test payment UI. |
settings.payment_method |
integer | Payment method ID. |
settings.payment_widget |
string | Payment widget. Can be 'paybycash' or 'giftcard'. If the parameter is set, the user is redirected to the Pay by Cash or Gift Cards widget, respectively. |
settings.ui |
object | Interface settings (object). |
settings.ui.theme |
string | Payment UI theme. Can be 'default' or 'default_dark'. |
settings.ui.size |
string | Payment UI size. Can be:
|
settings.ui.version |
string | Device type. Can be 'desktop' (default) or 'mobile'. |
settings.ui.desktop |
object | Interface settings for the desktop version (object). |
settings.ui.desktop.header |
object | Header settings (object). |
settings.ui.desktop.header.is_visible |
boolean | Whether to show the header in the payment UI. |
settings.ui.desktop.header.visible_logo |
boolean | If 'true', the header will show your logo (please first provide the image to your account manager). |
settings.ui.desktop.header.visible_name |
boolean | Whether to show the project name in the header. |
settings.ui.desktop.header.visible_purchase |
boolean | Whether to show the purchase description (purchase.description.value) in the header. ‘true’ by default. |
settings.ui.desktop.header.type |
string | How to show the header. Can be 'compact' (hides project name and user ID) or 'normal' (default). |
settings.ui.desktop.header.close_button |
boolean | Whether to show a Close button in Pay Station desktop. The button closes Pay Station and redirects the user to the URL specified in the "settings.return_url" parameter. 'false' by default. |
settings.ui.desktop.subscription_list |
object | Settings for the list of subscription plans (object). |
settings.ui.desktop.subscription_list.layout |
string | List template. Can be 'list' (default) or 'grid'. |
settings.ui.desktop.subscription_list.description |
string | Any text to show above the list of available subscription plans in the payment UI. |
settings.ui.desktop.subscription_list.display_local_price |
boolean | If 'true', and if the user's local currency is different from the one set for the subscription plan, the user will be able to see both prices: one in the local and one in the basic currency. |
settings.ui.desktop.virtual_item_list |
object | Settings for the list of virtual items (object). |
settings.ui.desktop.virtual_item_list.layout |
string | List template. Can be 'list' (default) or 'grid'. |
settings.ui.desktop.virtual_item_list.button_with_price |
boolean | If 'true', the price will be shown on the button. If 'false', the price will be shown on the left of the button. 'false' by default. |
settings.ui.desktop.virtual_item_list.view |
string | Display virtual item groups as a vertical/horizontal menu. Can be 'horizontal_navigation' or 'vertical' (default). |
settings.ui.desktop.virtual_currency_list |
object | Settings for the list of virtual currencies (object). |
settings.ui.desktop.virtual_currency_list.description |
string | Any text to show above the list of virtual currencies. |
settings.ui.desktop.virtual_currency_list.button_with_price |
boolean | If 'true', the price will be shown on the button. If 'false', the price will be shown on the left of the button. 'false' by default. |
settings.ui.header.visible_virtual_currency_balance |
boolean | Whether or not this element can be hidden on Payment UI. 'true' by default. |
settings.ui.mobile.mode |
string | A user can only pay using their saved payment methods. Can be 'saved_accounts'. |
settings.ui.mobile.header.close_button |
boolean | Whether to show a Close button in Pay Station mobile. The button closes Pay Station and redirects the user to the URL specified in the "settings.return_url" parameter. 'false' by default. |
settings.ui.mobile.footer.is_visible |
boolean | Whether to hide the footer in the mobile version of the payment UI. |
settings.ui.license_url |
string | Link to the EULA. |
settings.ui.components |
object | Menu settings (object). |
settings.ui.components.virtual_items |
object | Virtual items submenu. |
settings.ui.components.virtual_items.order |
integer | Position of the submenu in the menu. |
settings.ui.components.virtual_items.hidden |
boolean | Whether to show the submenu. |
settings.ui.components.virtual_items.selected_group |
string | Group to show after opening the virtual items tab. |
settings.ui.components.virtual_items.selected_item |
string | Item to show after opening the virtual items tab (item SKU). |
settings.ui.components.virtual_currency |
object | Virtual currency submenu. |
settings.ui.components.virtual_currency.custom_amount |
boolean | Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI. |
settings.ui.components.virtual_currency.order |
integer | Position of the submenu in the menu. |
settings.ui.components.virtual_currency.hidden |
boolean | Whether to show the submenu. |
settings.ui.components.subscriptions |
object | Subscription plans submenu (object). |
settings.ui.components.subscriptions.order |
integer | Position of the submenu in the menu. |
settings.ui.components.subscriptions.hidden |
boolean | Whether to show the submenu. |
settings.ui.mode |
string | Interface mode in Pay Station. Can be 'user_account' only: The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop. |
settings.ui.user_account |
object | User account details (object). |
settings.ui.user_account.info |
object | Page 'My account'. |
settings.ui.user_account.info.order |
integer | Position of the submenu in the menu. |
settings.ui.user_account.info.enable |
boolean | Whether to show the submenu. 'false' by default. |
settings.ui.user_account.history |
object | History submenu. |
settings.ui.user_account.history.order |
integer | Position of the submenu in the menu. |
settings.ui.user_account.history.enable |
boolean | Whether to show the submenu. 'false' by default. |
settings.ui.user_account.payment_accounts |
object | "My payment accounts" submenu. |
settings.ui.user_account.payment_accounts.order |
integer | Position of the submenu in the menu. |
settings.ui.user_account.payment_accounts.enable |
boolean | Whether to show the submenu. 'false' by default. |
settings.ui.user_account.subscriptions |
object | "Manage subscriptions" submenu. |
settings.ui.user_account.subscriptions.order |
integer | Position of the submenu in the menu. |
settings.ui.user_account.subscriptions.enable |
boolean | Whether to show the submenu. 'false' by default. |
settings.shipping_enabled |
boolean | Whether to display the delivery address form. 'false' by default. |
purchase |
object | Object containing purchase details. |
purchase.virtual_currency |
object | Object containing virtual currency details. |
purchase.virtual_currency.quantity |
float | Purchase amount in the virtual currency. |
purchase.virtual_currency.currency |
string | Currency of the virtual currency package to use in all calculations. |
purchase.virtual_items |
object | Object with data about the virtual items in purchase. |
purchase.virtual_items.currency |
string | Currency of the ordered items to use in all calculations. |
purchase.virtual_items.items |
array | Item data (array). |
purchase.virtual_items.items.sku |
string | Item ID. |
purchase.virtual_items.items.amount |
integer | Item quantity. |
purchase.virtual_items.available_groups |
array | Item groups IDs (array). The payment UI will only include items within the specified group. |
purchase.subscription |
object | Subscription data (object). |
purchase.subscription.plan_id |
string | Plan ID. |
purchase.subscription.operation |
string | The type of operation applied to the user’s subscription plan. To change the subscription plan, pass the ‘change_plan’ value. You need to specify the new plan ID in the purchase.subscription.plan_id parameter. |
purchase.subscription.product_id |
string | Product ID. |
purchase.subscription.currency |
string | Currency of the subscription plan to use in all calculations. |
purchase.subscription.available_plans |
array | Subscription plans (array) to show in the payment UI. |
purchase.subscription.trial_days |
integer | Trial period in days. |
purchase.pin_codes |
object | Game keys (object). |
purchase.pin_codes.currency |
string | Currency of a Game key within the order to use in all calculations. |
purchase.pin_codes.codes |
array | Game keys (array). |
purchase.pin_codes.codes.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.codes.drm |
string | DRM platform used to distribute the game. Can be 'steam', 'playstation', 'xbox', 'uplay', 'origin', 'drmfree', 'gog', 'epicgames', 'nintendo_eshop', 'discord_game_store', or 'oculus'. Make sure to have configured the required DRM platforms in your Publisher Account. If not passed in the token, will be chosen by the user in the payment UI. |
purchase.pin_codes.upgrade |
object | Object with the upgrade data. |
purchase.pin_codes.upgrade.id_user_history |
integer | ID of the entry containing data on the user and their packages. |
purchase.pin_codes.upgrade.id |
integer | Upgrade ID. |
purchase.checkout |
object | Object containing checkout details. |
purchase.checkout.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.checkout.amount |
float | Purchase amount. |
purchase.description |
object | Purchase description (object). |
purchase.description.value |
string | General purchase description to include in the payment UI and email receipts. To pass each item individually, use the parameters of the purchase.description.items array. |
purchase.description.items |
array of objects | Items array. |
purchase.description.items.name |
string | Item name. |
purchase.description.items.image_url |
string | Link to the item icon. |
purchase.description.items.description |
string | Item description in the purchase. |
purchase.description.items.price |
object | Object with the item price. |
purchase.description.items.price.amount |
string | Item price. |
purchase.description.items.quantity |
integer | Number of items in the purchase. |
purchase.description.items.is_bonus |
boolean | Whether an item is free and available as a bonus. Default is 'false'. |
purchase.gift |
object | Gift details (object). |
purchase.gift.giver_id |
string | Giver ID. |
purchase.gift.message |
string | Message from the giver. |
purchase.gift.hide_giver_from_receiver |
string | Whether to hide the giver identity from the recipient. 'true' by default. |
purchase.gift.friends |
array | Array with data on friends. |
purchase.gift.friends.id |
string | Gift recipient ID. |
purchase.gift.friends.name |
string | Gift recipient nickname. |
purchase.gift.friends.email |
string | Gift recipient email. |
purchase.coupon_code |
object | Information about a discount promo code or bonuses upon purchase (object). |
purchase.coupon_code.value |
string | Promo code value. |
purchase.coupon_code.hidden |
boolean | Hide the field promo code is entered into in the payment UI. 'false' by default. |
custom_parameters |
object | Your custom parameters, represented as a valid JSON set of key-value pairs. |
If any parameter is sent in the wrong format or has the wrong type, no token will be issued. You will receive a 422 HTTP code with the error description in the JSON body. In "extended_message" we will provide you an information what exactly parameters have been send incorrectly.
{
"extended_message": {
"global_errors": [],
"property_errors": {
"settings.project_id": [
"string value found, but an integer is required"
]
}
}
}
-
http
-
curl
-
php
-
C#
-
python
-
ruby
-
java
-
js
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token
Headers:
Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json
Body:
{
"purchase": {
"virtual_currency": {
"quantity": 100
},
"virtual_items": {
"items": [
{
"amount": 1,
"sku": "SKU01"
}
]
}
},
"settings": {
"currency": "USD",
"language": "en",
"project_id": 16184,
"ui": {
"components": {
"virtual_currency": {
"custom_amount": true
}
},
"desktop": {
"virtual_item_list": {
"button_with_price": true,
"layout": "list"
}
},
"size": "medium"
}
},
"user": {
"country": {
"allow_modify": true,
"value": "US"
},
"email": {
"value": "john.smith@mail.com"
},
"id": {
"value": "user_2"
},
"name": {
"value": "John Smith"
}
}
}
curl --request POST \
--url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
--header 'authorization: Basic <your_authorization_basic_key>' \
--header 'content-type: application/json' \
--data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');
$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Basic <your_authorization_basic_key>',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import http.client
conn = http.client.HTTPSConnection("api.xsolla.com")
payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"
headers = {
'content-type': "application/json",
'authorization': "Basic <your_authorization_basic_key>"
}
conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, 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}/token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
Request request = new Request.Builder()
.url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("authorization", "Basic <your_authorization_basic_key>")
.build();
Response response = client.newCall(request).execute();
var data = JSON.stringify({
"user": {
"id": {
"value": "user_2"
},
"name": {
"value": "John Smith"
},
"email": {
"value": "john.smith@mail.com"
},
"country": {
"value": "US",
"allow_modify": true
}
},
"settings": {
"project_id": 16184,
"currency": "USD",
"language": "en",
"ui": {
"size": "medium",
"desktop": {
"virtual_item_list": {
"layout": "list",
"button_with_price": true
}
},
"components": {
"virtual_currency": {
"custom_amount": true
}
}
}
},
"purchase": {
"virtual_currency": {
"quantity": 100
},
"virtual_items": {
"items": [
{
"sku": "SKU01",
"amount": 1
}
]
}
}
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
xhr.send(data);
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
Additional Parameters List
You can pass additional parameters in the token in the custom_parameters object to configure anti-fraud filters. The recommended parameters are shown in the table below. You can extend the list as needed.
Parameter | Type | Description |
---|---|---|
registration_date |
string | Account creation date per ISO 8601. |
total_hours |
integer | Total number of in-game hours. |
total_characters |
integer | Number of in-game characters. |
social_networks_added |
boolean | Whether the player has connected social media profiles. |
profile_image_added |
boolean | Whether the player has uploaded a profile image. |
active_date |
string | Last seen date per ISO 8601. |
total_friends |
integer | Number of friends. |
additional_verification |
boolean | Whether the player uses account verification procedures. |
win_rate |
integer | Win rate. |
last_change_password_date |
string | Last password change date per ISO 8601. |
chat_activity |
boolean | Whether the player uses the chat function. |
forum_activity |
boolean | Whether the player uses the forum function. |
total_bans |
integer | Number of times the player was banned in the chat/forum. |
profile_completed |
boolean | Whether the player added additional information to their profile. |
notifications_enabled |
boolean | Whether the player enabled notifications. |
user_level |
integer | Player’s level, reputation, or rank. |
karma_points |
integer | Player’s karma. |
total_sum |
float | Total amount of payments. |
non_premium_currency |
float | Amount of non-premium currency. |
total_game_events |
integer | Number of in-game events the player took part in. |
total_gifts |
integer | Number of in-game gifts the player has sent/received. |
tutorial_completed |
boolean | Whether the player has completed the game’s tutorial. |
completed_tasks |
integer | Number of tasks/objectives completed. |
items_used |
boolean | Whether the player uses purchased in-game items. |
pvp_activity |
boolean | Whether the player takes part in PvP battles. |
total_clans |
integer | Number of clans the player is a member of. |
unlocked_achievements |
integer | Number of achievements unlocked. |
total_inventory_value |
float | Total inventory value (in-game currency). |
character_customized |
boolean | Whether the player has customized their character. |
session_time |
string | Average session time per ISO 8601. |
Webhooks
Overview
Webhooks allow you to receive notifications of events that happen to your Xsolla transactions. Use webhooks to automate back-end and supplementary functions, such as providing status and other transaction-related information.
We use webhooks for:
- Payments, including purchases of virtual currency and items, bank card payments, and so on
- Recurring payments and subscription actions
- Transaction-related chargebacks/refunds
In most cases, webhooks are triggered by user actions on your website. But they can come from other actions, too. For example, a back-end process on your website may invoke an API method to refund a payment, or the payment system may send a notification about a disputed charge.
You must write or use a so-called listener, or handler, to receive and process webhooks. This is a program that waits for a webhook and usually passes it to an internal workflow of yours, which responds appropriately.
For example, you can do the following after receiving a webhook:
- Filling up user balance
- Unlocking new item for user
- Starting subscription service
- Blocking user after fraud detection
Listen to webhooks at the following IP addresses: 185.30.20.0/24, 185.30.21.0/24.
Note that your database must NOT contain two successful transactions with the same ID. If your listener receives a webhook with an existing transaction ID, it must return the latest result for that transaction. Avoid charging the user twice or creating duplicate records in your database.
Note that we cannot guarantee that your listener will receive all the webhooks we send. As Internet connections are not 100% reliable, webhooks may fail to come on time or at all. To address these issues, we provide a retry mechanism that re-sends failed messages at various intervals until your listener acknowledges their receipt. A repeated webhook may be sent within 12 hours after the previous one. The maximum number of retries is 12.
Sign Requests
Digital signatures enable secure data transmission. To generate the signature, (1) concatenate the request's JSON body with your project's secret key and (2) apply SHA-1 hashing to the resulting string.
Make sure that the created signature matches the one passed in the HTTP header.
-
http
-
curl
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}'
Response Codes
Xsolla API accepts conventional HTTP response codes for successful and failed requests. Code 204 indicates successful processing. Return code 400 in case of an error in the provided information (e.g., a required parameter missing, a failed recharge, etc.). Use code 500 for temporary errors with your servers.Webhooks List
The type of notification is sent in the notification_type parameter.Notification Type | Description |
---|---|
user_validation | Check if a user exists in the game. |
user_search | Get user info based on Public User ID. |
payment | Sent when a user completes a payment. |
refund | Sent when a payment must be canceled for any reason. |
afs_reject | Sent when a transaction is declined during an AFS check. |
create_subscription | Sent when a user creates a subscription. |
update_subscription | Sent when a subscription is renewed or changed. |
cancel_subscription | Sent when a subscription is canceled. |
get_pincode | Sent when Xsolla API needs to obtain the game keys. |
user_balance_operation | Sent when a user balance changes (the type of operation is sent in operation_type). |
redeem_key | Sent when a user activates a key. |
upgrade_refund | Sent when the upgrade is cancelled. |
inventory_get | Get items list from the game inventory to the secondary market. |
inventory_pull | Pull items from the game inventory to the secondary market. |
inventory_push | Push items from the secondary market to game inventory. |
User Validation
Sent to verify that a user exists in the game.Parameter | Type | Description |
---|---|---|
user |
object | User details (object). |
user.ip |
string | User IP. |
user.phone |
string | User phone. |
user.email |
string | User email. |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.country |
string | User's country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'user_validation',
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email'=> 'email@example.com',
'id'=> '1234567',
'country' => 'US'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type":"user_validation",
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"user_validation",
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isUserValidation()) {
$userArray = $message->getUser();
$userId = $message->getUserId();
$messageArray = $message->toArray();
//TODO if user not found, you should throw InvalidUserException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
User Search
Sent to retrieve user details using their Public User ID — a parameter that uniquely identifies the user and is known to them (email, screen name, etc). It allows the user to make purchases outside the game store (e.g., via cash kiosks).Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. Required. |
user |
object | User details (object). Required. |
user.public_id |
string | Public user ID. |
user.id |
string | User ID. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'user_search',
'user' => array(
'public_id' => 'public_email@example.com'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type":"user_search",
"user": {
"public_id": "public_email@example.com"
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"user_search",
"user": {
"public_id": "public_email@example.com"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
$callback = function (Message $message) {
if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
$userArray = $message->getUser();
$userPublicId = $message->getUserPublicId();
// TODO get a user from your database and fill the user data to model.
$user = new \Xsolla\SDK\Webhook\User();
$user->setId('user_id')
->setPublicId($userPublicId)
->setEmail('user_email') //Optional field
->setPhone('user_phone') //Optional field
->setName('user_name'); //Optional field
//TODO if user not found, you should throw InvalidUserException
return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json
{
"user": {
"public_id": "public_email@example.com",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User"
}
}
{
"user": {
"public_id": "public_email@example.com",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User"
}
}
Payment
Sent whenever a user completes a payment. Includes payment details.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. Required. |
purchase |
object | Purchase details (object). |
purchase.virtual_currency |
object | Virtual currency to purchase (object). |
purchase.virtual_currency.name |
string | Virtual currency name. |
purchase.virtual_currency.sku |
string | Virtual currency package SKU (if set for the virtual currency package). |
purchase.virtual_currency.quantity |
float | Quantity. |
purchase.virtual_currency.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_currency.amount |
float | Price in real currency. |
purchase.checkout |
object | Checkout details (object). |
purchase.checkout.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.checkout.amount |
float | Purchase amount. |
purchase.subscription |
object | Subscription details (object). |
purchase.subscription.plan_id |
string | Plan ID (external if the plan was created via API). |
purchase.subscription.subscription_id |
integer | Subscription ID in Xsolla database. |
purchase.subscription.product_id |
string | Product ID (if sent in the access token). |
purchase.subscription.tags |
array | Plan tags. |
purchase.subscription.date_create |
string | Subscription creation date. Date and time per ISO 8601. |
purchase.subscription.date_next_charge |
string | Next billing date. Date and time per ISO 8601. |
purchase.subscription.currency |
string | Subscription currency. Three-letter currency code per ISO 4217. |
purchase.subscription.amount |
float | Price in real currency. |
purchase.virtual_items |
object | Virtual items in purchase (object). |
purchase.virtual_items.items |
array | Item data (array). |
purchase.virtual_items.items.sku |
string | Item ID. |
purchase.virtual_items.items.amount |
integer | Item quantity. |
purchase.virtual_items.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_items.amount |
integer | Purchase amount. |
purchase.pin_codes |
object | Game keys (array). |
purchase.pin_codes.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.drm |
string | DRM platform used to distribute the game. Can be 'steam', 'playstation', 'xbox', 'uplay', 'origin', 'drmfree', 'gog', 'epicgames', 'nintendo_eshop', 'discord_game_store', or 'oculus'. Make sure that you have configured the required DRM platforms in your Publisher Account. |
purchase.pin_codes.currency |
string | Currency that the game keys is purchased for. Three-letter currency code per ISO 4217. |
purchase.pin_codes.amount |
float | Price. |
purchase.pin_codes.upgrade |
object | Object with upgrade data. |
purchase.pin_codes.upgrade.digital_content_from |
object | Object with data on the package, from which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_from.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_from.DRM |
string | Game DRM platform. |
purchase.pin_codes.upgrade.digital_content_to |
object | Object with data on the package, to which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_to.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_to.DRM |
string | Game DRM platform. |
purchase.pin_codes.upgrade.currency |
string | Purchase currency. Three-letter currency code per ISO 4217. |
purchase.pin_codes.upgrade.amount |
float | Price in real currency. |
purchase.gift |
object | Gift details (object). |
purchase.gift.giver_id |
string | Giver ID. |
purchase.gift.receiver_id |
string | Gift recipient ID. |
purchase.gift.receiver_email |
string | Gift recipient email. |
purchase.gift.message |
string | Message from the giver. |
purchase.gift.hide_giver_from_receiver |
string | Whether to hide the giver identity from the recipient. |
purchase.total |
object | Total price of purchase (object). Required. |
purchase.total.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.total.amount |
float | Total payment amount. |
purchase.promotions |
array | Promotions applied to this transaction (array). |
purchase.promotions.technical_name |
string | Technical name of the promotion. |
purchase.promotions.id |
integer | Promotion ID. |
purchase.coupon |
object | Coupon details (object; if a coupon was used when creating the subscription). |
purchase.coupon.coupon_code |
string | Coupon code. |
purchase.coupon.campaign_code |
string | Campaign code. |
user |
object | User details (object). |
user.ip |
string | User IP. |
user.phone |
string | User phone. |
user.email |
string | User email. |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.country |
string | User's country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.zip |
string | User's ZIP or postal code. |
transaction |
object | Transaction details (object). Required. |
transaction.id |
integer | Transaction ID. |
transaction.external_id |
string | Transaction external ID. |
transaction.payment_date |
string | Date of payment. |
transaction.payment_method |
integer | Payment method identifier. |
transaction.dry_run |
integer | Test transaction. 1 if test transaction, 0 if not. |
transaction.agreement |
integer | Agreement ID. |
payment_details |
object | Payment details (object). Required. |
payment_details.payment |
object | Amount paid by the user (object). |
payment_details.payment.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment.amount |
string | Amount. |
payment_details.payment_method_sum |
object | Amount debited from the payment system. |
payment_details.payment_method_sum.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_sum.amount |
string | Amount. |
payment_details.xsolla_balance_sum |
object | Amount debited from Xsolla balance. |
payment_details.xsolla_balance_sum.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_balance_sum.amount |
string | Amount. |
payment_details.payout |
object | Payout details (object). |
payment_details.payout.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payout.amount |
float | Amount. |
payment_details.vat |
object | VAT details (object; EU only). |
payment_details.vat.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.vat.amount |
float | Amount. |
payment_details.payout_currency_rate |
float | Exchange rate between payment and payout currencies. |
payment_details.xsolla_fee |
object | Xsolla fee (object). |
payment_details.xsolla_fee.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_fee.amount |
float | Amount. |
payment_details.payment_method_fee |
object | Payment system fee. |
payment_details.payment_method_fee.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_fee.amount |
float | Amount. |
payment_details.sales_tax |
object | Sales tax (object; USA only). |
payment_details.sales_tax.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.sales_tax.amount |
float | Amount. |
payment_details.repatriation_commission |
object | Object with data on repatriation costs, imposed on Xsolla by third parties. |
payment_details.repatriation_commission.currency |
string | Repatriation costs currency. Three-letter currency code per ISO 4217. |
payment_details.repatriation_commission.amount |
float | Repatriation costs amount. |
custom_parameters |
object | Your custom parameters. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'payment',
'purchase' => array(
'virtual_currency' => array(
'name' => 'Coins',
'quantity' => 100,
'currency' => 'USD',
'amount' => 9.99
),
'total' => array(
'currency' => 'USD',
'amount' => 9.99
)
),
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email' => 'email@example.com',
'id' => '1234567',
'country' => 'US'
),
'transaction' => array(
'id' => 87654321,
'payment_date' => '2014-09-23T19:25:25+04:00',
'payment_method' => 1380,
'dry_run' => 1
),
'payment_details' => array(
'payment' => array(
'currency' => 'USD',
'amount' => 9.99
),
'vat' => array(
'currency' => 'USD',
'amount' => 0
),
'payout_currency_rate' => 1,
'payout' => array(
'currency' => 'USD',
'amount' => 9.49
),
'xsolla_fee' => array(
'currency' => 'USD',
'amount' => 0.19
),
'payment_method_fee' => array(
'currency' => 'USD',
'amount' => 0.31
),
'repatriation_commission' => array(
'currency' => 'USD',
'amount' => 0.2
)
)
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1721
Authorization: Signature 34553d151e656110c656696c919f9a10e05de542
{
"notification_type":"payment",
"purchase":{
"virtual_currency":{
"name":"Coins",
"sku":"test_package1",
"quantity":10,
"currency":"USD",
"amount":100
},
"subscription":{
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_next_charge": "2014-10-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout":{
"currency":"USD",
"amount":50
},
"virtual_items":{
"items":[
{
"sku": "test_item1",
"amount":1
}
],
"currency":"USD",
"amount":50
},
"total":{
"currency":"USD",
"amount":200
},
"promotions":[{
"technical_name":"Demo Promotion",
"id":"853"
}],
"coupon":{
"coupon_code":"ICvj45S4FUOyy",
"campaign_code":"1507"
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction":{
"id":1,
"external_id":1,
"payment_date":"2014-09-24T20:38:16+04:00",
"payment_method":1,
"dry_run":1,
"agreement":1
},
"payment_details":{
"payment":{
"currency":"USD",
"amount":230
},
"vat": {
"currency": "USD",
"amount": 0
},
"payout_currency_rate": 1,
"payout":{
"currency":"USD",
"amount":200
},
"xsolla_fee":{
"currency":"USD",
"amount":10
},
"payment_method_fee":{
"currency":"USD",
"amount":20
},
"repatriation_commission":{
"currency":"USD",
"amount":"10"
}
},
"custom_parameters":{
"parameter1":"value1",
"parameter2":"value2"
}
}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type":"payment",
"purchase":{
"virtual_currency":{
"name":"Coins",
"sku":"test_package1",
"quantity":10,
"currency":"USD",
"amount":100
},
"subscription":{
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_next_charge": "2014-10-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout":{
"currency":"USD",
"amount":50
},
"virtual_items":{
"items":[
{
"sku": "test_item1",
"amount":1
}
],
"currency":"USD",
"amount":50
},
"total":{
"currency":"USD",
"amount":200
},
"promotions":[{
"technical_name":"Demo Promotion",
"id":"853"
}],
"coupon":{
"coupon_code":"ICvj45S4FUOyy",
"campaign_code":"1507"
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction":{
"id":1,
"external_id":1,
"payment_date":"2014-09-24T20:38:16+04:00",
"payment_method":1,
"dry_run":1,
"agreement":1
},
"payment_details":{
"payment":{
"currency":"USD",
"amount":230
},
"vat": {
"currency": "USD",
"amount": 0
},
"payout_currency_rate": 1,
"payout":{
"currency":"USD",
"amount":200
},
"xsolla_fee":{
"currency":"USD",
"amount":10
},
"payment_method_fee":{
"currency":"USD",
"amount":20
},
"repatriation_commission":{
"currency":"USD",
"amount":"10"
}
},
"custom_parameters":{
"parameter1":"value1",
"parameter2":"value2"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isPayment()) {
$userArray = $message->getUser();
$paymentArray = $message->getTransaction();
$paymentId = $message->getPaymentId();
$externalPaymentId = $message->getExternalPaymentId();
$paymentDetailsArray = $message->getPaymentDetails();
$customParametersArray = $message->getCustomParameters();
$isDryRun = $message->isDryRun();
$messageArray = $message->toArray();
// TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Refund
Sent whenever a payment is canceled. Includes payment details.
Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. Required. |
purchase |
object | Purchase details (object). |
purchase.virtual_currency |
object | Virtual currency to purchase (object). |
purchase.virtual_currency.name |
string | Virtual currency name. |
purchase.virtual_currency.quantity |
float | Quantity. |
purchase.virtual_currency.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_currency.amount |
float | Price in real currency. |
purchase.checkout |
object | Checkout details (object). |
purchase.checkout.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.checkout.amount |
float | Purchase amount. |
purchase.subscription |
object | Subscription details (object). |
purchase.subscription.plan_id |
string | Plan ID (external if the plan was created via API). |
purchase.subscription.tags |
array | Plan tags. |
purchase.subscription.subscription_id |
integer | Subscription ID in Xsolla database. |
purchase.subscription.date_create |
string | Subscription creation date. Date and time per ISO 8601. |
purchase.subscription.currency |
string | Subscription currency. Three-letter currency code per ISO 4217. |
purchase.subscription.amount |
float | Price in real currency. |
purchase.virtual_items |
object | Virtual items in purchase (object). |
purchase.virtual_items.items |
array | Item data (array). |
purchase.virtual_items.items.sku |
string | Item ID. |
purchase.virtual_items.items.amount |
integer | Item quantity. |
purchase.virtual_items.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_items.amount |
integer | Purchase amount. |
purchase.pin_codes |
object | Game keys (object). |
purchase.pin_codes.upgrade |
object | Object with upgrade data. |
purchase.pin_codes.upgrade.digital_content_from |
object | Object with data on the package, from which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_from.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_from.DRM |
string | Game DRM platform. |
purchase.pin_codes.upgrade.digital_content_to |
object | Object with data on the package, to which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_to.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_to.DRM |
string | Game DRM platform. |
purchase.pin_codes.upgrade.currency |
string | Purchase currency. Three-letter currency code per ISO 4217. |
purchase.pin_codes.upgrade.amount |
float | Price in real currency. |
purchase.total |
object | Total price of purchase (object). |
purchase.total.currency |
string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.total.amount |
float | Total payment amount. |
user |
object | User details (object). |
user.ip |
string | User IP. |
user.phone |
string | User phone. |
user.email |
string | User email. |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.country |
string | User's country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.zip |
string | User's ZIP or postal code. |
transaction |
object | Transaction details (object). Required. |
transaction.id |
integer | Transaction ID. |
transaction.external_id |
string | Transaction external ID. |
transaction.dry_run |
integer | Test transaction. 1 if test transaction, 0 if not. |
transaction.agreement |
integer | Agreement ID. |
refund_details |
object | Refund details (object). |
refund_details.code |
integer | Code ID. |
refund_details.reason |
string | Refund reason. |
refund_details.author |
string | Refund initiator. |
payment_details |
object | Payment details (object). Required. |
payment_details.payment |
object | Amount paid by the user (object). |
payment_details.payment.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment.amount |
string | Amount. |
payment_details.payment_method_sum |
object | Amount debited from the payment system. |
payment_details.payment_method_sum.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_sum.amount |
string | Amount. |
payment_details.xsolla_balance_sum |
object | Amount debited from Xsolla balance. |
payment_details.xsolla_balance_sum.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_balance_sum.amount |
string | Amount. |
payment_details.payout |
object | Payout details (object). |
payment_details.payout.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payout.amount |
float | Amount. |
payment_details.vat |
object | VAT details (object; EU only). |
payment_details.vat.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.vat.amount |
float | Amount. |
payment_details.payout_currency_rate |
float | Exchange rate between payment and payout currencies. |
payment_details.xsolla_fee |
object | Xsolla fee (object). |
payment_details.xsolla_fee.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_fee.amount |
float | Amount. |
payment_details.payment_method_fee |
object | Payment system fee. |
payment_details.payment_method_fee.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_fee.amount |
float | Amount. |
payment_details.sales_tax |
object | Sales tax (object; USA only). |
payment_details.sales_tax.currency |
string | Currency. Three-letter currency code per ISO 4217. |
payment_details.sales_tax.amount |
float | Amount. |
payment_details.repatriation_commission |
object | Object with data on repatriation costs, imposed on Xsolla by third parties. |
payment_details.repatriation_commission.currency |
string | Repatriation costs currency. Three-letter currency code per ISO 4217. |
payment_details.repatriation_commission.amount |
float | Repatriation costs amount. |
custom_parameters |
object | Your custom parameters. |
Refund codes:
Code | Reason | Description |
---|---|---|
1. | Cancellation by the user request / the game request. | Cancellation initiated from Publisher Account. |
2. | Chargeback. | Transaction chargeback requested. |
3. | Integration Error. | Issues in integration between Xsolla and the game. Recommendation: Do not blacklist the user. |
4. | Fraud. | Fraud suspected. |
5. | Test Payment. | Test transaction followed by cancellation. Recommendation: Do not blacklist the user. |
6. | Expired Invoice. | Invoice overdue (used for postpaid model). |
7. | PS debt cancel. | Payout refused by payment system. Recommendation: Do not blacklist the user. |
8. | Cancellation by the PS request. | Cancellation requested by payment system. Recommendation: Do not blacklist the user. |
9. | Cancellation by the user request. | The user was not satisfied with the game or the purchase for any reason. Recommendation: Do not blacklist the user. |
10. | Cancellation by the game request. | Cancellation requested by the game. Recommendation: Do not blacklist the user. |
11. | Account holder called to report fraud. | The account owner states that they didn't make the transaction. |
12. | Friendly fraud. | Friendly fraud reported. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'refund',
'purchase' => array(
'virtual_currency' => array(
'name' => 'Coins',
'quantity' => 100,
'currency' => 'USD',
'amount' => 9.99
),
'total' => array(
'currency' => 'USD',
'amount' => 9.99
)
),
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email' => 'email@example.com',
'id' => '1234567',
'country' => 'US'
),
'transaction' => array(
'id' => 87654321,
'payment_date' => '2014-09-23T19:25:25+04:00',
'payment_method' => 1380,
'dry_run' => 1
),
'refund_details' => array(
'code' => 1,
'reason' => 'Fraud'
),
'payment_details' => array(
'payment' => array(
'currency' => 'USD',
'amount' => 9.99
),
'vat' => array(
'currency' => 'USD',
'amount' => 0
),
'payout_currency_rate' => 1,
'payout' => array(
'currency' => 'USD',
'amount' => 9.49
),
'xsolla_fee' => array(
'currency' => 'USD',
'amount' => 0.19
),
'payment_method_fee' => array(
'currency' => 'USD',
'amount' => 0.31
),
'repatriation_commission' => array(
'currency' => 'USD',
'amount' => 0.2
)
)
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
{
"notification_type":"refund",
"purchase":{
"virtual_currency":{
"name": "Coins",
"quantity":10,
"currency":"USD",
"amount":100
},
"subscription":{
"plan_id": "b5dac9c8",
"subscription_id": "10",
"date_create": "2014-09-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout":{
"currency":"USD",
"amount":50
},
"virtual_items":{
"items":[
{
"sku": "test_item1",
"amount":1
}
],
"currency":"USD",
"amount":50
},
"total":{
"currency":"USD",
"amount":200
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction":{
"id":1,
"external_id":1,
"dry_run":1,
"agreement":1
},
"refund_details":{
"code":1,
"reason":"Fraud"
},
"payment_details":{
"xsolla_fee":{
"currency":"USD",
"amount":"10"
},
"payout":{
"currency":"USD",
"amount":"200"
},
"payment_method_fee":{
"currency":"USD",
"amount":"20"
},
"payment":{
"currency":"USD",
"amount":"230"
},
"repatriation_commission":{
"currency":"USD",
"amount":"10"
}
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type":"refund",
"purchase":{
"virtual_currency":{
"name": "Coins",
"quantity":10,
"currency":"USD",
"amount":100
},
"subscription":{
"plan_id": "b5dac9c8",
"subscription_id": "10",
"date_create": "2014-09-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout":{
"currency":"USD",
"amount":50
},
"virtual_items":{
"items":[
{
"sku": "test_item1",
"amount":1
}
],
"currency":"USD",
"amount":50
},
"total":{
"currency":"USD",
"amount":200
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction":{
"id":1,
"external_id":1,
"dry_run":1,
"agreement":1
},
"refund_details":{
"code":1,
"reason":"Fraud"
},
"payment_details":{
"xsolla_fee":{
"currency":"USD",
"amount":"10"
},
"payout":{
"currency":"USD",
"amount":"200"
},
"payment_method_fee":{
"currency":"USD",
"amount":"20"
},
"payment":{
"currency":"USD",
"amount":"230"
},
"repatriation_commission":{
"currency":"USD",
"amount":"10"
}
}
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isRefund()) {
$userArray = $message->getUser();
$paymentArray = $message->getTransaction();
$paymentId = $message->getPaymentId();
$externalPaymentId = $message->getExternalPaymentId();
$paymentDetailsArray = $message->getPaymentDetails();
$customParametersArray = $message->getCustomParameters();
$isDryRun = $message->isDryRun();
$refundArray = $message->getRefundDetails();
$messageArray = $message->toArray();
// TODO if you cannot handle the refund, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Upgrade Refund
When a user refunds the payment associated with the upgrade, Xsolla sends the data on all cancelled upgrades and the current game package to the webhook URL.Parameter | Type | Description |
---|---|---|
notification_type |
string | Notification type. Required. |
purchase |
object | Object with the purchase data. Required. |
purchase.pin_codes |
object | Object with data on the purchased game packages. |
purchase.pin_codes.purchase_type |
string | Purchase type. Can be “regular” (purchasing the package) or “upgrade” (upgrading the package). |
purchase.pin_codes.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.DRM |
string | Game DRM platform. |
purchase.pin_codes.currency |
string | Purchase currency. Three-letter currency code per ISO 4217. |
purchase.pin_codes.amount |
float | Price in real currency. |
purchase.pin_codes.transaction |
object | Object with the transaction data. |
purchase.pin_codes.transaction.id |
integer | Transaction ID. |
purchase.pin_codes.upgrade |
object | Object with the upgrade data. |
purchase.pin_codes.upgrade.digital_content_from |
object | Object with data on the package, from which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_from.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_from.DRM |
string | Game DRM platform. |
purchase.pin_codes.upgrade.digital_content_to |
object | Object with data on the package, to which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_to.digital_content |
string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_to.DRM |
string | Game DRM platform. |
ownership |
object | Object with data on packages owned by the user. Required. |
ownership.digital_content |
string | Game SKU set in Publisher Account. |
ownership.DRM |
string | Game DRM platform. |
-
php
-
http
-
curl
<?php
$request = array (
'notification_type' => 'upgrade_refund',
'purchase' =>
array (
'pin_codes' =>
array (
0 =>
array (
'purchase_type' => 'regular',
'digital_content' => 'silver',
'DRM' => 'drmfree',
'currency' => 'USD',
'amount' => '40',
'transaction' =>
array (
'id' => '361697569',
),
),
1 =>
array (
'purchase_type' => 'upgrade',
'upgrade' =>
array (
'digital_content_from' =>
array (
'digital_content' => 'silver',
'DRM' => 'drmfree',
),
'digital_content_to' =>
array (
'digital_content' => 'gold',
'DRM' => 'drmfree',
),
),
'currency' => 'USD',
'amount' => '20',
'transaction' =>
array (
'id' => '361697570'
),
),
2 =>
array (
'purchase_type' => 'upgrade',
'upgrade' =>
array (
'digital_content_from' =>
array (
'digital_content' => 'gold',
'DRM' => 'drmfree',
),
'digital_content_to' =>
array (
'digital_content' => 'platinum',
'DRM' => 'drmfree',
),
),
'currency' => 'USD',
'amount' => '20',
'transaction' =>
array (
'id' => '361697571'
),
),
),
),
'ownership' =>
array (
'digital_content' => NULL,
'DRM' => NULL,
),
)
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Authorization: Signature <signature>
{
"notification_type": "upgrade_refund",
"purchase": {
"pin_codes": [
{
"purchase_type": "regular",
"digital_content": "silver",
"DRM": "drmfree",
"currency": "USD",
"amount": "40",
"transaction": {
"id": "361697569"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "silver",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "gold",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697570"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "gold",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "platinum",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697571"
}
}
]
},
"ownership": {
"digital_content": null,
"DRM": null
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type": "upgrade_refund",
"purchase": {
"pin_codes": [
{
"purchase_type": "regular",
"digital_content": "silver",
"DRM": "drmfree",
"currency": "USD",
"amount": "40",
"transaction": {
"id": "361697569"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "silver",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "gold",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697570"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "gold",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "platinum",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697571"
}
}
]
},
"ownership": {
"digital_content": null,
"DRM": null
}
}'
AFS Rejected Transaction
When a transaction is declined during an AFS check, Xsolla sends transaction details to the URL webhook. To enable this notification, please contact the account manager.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. Required. |
user |
object | User details (object). |
user.ip |
string | User IP. |
user.phone |
string | User phone. |
user.email |
string | User email. |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.country |
string | User's country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.zip |
string | User's ZIP or postal code. |
transaction |
object | Transaction details (object). Required. |
transaction.id |
integer | Transaction ID. |
transaction.external_id |
string | Transaction external ID. |
transaction.dry_run |
integer | Test transaction. 1 if test transaction, 0 if not. |
transaction.agreement |
integer | Agreement ID. |
refund_details |
object | Refund details (object). |
refund_details.code |
integer | Code ID. |
refund_details.reason |
string | Refund reason. |
refund_details.author |
string | Refund initiator. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'afs_reject',
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email' => 'email@example.com',
'id' => '1234567',
'country' => 'US'
),
'transaction' => array(
'id' => 87654321,
'payment_date' => '2014-09-23T19:25:25+04:00',
'payment_method' => 1380,
'dry_run' => 1
),
'refund_details' => array(
'code' => 4,
'reason' => 'Potential fraud'
)
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
{
"notification_type":"afs_reject",
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "semail@example.com,
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction":{
"id":1,
"external_id":1,
"dry_run":1,
"agreement":1
},
"refund_details":{
"code":4,
"reason":"Potential fraud"
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type":"afs_reject",
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "semail@example.com,
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction":{
"id":1,
"external_id":1,
"dry_run":1,
"agreement":1
},
"refund_details":{
"code":4,
"reason":"Potential fraud"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isRefund()) {
$userArray = $message->getUser();
$paymentArray = $message->getTransaction();
$paymentId = $message->getPaymentId();
$externalPaymentId = $message->getExternalPaymentId();
$customParametersArray = $message->getCustomParameters();
$isDryRun = $message->isDryRun();
$refundArray = $message->getRefundDetails();
$messageArray = $message->toArray();
// TODO if you cannot handle the refund, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Created Subscription
When a user creates a subscription, we send a notification to your payment notification script.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. Required. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
subscription |
object | Subscription details (object). |
subscription.plan_id |
string | Plan ID (external if the plan was created via API). |
subscription.tags |
array | Plan tags. |
subscription.subscription_id |
integer | Subscription ID in Xsolla database. |
subscription.product_id |
string | Product ID (if sent in the access token). |
subscription.date_create |
string | Subscription creation date. Date and time per ISO 8601. |
subscription.date_next_charge |
string | Next billing date. Date and time per ISO 8601. |
subscription.trial |
object | Trial period (object). |
subscription.trial.value |
integer | Trial period. |
subscription.trial.type |
string | Trial period type: day. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'create_subscription',
'user' => array(
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => array(
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_next_charge' => '2015-01-22T19:25:25+04:00',
'trial' => array(
'value' => 90,
'type' => 'day'
)
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type":"create_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_create":"2014-09-22T19:25:25+04:00",
"date_next_charge":"2015-01-22T19:25:25+04:00",
"trial": {
"value": 90,
"type": "day"
}
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"create_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_create":"2014-09-22T19:25:25+04:00",
"date_next_charge":"2015-01-22T19:25:25+04:00",
"trial": {
"value": 90,
"type": "day"
}
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof CreateSubscriptionMessage) {
$messageArray = $message->toArray();
// TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Updated Subscription
If some parameters in subscription ("plan_id", "date_next_charge") were changed and in case of every subscription renewal, we send the notification "update_subscription" on your webhook URL.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. Required. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
subscription |
object | Subscription details (object). |
subscription.plan_id |
string | Plan ID (external if the plan was created via API). |
subscription.tags |
array | Plan tags. |
subscription.subscription_id |
integer | Subscription ID in Xsolla database. |
subscription.product_id |
string | Product ID (if sent in the access token). |
subscription.date_next_charge |
string | Next billing date. Date and time per ISO 8601. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'update_subscription',
'user' => array(
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => array(
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_next_charge' => '2015-01-22T19:25:25+04:00'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type":"update_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_next_charge":"2015-01-22T19:25:25+04:00"
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"update_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_next_charge":"2015-01-22T19:25:25+04:00"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UpdateSubscriptionMessage) {
$messageArray = $message->toArray();
// TODO if the subscription renewing fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Canceled Subscription
When a subscription is canceled for any reason, we send a notification to your payment notification script.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. Required. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
subscription |
object | Subscription details (object). |
subscription.plan_id |
string | Plan ID (external if the plan was created via API). |
subscription.tags |
array | Plan tags. |
subscription.subscription_id |
integer | Subscription ID in Xsolla database. |
subscription.product_id |
string | Product ID (if sent in the access token). |
subscription.date_create |
string | Subscription creation date. Date and time per ISO 8601. |
subscription.date_end |
string | Subscription termination date. Date and time per ISO 8601. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'cancel_subscription',
'user' => array(
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => array(
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_end' => '2015-01-22T19:25:25+04:00',
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type":"cancel_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_create":"2014-09-22T19:25:25+04:00",
"date_end":"2015-01-22T19:25:25+04:00"
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"cancel_subscription",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"subscription":{
"plan_id":"b5dac9c8",
"subscription_id":"10",
"product_id":"Demo Product",
"date_create":"2014-09-22T19:25:25+04:00",
"date_end":"2015-01-22T19:25:25+04:00"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof CancelSubscriptionMessage) {
$messageArray = $message->toArray();
// TODO if the subscription canceling fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Get Game Keys
We will be making API calls to your server to obtain game activation codes after each successful payment.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
pin_code |
object | Game keys details (object). |
pin_code.digital_content |
string | Game SKU. |
pin_code.DRM |
string | DRM platform used to distribute the game. |
-
php
-
http
-
curl
<?php
$request = array (
'notification_type' => 'get_pincode',
'user' =>
array (
'id' => '1234567',
'name' => 'Xsolla User',
),
'pin_code' =>
array (
'digital_content' => 'Game SKU',
'DRM' => 'Steam',
),
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type":"get_pincode",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"pin_code":{
"digital_content":"Game SKU",
"DRM":"Steam"
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"get_pincode",
"user":{
"id":"1234567",
"name":"Xsolla User"
},
"pin_code":{
"digital_content":"Game SKU",
"DRM":"Steam"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof GetPinCodeMessage) {
$userArray = $message->getUser();
$drmSku = $message->getDRM();
$digitalContentSku = $message->getDigitalContent();
// TODO get a pin code from your database or generate a new one. Put the pin code into variable $newPinCode
$newPinCode = 'NEW_PIN_CODE';
// TODO if the pin code creation or generation fail for some reason, you should throw XsollaWebhookException
return new \Xsolla\SDK\Webhook\Response\PinCodeResponse($newPinCode);
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json
{
"pin_code": "PIN_CODE"
}
Activate key
When a user activates a key, Xsolla sends a notification to your webhook URL.Parameter | Type | Description |
---|---|---|
notification_type |
string | Notification type. |
key |
string | Activation key. |
sku |
string | Unique key package ID. |
user_id |
string | User ID. |
activation_date |
datetime | Key activation date in the YYYYMMDDHHMMSS format per ISO 8601. |
user_country |
string | User country. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used. |
restriction |
object | Object with regional restriction cluster settings. The cluster includes a restriction type and a list of countries, servers and locales for which the game is available. |
restriction.sku |
string | Unique cluster ID. |
restriction.name |
string | Cluster name. |
restriction.types |
array | Array of restriction types. |
restriction_countries |
array | Array of countries in the cluster. |
restriction.servers |
array | Array of game servers. |
restriction.locales |
array | Array of locales. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'redeem_key',
'key' => ‘wqdqwwddq9099022’,
'sku' => 123,
'user_id' => ‘sample_user’,
'activation_date' => ‘2018-11-20T08:38:51+03:00’,
'user_country' => ‘EN’,
'restriction' =>
array(
'name' => ‘cls_1’,
'types' =>
array(
‘activation’
),
'countries' =>
array(
‘RU’
),
),
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
"notification_type": "redeem_key",
"key": "wqdqwwddq9099022",
"sku": "123",
"user_id": "sample_user",
"activation_date": "2018-11-20T08:38:51+03:00",
"user_country": "EN",
"restriction": {
"name": "cls_1",
"types": [
"activation"
],
"countries": [
"RU"
]
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type": "redeem_key",
"key": "wqdqwwddq9099022",
"sku": "123",
"user_id": "sample_user",
"activation_date": "2018-11-20T08:38:51+03:00",
"user_country": "EN",
"restriction": {
"name": "cls_1",
"types": [
"activation"
],
"countries": [
"RU"
]
}
}'
<?php
$response = null;
HTTP/1.1 204 No Content
Get Friends
The API should be implemented on the partner’s side. The maximum number of friends is 2000. See the recipe.
HTTP REQUEST
GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1
Parameter | Type | Description |
---|---|---|
notification_type |
string | ID that defines the type of request to get the list of friends. The value is 'friends_list'. |
user |
string | Unique ID of the user buying the gift. |
query |
string | Friend’s name or ID (full or partial). |
limit |
string | Limit for the number of elements on the page. Required. |
offset |
integer | Number of the element from which the list is generated (the count starts from 0). |
sign |
string | Signature line, generated as follows:
|
-
http
-
curl
GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1 HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
$ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
-X GET \
-u merchant_id:merchant_api_key
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"friends": [
{
"id": "1",
"name": "doctor",
"email": "doctor@hospital.com",
"image_url": "https://partner/link/doctor.jpg"
},
{
"id": "2",
"name": "cook",
"email": "cook@kitchen.com",
"image_url": "https://partner/link/cook.jpg"
},
{
"id": "3",
"name": "teacher",
"email": "teacher@school.com"
},
{
"id": "4",
"name": "god",
"email": "god@heaven.com",
"image_url": "https://partner/link/god.jpg"
}
],
"total": 10
}
]
[
{
"friends": [
{
"id": "1",
"name": "John Carter",
"email": "carter@xsolla.com",
"image_url": "https://partner/link/doctor.jpg"
},
{
"id": "2",
"name": "John Smith",
"email": "smith@xsolla.com",
"image_url": "https://partner/link/cook.jpg"
}
],
"total": 10
}
]
User Balance: Payment
Sent whenever a user makes a payment.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. |
operation_type |
string | Type of operation. |
id_operation |
integer | Operation ID in Xsolla database. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.email |
string | User email. |
virtual_currency_balance |
object | User balance data (object). |
virtual_currency_balance.old_value |
string | Balance before transaction. |
virtual_currency_balance.new_value |
string | Balance after transaction. |
virtual_currency_balance.diff |
string | Quantity of virtual currency in the purchase. |
transaction |
object | Transaction details (object). Required. |
transaction.id |
integer | Transaction ID. |
transaction.date |
string | Date of transaction. |
-
php
-
http
-
curl
<?php
$request = array(
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '200',
'diff' => '200'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'transaction => array(
'id' => '123456789',
'date' => '2015-05-19T15:54:40+03:00'
),
'operation_type' => 'payment',
'notification_type' => 'user_balance_operation',
'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"200",
"diff":"200"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"transaction":{
"id":"123456789",
"date":"2015-05-19T15:54:40+03:00"
},
"operation_type":"payment",
"notification_type":"user_balance_operation",
"id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"200",
"diff":"200"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"transaction":{
"id":"123456789",
"date":"2015-05-19T15:54:40+03:00"
},
"operation_type":"payment",
"notification_type":"user_balance_operation",
"id_operation":"66989"
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
User Balance: Purchase
Sent when a user purchases something inside the game. Specifies the change in the user's balance.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. |
operation_type |
string | Type of operation. |
id_operation |
integer | Operation ID in Xsolla database. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.email |
string | User email. |
virtual_currency_balance |
object | User balance data (object). |
virtual_currency_balance.old_value |
string | Balance before transaction. |
virtual_currency_balance.new_value |
string | Balance after transaction. |
virtual_currency_balance.diff |
string | Quantity of virtual currency in the purchase. |
items_operation_type |
string | Type of operation made with virtual items. |
items |
array | Virtual items within the purchase (array of objects). |
items.sku |
string | Item ID. |
items.amount |
integer | Item quantity. |
-
php
-
http
-
curl
<?php
$request = array(
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '200',
'diff' => '200'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'operation_type' => 'inGamePurchase',
'notification_type' => 'user_balance_operation',
'items_operation_type' => 'add',
'items' => array(
'sku' => '1468',
'amount' => '2'
),
'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"200",
"diff":"200"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"operation_type":"inGamePurchase",
"notification_type":"user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"200",
"diff":"200"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"operation_type":"inGamePurchase",
"notification_type":"user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation":"66989"
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
User Balance: Redeem Coupon
Sent when a user redeems a coupon to receive virtual items or virtual currency.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. |
operation_type |
string | Type of operation. |
id_operation |
integer | Operation ID in Xsolla database. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.email |
string | User email. |
virtual_currency_balance |
object | User balance data (object). |
virtual_currency_balance.old_value |
string | Balance before transaction. |
virtual_currency_balance.new_value |
string | Balance after transaction. |
virtual_currency_balance.diff |
string | Quantity of virtual currency in the purchase. |
items_operation_type |
string | Type of operation made with virtual items. |
items |
array | Virtual items within the purchase (array of objects). |
items.sku |
string | Item ID. |
items.amount |
integer | Item quantity. |
coupon |
object | Coupon details (object). |
coupon.coupon_code |
string | Coupon code. |
coupon.campaign_code |
string | Campaign code. |
-
php
-
http
-
curl
<?php
$request = array(
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '0',
'diff' => '0'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'operation_type' => 'coupon',
'notification_type' => 'user_balance_operation',
'items_operation_type' => 'add',
'items' => array(
'sku' => '1468',
'amount' => '2'
),
'id_operation' => '66989',
'coupon' => array(
'coupon_code' => 'test123',
'campaign_code' => 'Xsolla Campaign'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"0",
"diff":"0"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"operation_type":"coupon",
"notification_type":"user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation":"66989",
"coupon": {
"coupon_code": "test123",
"campaign_code": "Xsolla Campaign"
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"0",
"diff":"0"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"operation_type":"coupon",
"notification_type":"user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation":"66989",
"coupon": {
"coupon_code": "test123",
"campaign_code": "Xsolla Campaign"
}
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
User Balance: Manual Update
Sent when a user's balance is changed manually.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. |
operation_type |
string | Type of operation. |
id_operation |
integer | Operation ID in Xsolla database. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.email |
string | User email. |
virtual_currency_balance |
object | User balance data (object). |
virtual_currency_balance.old_value |
string | Balance before transaction. |
virtual_currency_balance.new_value |
string | Balance after transaction. |
virtual_currency_balance.diff |
string | Quantity of virtual currency in the purchase. |
-
php
-
http
-
curl
<?php
$request = array(
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '100',
'diff' => '100'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'operation_type' => 'internal',
'notification_type' => 'user_balance_operation',
'id_operation' => '67002'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"100",
"diff":"100"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"operation_type":"internal",
"notification_type":"user_balance_operation",
"id_operation":"67002"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"100",
"diff":"100"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"operation_type":"internal",
"notification_type":"user_balance_operation",
"id_operation":"67002"
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
User Balance: Refund
Sent when a user cancels a payment. Specifies the change in the user's balance.Parameter | Type | Description |
---|---|---|
notification_type |
string | Type of notification. |
operation_type |
string | Type of operation. |
id_operation |
integer | Operation ID in Xsolla database. |
user |
object | User details (object). |
user.id |
string | User ID. Required. |
user.name |
string | Username. |
user.email |
string | User email. |
virtual_currency_balance |
object | User balance data (object). |
virtual_currency_balance.old_value |
string | Balance before transaction. |
virtual_currency_balance.new_value |
string | Balance after transaction. |
virtual_currency_balance.diff |
string | Quantity of virtual currency in the purchase. |
transaction |
object | Transaction details (object). Required. |
transaction.id |
integer | Transaction ID. |
transaction.date |
string | Date of transaction. |
items_operation_type |
string | Type of operation made with virtual items. |
items |
array | Virtual items within the purchase (array of objects). |
items.sku |
string | Item ID. |
items.amount |
integer | Item quantity. |
-
php
-
http
-
curl
<?php
$request = array(
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '0',
'diff' => '0'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'transaction' => array(
'id' => '123456789',
'date' => '2015-05-19T15:54:40+03:00'
),
'operation_type' => 'cancellation',
'notification_type' => 'user_balance_operation',
'items_operation_type' => 'remove',
'items' => array(
'sku' => '1468',
'amount' => '2'
),
'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"0",
"diff":"0"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"transaction":{
"id":"123456789",
"date":"2015-05-19T15:54:40+03:00"
},
"operation_type":"cancellation",
"notification_type":"user_balance_operation",
"items_operation_type": "remove",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"virtual_currency_balance":{
"old_value":"0",
"new_value":"0",
"diff":"0"
},
"user":{
"name":"Xsolla User",
"id":"1234567",
"email":"email@example.com"
},
"transaction":{
"id":"123456789",
"date":"2015-05-19T15:54:40+03:00"
},
"operation_type":"cancellation",
"notification_type":"user_balance_operation",
"items_operation_type": "remove",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation":"66989"
}'
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Secondary Market: Get Items List
When a secondary market requests data of the items from a game inventory, Xsolla sends a notification to your webhook URL.Parameter | Type | Description |
---|---|---|
notification_type |
string | Notification type. |
project_id |
integer | Project ID. |
payload |
object | Object with the user and secondary market data. |
payload.user |
object | Object with the user data. |
payload.user.id |
string | User ID. |
payload.secondary_market |
object | Object with the secondary market data. |
payload.secondary_market.id |
string | Secondary market ID. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'inventory_get',
'project_id' => 1024,
'payload' => array(
'user' => array(
'id' => 'username'
),
'secondary_market' => array(
'id' => '1'
),
),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)
{
"notification_type": "inventory_get",
"project_id": 1024,
"payload": {
"user": {
"id": "username"
},
"secondary_market": {
"id": "1"
}
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
"notification_type": "inventory_get",
"project_id": 1024,
"payload": {
"user": {
"id": "username"
},
"secondary_market": {
"id": "1"
}
}
}
<?php
$response = array(
'user' => array(
'id' => 'username'
),
'items' => array(
array(
'sku' => 'sku1',
'instance_id' => 'instance1'
),
array(
'sku' => 'sku2',
'instance_id' => 'instance2'
),
),
)
HTTP/1.1 204
{
"user": {
"id": "username"
},
"items": [
{
"sku": "sku1",
"instance_id": “instance1”
},
{
"sku": "sku2",
"instance_id": “instance2”
}
],
}
{
"user": {
"id": "username"
},
"items": [
{
"sku": "sku1",
"instance_id": "instance1"
},
{
"sku": "sku2",
"instance_id": "instance2"
}
],
}
Secondary Market: Pull Game Items
When a secondary market requests items from a game inventory, Xsolla sends a notification to your webhook URL.Parameter | Type | Description |
---|---|---|
notification_type |
string | Notification type. |
project_id |
integer | Project ID. |
payload |
object | Object with the user and secondary market data. |
payload.user |
object | Object with the user data. |
payload.user.id |
string | User ID. |
items |
array | Array with item data. |
items.sku |
string | Item SKU. |
items.instance_id |
string | Unique item ID within the game. |
payload.secondary_market |
object | Object with the secondary market data. |
payload.secondary_market.id |
string | Secondary market ID. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'inventory_pull',
'project_id' => 1024,
'payload' => array(
'user' => array(
'id' => 'username'
),
'items' => array(
array(
'sku' => 'sku1',
'instance_id' => 'instance1'
),
array(
'sku' => 'sku2',
'instance_id' => 'instance2'
),
)
'secondary_market' => array(
'id' => '1'
),
),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)
{
"notification_type": "inventory_pull",
"project_id": 1024,
"payload": {
"user": {
"id": "username"
},
"items": [
{
"sku": "sku1",
"instance_id": "instance1"
},
{
"sku": "sku2",
"instance_id": "instance2"
},
],
"secondary_market": {
"id": "1"
}
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
"notification_type": "inventory_pull",
"project_id": 1024,
"payload": {
"user": {
"id": "username"
},
"items": [
{
"sku": "sku1",
"instance_id": "instance1"
},
{
"sku": "sku2",
"instance_id": "instance2"
}
],
"secondary_market": {
"id": "1"
}
}
}
<?php
$response = null;
HTTP/1.1 204 No Content
Secondary Market: Push Game Items
When a secondary market pushes items to a game inventory, Xsolla sends a notification to your webhook URL.Parameter | Type | Description |
---|---|---|
notification_type |
string | Notification type. |
project_id |
integer | Project ID. |
payload |
object | Object with the user and secondary market data. |
payload.user |
object | Object with the user data. |
payload.user.id |
string | User ID. |
items |
array | Array with item data. |
items.sku |
string | Item SKU. |
items.instance_id |
string | Unique item ID within the game. |
payload.secondary_market |
object | Object with the secondary market data. |
payload.secondary_market.id |
string | Secondary market ID. |
-
php
-
http
-
curl
<?php
$request = array(
'notification_type' => 'inventory_push',
'project_id' => 1024,
'payload' => array(
'user' => array(
'id' => 'username'
)
'items' => array(
array(
'sku' => 'sku1',
'instance_id' => 'instance1'
),
array(
'sku' => 'sku2',
'instance_id' => 'instance2'
),
),
'secondary_market' => array(
'id' => '1'
),
),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)
{
"notification_type": "inventory_push",
"project_id": 1024,
"payload": {
"user": {
"id": "username"
},
"items": [
{
"sku": "sku1",
"instance_id": "instance1"
},
{
"sku": "sku2",
"instance_id": "instance2"
}
],
"secondary_market": {
"id": "1"
}
}
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
"notification_type": "inventory_push",
"project_id": 1024,
"payload": {
"user": {
"id": "username"
},
"items": [
{
"sku": "sku1",
"instance_id": "instance1"
},
{
"sku": "sku2",
"instance_id": "instance2"
}
],
"secondary_market": {
"id": "1"
}
}
}
<?php
$response = null;
HTTP/1.1 204 No Content
Webhooks Errors
Permanent error codes:
Code | Message |
---|---|
INVALID_USER | Invalid user. |
INVALID_PARAMETER | Invalid parameter. |
INVALID_SIGNATURE | Invalid signature. |
INCORRECT_AMOUNT | Incorrect amount. |
INCORRECT_INVOICE | Incorrect invoice. |
HTTP/1.1 400 Bad Request
{
"error":{
"code":"INVALID_USER",
"message":"Invalid user"
}
}