Xsolla Documentation - Getting Started

Overview

Xsolla API includes:

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

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

The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.

Xsolla API uses the following endpoint paths:

https://api.xsolla.com — Pay Station API, Store API, Publisher Account API
https://login.xsolla.com/api — Login API

Most endpoint paths include the merchant_id parameter. This indicates that the requesting application is running on your behalf.

Requests and Responses

The requests to Xsolla API must:

be sent over HTTPS,
use TLS 1.2 or higher,
contain authentication parameters,
contain an additional header: Content-Type: application/json for PUT and POST requests.

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

By default, all requests return a response with JSON data in the body and Content-Type: application/json in the header.

API Changes

Xsolla may change the API functionality as follows:

Add new API resources
Add optional request parameters
Add new properties to existing API responses
Add new values for existing parameters with enumerable values
Add new webhook types and JSON parameters
Add optional HTTP request headers
Reject any request in which valid parameters contain invalid values
Reject improperly formed requests that were previously accepted due to lenient parsing, if the parsing logic is changed
Add, change, or remove undocumented functionality at any time

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

Versioning

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

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

Info: Keep in mind that we can only guarantee API integrity within the same version.

Authentication

Xsolla API uses basic access authentication. All requests to API must contain the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant_id:api_key pair encoded according to the Base64 standard.

Go to Xsolla Publisher Account to find values of the merchant_id and api_key parameters:

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

Notice:

Keep your API key in secret. It provides access to your personal account and your projects in Publisher Account.
Changing the API key may stop payments to all your projects. API calls that use your current key will stop working until you update them with your new key.

Example

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
Headers:
  Authorization: Basic <your_authorization_basic_key>

curl --request GET \
--url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'

<?php

// if you use Xsolla SDK for PHP
use Xsolla\SDK\API\XsollaClient;
$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$eventsList = $client->ListEvents(array());

// if you don’t use Xsolla SDK for PHP
$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

headers = { 'authorization': "Basic <your_authorization_basic_key>" }

conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
  .get()
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

Endpoint Types

The type of an endpoint indicates what kind of data it handles and what action it performs on it. The most common actions are:

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

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.

Notice: This API method can't be used under high load. When the number of requests is high, rate limits may apply. Contact your Account Manager to find out the rate limits for this API method.

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

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). The user.email object is an integral part of building anti-fraud models and payment processing. It is both Xsolla and payment systems requirement. Missing this parameter can lead to lower acceptance rates. Required.
user.email.value	string	User email. Must be valid according to the RFC 822 protocol. Required.
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.
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: small: the least possible size of the payment UI. Use this value when the window size is strictly limited (dimensions: 620 x 630) medium: recommended size. Use this value to display the payment UI in a lightbox (dimensions: 740 x 760) large: the optimal size for displaying the payment UI in a new window or tab (dimensions: 820 x 840)
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 (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.
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.price.amount_before_discount	string	Item price before the discount.
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"
            ]
        }
    }
}

Request

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);

Response

{
  "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.

See recipe

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 charge-backs/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 a user’s balance
Unlocking new item for a 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.

Notice: 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.

We cannot guarantee that your listener will receive all the webhooks we send. As internet connection is not 100% reliable, webhooks may fail to come on time or at all. Moreover, your listener may return a 5xx HTTP code for a temporary error on your server. For example, your listener returns a 500 HTTP response code in case a virtual item that a user purchased successfully was not added to the user's inventory.

To address these issues, we provide a retry mechanism that resends failed messages at various intervals until your listener receives them. A repeated webhook may be sent within 12 hours after the previous one. The maximum number of retries is 12.

Note: Although connection problems may indeed result in lost, delayed, or duplicate webhooks, the most common cause is faulty logic on the listener side.

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.

Request

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.
afs_black_list	Sent when the AFS blocklist is updated.
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.
non_renewal_subscription	Sent when status is set to non-renewing.
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.
payment_account_add	Sent when a user adds or saves payment account.
payment_account_remove	Sent when a user removes the payment account from saved accounts.

User Validation

Sent to verify that a user exists in the game.

Parameter	Type	Description
notification_type	string	Type of notification. Required.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
    'notification_type' => 'user_validation',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },    
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
user	object	User details (object). Required.
user.public_id	string	Public user ID.
user.id	string	User ID.

Request

<?php

$request = array(
    'notification_type' => 'user_search',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "public_id": "public_email@example.com"
    }
}'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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	float	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.payment_method_order_id	string	Payment ID in the payment system.
transaction.dry_run	integer	Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
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 and Canada only).
payment_details.sales_tax.currency	string	Currency. Three-letter currency code per ISO 4217.
payment_details.sales_tax.amount	float	Amount.
payment_details.direct_wht	object	Direct withholding tax.
payment_details.direct_wht.currency	string	Currency. Three-letter currency code per ISO 4217.
payment_details.direct_wht.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.

Request

<?php

$request = array(
    'notification_type' => 'payment',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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,
        'payment_method_order_id' => 1234567890123456789,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'sales_tax' => array(
            'currency' => 'EUR',
            'amount' => 0
        ),
        'direct_wht' => array(
            'currency' => 'EUR',
            'amount' => 70
        ),
        '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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,
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "sales_tax": {
            "currency": "EUR",
            "amount": 0
        },
        "direct_wht": {
            "currency": "EUR",
            "amount": 0.70
        },
        "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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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,
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "sales_tax": {
            "currency": "EUR",
            "amount": 0
        },
        "direct_wht": {
            "currency": "EUR",
            "amount": 0.70
        },
        "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"
    }
}'

Response

<?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. Learn more about a refund process in the recipe.

Parameter	Type	Description
notification_type	string	Type of notification. Required.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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	float	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. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
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 and Canada only).
payment_details.sales_tax.currency	string	Currency. Three-letter currency code per ISO 4217.
payment_details.sales_tax.amount	float	Amount.
payment_details.direct_wht	object	Direct withholding tax.
payment_details.direct_wht.currency	string	Currency. Three-letter currency code per ISO 4217.
payment_details.direct_wht.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.	Charge-back.	Transaction charge-back 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.

Request

<?php

$request = array(
    'notification_type' => 'refund',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),    
    '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
        ),
        'sales_tax' => array(
            'currency' => 'EUR',
            'amount' => 0
        ),
        'direct_wht' => array(
            'currency' => 'EUR',
            'amount' => 70
        ),
        '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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": {
        "sales_tax": {
            "currency": "EUR",
            "amount": 0
        },
        "direct_wht": {
            "currency": "EUR",
            "amount": 0.70
        },
        "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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": {
            "sales_tax": {
                "currency": "EUR",
                "amount": 0
            },
            "direct_wht": {
                "currency": "EUR",
                "amount": 0.70
            },
            "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"
            }
        }
    }
}'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array (
  'notification_type' => 'upgrade_refund',
  'settings' => array(
     'project_id' => 18404,
     'merchant_id' => 2340
  ),
  '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",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "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",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "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
  }
}'

Response

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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
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.

Request

<?php

$request = array(
  'notification_type' => 'afs_reject',
  'settings' => array(
    'project_id' => 18404,
    'merchant_id' => 2340
  ),
  '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",
  "settings": {
    "project_id": 18404,
    "merchant_id": 2340
  },
  "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",
  "settings": {
    "project_id": 18404,
    "merchant_id": 2340
  },
  "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"
  }
}'

Response

<?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

AFS Updated Blocklist

When the AFS blocklist is updated (add or remove a parameter), Xsolla sends the notification to the webhook URL. The parameter addition is performed automatically on the Xsolla side or on request. Parameter removing is possible only on request. To enable this notification, contact the Account Manager.

Parameter	Type	Description
notification_type	string	Type of notification. Required.
event	object	Object with information about AFS blocklist event. Required.
event.action	string	Type of event. Possible values: adding, removing.
event.reason	string	Cause of event. Possible values: Addition: сhargeback — chargeback, fraud_activity — fraud, suspicious_activity — suspicious activity, ps_reported_fraud — payment system notification about fraud, linked_chargeback — chargeback relation, partner_request — on request, friendly_fraud — friendly fraud, user_reported_fraud — user report about fraud, linked_parameter — linked parameter in AFS blocklist, other_data_in_blacklist — other parameters in AFS blocklist, by_afs_filters — AFS filter. Removing: wrongly_added — added by mistake, removed_by_cs_review — removed after reporting to Xsolla technical support, other_forgiveness_reason — other reason for removing.
event.parameter	string	Name of parameter by which event occurred. Possible values: nick — user’s nickname, email — user’s email address, ps_account — user’s billing account, ip_address — user’s IP address, card_issuer — user’s credit card issuing bank, phone — user’s phone number.
event.parameter_value	string	Value of parameter by which event occurred.
event.date_of_last_action	string	Time of the latest AFS blocklist event in the ISO 8601 format.
event.transaction_id	string	Transaction ID associated with the parameter by which the event occurred.

Request

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 233
Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6

{
  "event": {
    "action": "adding",
    "date_of_last_action": "2020-11-27 10:09:05",
    "parameter": "email",
    "parameter_value": "some_cool_email@gmail.com",
    "reason": "ps_reported_fraud",
    "transaction_id": "111111111"
  },
  "notification_type": "afs_black_list"
}

$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \
-d '{
  "event": {
    "action": "adding",
    "date_of_last_action": "2020-11-27 10:09:05",
    "parameter": "email",
    "parameter_value": "some_cool_email@gmail.com",
    "reason": "ps_reported_fraud",
    "transaction_id": "111111111"
  },
  "notification_type": "afs_black_list"
}'

Response

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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.
custom_parameters	object	Your custom parameters.

Request

<?php

$request = array(
    'notification_type' => 'create_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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"
                }
        }
    }'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
    'notification_type' => 'update_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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"
        }
    }'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
    'notification_type' => 'cancel_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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"
        }
    }'

Response

<?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

Non-renewing Subscription

When a subscription status is set to non-renewing for any reason, we send the notification non_renewal_subscription to your webhook URL.

Parameter	Type	Description
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account. Required.
settings.merchant_id	integer	Merchant ID.
notification_type	string	Type of notification. Required.
user	object	User details (object).
user.id	string	User ID. Required.
user.name	string	Username.
user.email	string	User email.
subscription	object	Subscription details (object).
subscription.subscription_id	integer	Subscription ID in Xsolla database.
subscription.plan_id	string	Plan ID (external if the plan was created via API).
subscription.date_create	string	Subscription creation date. Date and time per ISO 8601.
subscription.date_next_charge	string	Next billing date. This is the date when a next payment was expected before user subscription was set to non-renew. Date and time per ISO 8601.
subscription.currency	string	Subscription currency. Three-letter currency code per ISO 4217.
subscription.amount	float	Price in real currency.

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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array (
       'notification_type' => 'get_pincode',
       'settings' => array(
          'project_id' => 18404,
          'merchant_id' => 2340
       ),
       '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",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "pin_code": {
            "digital_content": "Game SKU",
            "DRM": "Steam"
        }
    }'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php
$request = array(
    'notification_type' => 'redeem_key',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    '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",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "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",
  "settings": {
        "project_id": 18404,
        "merchant_id": 2340
  },
  "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"
         ]
    }
}'

Response

<?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: Concatenate notification_type + parameter values sorted alphabetically by the key + secret_key Apply SHA-1 to the resulting string

Request

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

Response

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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    '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

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "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 '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "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"
    }'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
    'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
    ),
    '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

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "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 '{
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "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"
    }'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    '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

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "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 '{
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "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"
        }
    }'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    '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

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "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 '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "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"
    }'

Response

<?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.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
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.

Request

<?php

$request = array(
     'settings' => array(
         'project_id' => 18404,
         'merchant_id' => 2340
     ),
     '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

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "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 '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "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"
    }'

Response

<?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

Add Payment Account

Sent whenever a user adds a payment account manually or saves payment account when purchasing something inside the game. To enable this notification, contact the Account Manager.

Parameter	Type	Description
notification_type	string	Type of notification. Required.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
user	object	User details (object).
user.ip	string	User IP.
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.
payment_account	object	Payment account details (object).
payment_account.id	string	Payment account ID. Required.
payment_account.name	string	The payment account name in the payment system (e.g., payment card number, email).
payment_account.payment_method	integer	Payment method ID.
payment_account.type	string	Type of payment account (e.g., card, PayPal).

Request

POST /your/uri HTTP/1.1
Host:           your.hostname
Accept:         application/json
Content-Length: 255
Content-Type:   application/json
Authorization:  Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843

{
    "notification_type": "payment_account_add",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type":"payment_account_add",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'

Response

HTTP/1.1 204 No Content

Remove Payment Account

Sent whenever a user removes the payment account from saved accounts. To enable this notification, please contact the Account Manager.

Parameter	Type	Description
notification_type	string	Type of notification. Required.
settings	object	Custom project settings (object).
settings.project_id	integer	Game’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id	integer	Merchant ID.
user	object	User details (object).
user.email	string	User email.
user.id	string	User ID. Required.
user.name	string	Username.
payment_account	object	Payment account details (object).
payment_account.id	string	Payment account ID. Required.
payment_account.name	string	The payment account name in the payment system (e.g., payment card number, email).
payment_account.payment_method	integer	Payment method ID.
payment_account.type	string	Type of payment account (e.g., card, PayPal).

Request

POST /your/uri HTTP/1.1
Host:           your.hostname
Accept:         application/json
Content-Length: 258
Content-Type:   application/json
Authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


{
    "notification_type": "payment_account_remove",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "payment_account_remove",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'

Response

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

Thank you for your feedback!

We'll review your message and use it to help us improve your experience.

Your browser is not supported. Please try a different browser

Getting Started

Overview

Requests and Responses

API Changes

Versioning

Authentication

Endpoint Types

Date Format

Pagination

Errors Handling

Token

Get Token

user

user.id

user.id.value

user.name

user.name.value

user.email

user.email.value

user.phone

user.phone.value

user.country

user.country.value

user.country.allow_modify

user.attributes

user.steam_id

user.steam_id.value

user.tracking_id

user.tracking_id.value

user.public_id.value

user.utm

user.utm.utm_source

user.utm.utm_medium

user.utm.utm_campaign

user.utm.utm_term

user.utm.utm_content

user.is_legal

user.legal

user.legal.name

user.legal.address

user.legal.vat_id

user.legal.country

settings

settings.external_id

settings.project_id

settings.language

settings.return_url

settings.currency

settings.mode

settings.payment_method

settings.payment_widget

settings.ui

settings.ui.theme

settings.ui.size

settings.ui.version

settings.ui.desktop

settings.ui.desktop.header

settings.ui.desktop.header.is_visible

settings.ui.desktop.header.visible_logo

settings.ui.desktop.header.visible_name

settings.ui.desktop.header.visible_purchase

settings.ui.desktop.header.type

settings.ui.desktop.header.close_button

settings.ui.desktop.subscription_list

settings.ui.desktop.subscription_list.layout

settings.ui.desktop.subscription_list.description

settings.ui.desktop.subscription_list.display_local_price

settings.ui.desktop.virtual_item_list

settings.ui.desktop.virtual_item_list.layout

settings.ui.desktop.virtual_item_list.button_with_price

settings.ui.desktop.virtual_item_list.view

settings.ui.desktop.virtual_currency_list

settings.ui.desktop.virtual_currency_list.description

settings.ui.desktop.virtual_currency_list.button_with_price

settings.ui.header.visible_virtual_currency_balance

settings.ui.mobile.mode

settings.ui.mobile.header.close_button

settings.ui.mobile.footer.is_visible

settings.ui.license_url