Getting Started

Overview

Xsolla API includes:

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

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

Xsolla API uses the following endpoint paths:

  • https://api.xsolla.com — Pay Station API, 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.

Copy
Full screen
Small screen

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

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

API Changes

Xsolla may change the API functionality as follows:

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

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

Versioning

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

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

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

Authentication

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

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

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

Notice:
  • Keep your API key in secret. It provides access to your personal account and your projects in Publisher Account.
  • Changing the API key may stop payments to all your projects. API calls that use your current key will stop working until you update them with your new key.
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Example
GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request GET \
--url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'
<?php

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

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

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

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

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

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

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

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

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

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

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

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

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

response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

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

Response response = client.newCall(request).execute();
var data = null;

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

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

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

xhr.send(data);

Endpoint Types

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

ActionHTTP MethodDescription
CreatePOSTCreates and saves an entity of the specified type.
ListGETReturns a list of entities matching the query. To get details on an entity, first find out its ID using the corresponding List endpoint, and then provide this ID to the corresponding Retrieve endpoint.
RetrieveGETProvides details on the entity with the specified ID.
ReplacePUTModifies all fields of the entity with the specified ID.
UpdatePATCHModifies specified fields of the entity with the specified ID.
DeleteDELETEDeletes the entity with the specified ID.

Date Format

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

Pagination

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

Errors Handling

List of supported HTTP errors:

  • 200, 201, 204 — No error
  • 400 Bad Request — This often indicates a required parameter missing. Refer to the response body for details
  • 401 Unauthorized — No valid API key provided
  • 402 Request Failed — Request failed despite valid parameters
  • 403 Forbidden — No permission. Refer to the response body for details
  • 404 Not Found — The requested item doesn't exist
  • 409, 422 — Invalid request parameters
  • 412 Precondition Failed — The project has not been activated yet (used in the 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" >}}TypeDescription
http_status_codeintegerHTTP code.
messagestringA human-readable message describing the error. This message is always in English. Do not rely on this value for any particular error, because it might change in the future.
extended_messagestringMore detailed error description.
request_idstringUnique request ID that might be used for troubleshooting.
Copy
Full screen
Small screen

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

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

Copy
Full screen
Small screen

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

ParameterTypeDescription
user
objectUser details (object).
user.id
objectUser ID (object). Required.
user.id.value
stringUser ID.
user.name
objectUser screen name (object).
user.name.value
stringUser screen name.
user.email
objectUser 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
stringUser email. Must be valid according to the RFC 822 protocol. Required.
user.phone
objectUser phone number (object).
user.phone.value
stringUser phone number.
user.country
objectUser country (object).
user.country.value
stringTwo-letter uppercase country code per ISO 3166-1 alpha-2.
user.country.allow_modify
booleanWhether or not user can change the country on payment UI. 'false' by default.
user.attributes
objectUser attributes for filtering the item list, represented as a valid JSON set of key-value pairs.
user.steam_id
objectUser's Steam ID (object).
user.steam_id.value
stringSteam ID.
user.tracking_id
objectUser tracking ID (object).
user.tracking_id.value
stringUnique tracking ID (used in marketing campaigns).
user.public_id.value
stringParameter 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
objectTraffic attributes (object).
user.utm.utm_source
stringTraffic source.
user.utm.utm_medium
stringTraffic channel (contextual ads, media ads, email lists, etc.).
user.utm.utm_campaign
stringCampaign title, transliterated or translated to English.
user.utm.utm_term
stringCampaign 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
stringCampaign content.
booleanWhether the user is a legal entity.
objectObject with legal entity details. Object and all its parameters are required if user.is_legal is ‘true’.
stringFull legal name.
stringFull legal address.
stringIndividual taxpayer identifier.
stringCountry of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
settings
objectCustom project settings (object).
settings.external_id
stringTransaction’s external ID.
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account. Required.
settings.language
stringInterface language. Two-letter lowercase language code.
settings.return_url
stringPage to redirect the user to after payment. Parameters 'user_id', 'foreigninvoice', 'invoice_id' and 'status' will be automatically added to the link.
settings.currency
stringPreferred payment currency. Three-letter currency code per ISO 4217.
settings.mode
stringSet 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
integerPayment method ID.
settings.payment_widget
stringPayment 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
objectInterface settings (object).
settings.ui.theme
stringPayment UI theme. Can be 'default' or 'default_dark'.
settings.ui.size
stringPayment 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
stringDevice type. Can be 'desktop' (default) or 'mobile'.
settings.ui.desktop
objectInterface settings for the desktop version (object).
settings.ui.desktop.header
objectHeader settings (object).
settings.ui.desktop.header.is_visible
booleanWhether to show the header in the payment UI.
booleanIf 'true', the header will show your logo (first provide the image to your account manager).
settings.ui.desktop.header.visible_name
booleanWhether to show the project name in the header.
settings.ui.desktop.header.visible_purchase
booleanWhether to show the purchase description (purchase.description.value) in the header. ‘true’ by default.
settings.ui.desktop.header.type
stringHow to show the header. Can be 'compact' (hides project name and user ID) or 'normal' (default).
settings.ui.desktop.header.close_button
booleanWhether 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
objectSettings for the list of subscription plans (object).
settings.ui.desktop.subscription_list.layout
stringList template. Can be 'list' (default) or 'grid'.
settings.ui.desktop.subscription_list.description
stringAny text to show above the list of available subscription plans in the payment UI.
settings.ui.desktop.subscription_list.display_local_price
booleanIf '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
objectSettings for the list of virtual items (object).
settings.ui.desktop.virtual_item_list.layout
stringList template. Can be 'list' (default) or 'grid'.
settings.ui.desktop.virtual_item_list.button_with_price
booleanIf '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
stringDisplay virtual item groups as a vertical/horizontal menu. Can be 'horizontal_navigation' or 'vertical' (default).
settings.ui.desktop.virtual_currency_list
objectSettings for the list of virtual currencies (object).
settings.ui.desktop.virtual_currency_list.description
stringAny text to show above the list of virtual currencies.
settings.ui.desktop.virtual_currency_list.button_with_price
booleanIf '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
booleanWhether or not this element can be hidden on Payment UI. 'true' by default.
settings.ui.mobile.mode
stringA user can only pay using their saved payment methods. Can be 'saved_accounts'.
settings.ui.mobile.header.close_button
booleanWhether 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.
booleanWhether to hide the footer in the mobile version of the payment UI.
settings.ui.license_url
stringLink to the EULA.
settings.ui.components
objectMenu settings (object).
settings.ui.components.virtual_items
objectVirtual items submenu.
settings.ui.components.virtual_items.order
integerPosition of the submenu in the menu.
settings.ui.components.virtual_items.hidden
booleanWhether to show the submenu.
settings.ui.components.virtual_items.selected_group
stringGroup to show after opening the virtual items tab.
settings.ui.components.virtual_items.selected_item
stringItem to show after opening the virtual items tab (item SKU).
settings.ui.components.virtual_currency
objectVirtual currency submenu.
settings.ui.components.virtual_currency.custom_amount
booleanWhether the user can enter an arbitrary quantity of the virtual currency in the payment UI.
settings.ui.components.virtual_currency.order
integerPosition of the submenu in the menu.
settings.ui.components.virtual_currency.hidden
booleanWhether to show the submenu.
settings.ui.components.subscriptions
objectSubscription plans submenu (object).
settings.ui.components.subscriptions.order
integerPosition of the submenu in the menu.
settings.ui.components.subscriptions.hidden
booleanWhether to show the submenu.
settings.ui.mode
stringInterface 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
objectUser account details (object).
settings.ui.user_account.info
objectPage My account.
settings.ui.user_account.info.order
integerPosition of the submenu in the menu.
settings.ui.user_account.info.enable
booleanWhether to show the submenu. 'false' by default.
settings.ui.user_account.history
objectHistory submenu.
settings.ui.user_account.history.order
integerPosition of the submenu in the menu.
settings.ui.user_account.history.enable
booleanWhether to show the submenu. 'false' by default.
settings.ui.user_account.payment_accounts
objectMy payment accounts submenu.
settings.ui.user_account.payment_accounts.order
integerPosition of the submenu in the menu.
settings.ui.user_account.payment_accounts.enable
booleanWhether to show the submenu. 'false' by default.
settings.ui.user_account.subscriptions
objectManage subscriptions submenu.
settings.ui.user_account.subscriptions.order
integerPosition of the submenu in the menu.
settings.ui.user_account.subscriptions.enable
booleanWhether to show the submenu. 'false' by default.
purchase
objectObject containing purchase details.
purchase.virtual_currency
objectObject containing virtual currency details.
purchase.virtual_currency.quantity
floatPurchase amount in the virtual currency.
purchase.virtual_currency.currency
stringCurrency of the virtual currency package to use in all calculations.
purchase.virtual_items
objectObject with data about the virtual items in purchase.
purchase.virtual_items.currency
stringCurrency of the ordered items to use in all calculations.
purchase.virtual_items.items
arrayItem data (array).
purchase.virtual_items.items.sku
stringItem ID.
purchase.virtual_items.items.amount
integerItem quantity.
purchase.virtual_items.available_groups
arrayItem groups IDs (array). The payment UI will only include items within the specified group.
purchase.subscription
objectSubscription data (object).
purchase.subscription.plan_id
stringPlan ID.
purchase.subscription.operation
stringThe 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
stringProduct ID.
purchase.subscription.currency
stringCurrency of the subscription plan to use in all calculations.
purchase.subscription.available_plans
arraySubscription plans (array) to show in the payment UI.
purchase.subscription.trial_days
integerTrial period in days.
purchase.pin_codes
objectGame keys (object).
purchase.pin_codes.currency
stringCurrency of a Game key within the order to use in all calculations.
purchase.pin_codes.codes
arrayGame keys (array).
purchase.pin_codes.codes.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.codes.drm
stringDRM 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
objectObject with the upgrade data.
purchase.pin_codes.upgrade.id_user_history
integerID of the entry containing data on the user and their packages.
purchase.pin_codes.upgrade.id
integerUpgrade ID.
purchase.checkout
objectObject containing checkout details.
purchase.checkout.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
floatPurchase amount.
purchase.description
objectPurchase description (object).
purchase.description.value
stringGeneral 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 objectsItems array.
purchase.description.items.name
stringItem name.
purchase.description.items.image_url
stringLink to the item icon.
purchase.description.items.description
stringItem description in the purchase.
purchase.description.items.price
objectObject with the item price.
purchase.description.items.price.amount
stringItem price.
purchase.description.items.price.amount_before_discount
stringItem price before the discount.
purchase.description.items.quantity
integerNumber of items in the purchase.
purchase.description.items.is_bonus
booleanWhether an item is free and available as a bonus. Default is 'false'.
purchase.gift
objectGift details (object).
purchase.gift.giver_id
stringGiver ID.
purchase.gift.message
stringMessage from the giver.
purchase.gift.hide_giver_from_receiver
stringWhether to hide the giver identity from the recipient. 'true' by default.
purchase.gift.friends
arrayArray with data on friends.
purchase.gift.friends.id
stringGift recipient ID.
purchase.gift.friends.name
stringGift recipient nickname.
purchase.gift.friends.email
stringGift recipient email.
purchase.coupon_code
objectInformation about a discount promo code or bonuses upon purchase (object).
purchase.coupon_code.value
stringPromo code value.
purchase.coupon_code.hidden
booleanHide the field promo code is entered into in the payment UI. 'false' by default.
custom_parameters
objectYour 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.

Copy
Full screen
Small screen

{
    "extended_message": {
        "global_errors": [],
        "property_errors": {
            "settings.project_id": [
                "string value found, but an integer is required"
            ]
        }
    }
}

Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
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

ParameterTypeDescription
registration_date
stringAccount creation date per ISO 8601.
total_hours
integerTotal number of in-game hours.
total_characters
integerNumber of in-game characters.
social_networks_added
booleanWhether the player has connected social media profiles.
profile_image_added
booleanWhether the player has uploaded a profile image.
active_date
stringLast seen date per ISO 8601.
total_friends
integerNumber of friends.
additional_verification
booleanWhether the player uses account verification procedures.
win_rate
integerWin rate.
last_change_password_date
stringLast password change date per ISO 8601.
chat_activity
booleanWhether the player uses the chat function.
forum_activity
booleanWhether the player uses the forum function.
total_bans
integerNumber of times the player was banned in the chat/forum.
profile_completed
booleanWhether the player added additional information to their profile.
notifications_enabled
booleanWhether the player enabled notifications.
user_level
integerPlayer’s level, reputation, or rank.
karma_points
integerPlayer’s karma.
total_sum
floatTotal amount of payments.
non_premium_currency
floatAmount of non-premium currency.
total_game_events
integerNumber of in-game events the player took part in.
total_gifts
integerNumber of in-game gifts the player has sent/received.
tutorial_completed
booleanWhether the player has completed the game’s tutorial.
completed_tasks
integerNumber of tasks/objectives completed.
items_used
booleanWhether the player uses purchased in-game items.
pvp_activity
booleanWhether the player takes part in PvP battles.
total_clans
integerNumber of clans the player is a member of.
unlocked_achievements
integerNumber of achievements unlocked.
total_inventory_value
floatTotal inventory value (in-game currency).
character_customized
booleanWhether the player has customized their character.
session_time
stringAverage 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.

Copy
Full screen
Small screen
http
  • http
  • curl
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 TypeDescription
user_validationCheck if a user exists in the game.
user_searchGet user info based on Public User ID.
paymentSent when a user completes a payment.
refundSent when a payment must be canceled for any reason.
afs_rejectSent when a transaction is declined during an AFS check.
afs_black_listSent when the AFS blocklist is updated.
create_subscriptionSent when a user creates a subscription.
update_subscriptionSent when a subscription is renewed or changed.
cancel_subscriptionSent when a subscription is canceled.
non_renewal_subscriptionSent when status is set to non-renewing.
get_pincodeSent when Xsolla API needs to obtain the game keys.
user_balance_operationSent when a user balance changes (the type of operation is sent in operation_type).
redeem_keySent when a user activates a key.
upgrade_refundSent when the upgrade is cancelled.
payment_account_addSent when a user adds or saves payment account.
payment_account_removeSent when a user removes the payment account from saved accounts.

User Validation

Sent to verify that a user exists in the game.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.ip
stringUser IP.
user.phone
stringUser phone.
user.email
stringUser email.
user.id
stringUser ID. Required.
user.name
stringUsername.
user.country
stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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
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).

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object). Required.
user.public_id
stringPublic user ID.
user.id
stringUser ID.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
purchase
objectPurchase details (object).
purchase.virtual_currency
objectVirtual currency to purchase (object).
purchase.virtual_currency.name
stringVirtual currency name.
purchase.virtual_currency.sku
stringVirtual currency package SKU (if set for the virtual currency package).
purchase.virtual_currency.quantity
floatQuantity.
purchase.virtual_currency.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_currency.amount
floatPrice in real currency.
purchase.checkout
objectCheckout details (object).
purchase.checkout.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
floatPurchase amount.
purchase.subscription
objectSubscription details (object).
purchase.subscription.plan_id
stringPlan ID (external if the plan was created via API).
purchase.subscription.subscription_id
integerSubscription ID in Xsolla database.
purchase.subscription.product_id
stringProduct ID (if sent in the access token).
purchase.subscription.tags
arrayPlan tags.
purchase.subscription.date_create
stringSubscription creation date. Date and time per ISO 8601.
purchase.subscription.date_next_charge
stringNext billing date. Date and time per ISO 8601.
purchase.subscription.currency
stringSubscription currency. Three-letter currency code per ISO 4217.
purchase.subscription.amount
floatPrice in real currency.
purchase.virtual_items
objectVirtual items in purchase (object).
purchase.virtual_items.items
arrayItem data (array).
purchase.virtual_items.items.sku
stringItem ID.
purchase.virtual_items.items.amount
integerItem quantity.
purchase.virtual_items.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_items.amount
floatPurchase amount.
purchase.pin_codes
objectGame keys (array).
purchase.pin_codes.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.drm
stringDRM 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
stringCurrency that the game keys is purchased for. Three-letter currency code per ISO 4217.
purchase.pin_codes.amount
floatPrice.
purchase.pin_codes.upgrade
objectObject with upgrade data.
purchase.pin_codes.upgrade.digital_content_from
objectObject with data on the package, from which the user upgraded.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringGame DRM platform.
purchase.pin_codes.upgrade.digital_content_to
objectObject with data on the package, to which the user upgraded.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringGame DRM platform.
purchase.pin_codes.upgrade.currency
stringPurchase currency. Three-letter currency code per ISO 4217.
purchase.pin_codes.upgrade.amount
floatPrice in real currency.
purchase.gift
objectGift details (object).
purchase.gift.giver_id
stringGiver ID.
purchase.gift.receiver_id
stringGift recipient ID.
purchase.gift.receiver_email
stringGift recipient email.
purchase.gift.message
stringMessage from the giver.
purchase.gift.hide_giver_from_receiver
stringWhether to hide the giver identity from the recipient.
purchase.total
objectTotal price of purchase (object). Required.
purchase.total.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.total.amount
floatTotal payment amount.
purchase.promotions
arrayPromotions applied to this transaction (array).
purchase.promotions.technical_name
stringTechnical name of the promotion.
purchase.promotions.id
integerPromotion ID.
purchase.coupon
objectCoupon details (object; if a coupon was used when creating the subscription).
purchase.coupon.coupon_code
stringCoupon code.
purchase.coupon.campaign_code
stringCampaign code.
user
objectUser details (object).
user.ip
stringUser IP.
user.phone
stringUser phone.
user.email
stringUser email.
user.id
stringUser ID. Required.
user.name
stringUsername.
user.country
stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.zip
stringUser's ZIP or postal code.
transaction
objectTransaction details (object). Required.
transaction.id
integerTransaction ID.
transaction.external_id
stringTransaction external ID.
transaction.payment_date
stringDate of payment.
transaction.payment_method
integerPayment method identifier.
transaction.payment_method_order_id
stringPayment ID in the payment system.
transaction.dry_run
integerTest transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
transaction.agreement
integerAgreement ID.
payment_details
objectPayment details (object). Required.
payment_details.payment
objectAmount paid by the user (object).
payment_details.payment.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payment.amount
stringAmount.
payment_details.payment_method_sum
objectAmount debited from the payment system.
payment_details.payment_method_sum.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payment_method_sum.amount
stringAmount.
payment_details.xsolla_balance_sum
objectAmount debited from Xsolla balance.
payment_details.xsolla_balance_sum.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.xsolla_balance_sum.amount
stringAmount.
payment_details.payout
objectPayout details (object).
payment_details.payout.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payout.amount
floatAmount.
payment_details.vat
objectVAT details (object; EU only).
payment_details.vat.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.vat.amount
floatAmount.
payment_details.payout_currency_rate
floatExchange rate between payment and payout currencies.
payment_details.xsolla_fee
objectXsolla fee (object).
payment_details.xsolla_fee.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.xsolla_fee.amount
floatAmount.
payment_details.payment_method_fee
objectPayment system fee.
payment_details.payment_method_fee.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payment_method_fee.amount
floatAmount.
payment_details.sales_tax
objectSales tax (object; USA and Canada only).
payment_details.sales_tax.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.sales_tax.amount
floatAmount.
payment_details.direct_wht
objectDirect withholding tax.
payment_details.direct_wht.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.direct_wht.amount
floatAmount.
payment_details.repatriation_commission
objectObject with data on repatriation costs, imposed on Xsolla by third parties.
payment_details.repatriation_commission.currency
stringRepatriation costs currency. Three-letter currency code per ISO 4217.
payment_details.repatriation_commission.amount
floatRepatriation costs amount.
custom_parameters
objectYour custom parameters.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
purchase
objectPurchase details (object).
purchase.virtual_currency
objectVirtual currency to purchase (object).
purchase.virtual_currency.name
stringVirtual currency name.
purchase.virtual_currency.quantity
floatQuantity.
purchase.virtual_currency.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_currency.amount
floatPrice in real currency.
purchase.checkout
objectCheckout details (object).
purchase.checkout.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
floatPurchase amount.
purchase.subscription
objectSubscription details (object).
purchase.subscription.plan_id
stringPlan ID (external if the plan was created via API).
purchase.subscription.tags
arrayPlan tags.
purchase.subscription.subscription_id
integerSubscription ID in Xsolla database.
purchase.subscription.date_create
stringSubscription creation date. Date and time per ISO 8601.
purchase.subscription.currency
stringSubscription currency. Three-letter currency code per ISO 4217.
purchase.subscription.amount
floatPrice in real currency.
purchase.virtual_items
objectVirtual items in purchase (object).
purchase.virtual_items.items
arrayItem data (array).
purchase.virtual_items.items.sku
stringItem ID.
purchase.virtual_items.items.amount
integerItem quantity.
purchase.virtual_items.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_items.amount
floatPurchase amount.
purchase.pin_codes
objectGame keys (object).
purchase.pin_codes.upgrade
objectObject with upgrade data.
purchase.pin_codes.upgrade.digital_content_from
objectObject with data on the package, from which the user upgraded.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringGame DRM platform.
purchase.pin_codes.upgrade.digital_content_to
objectObject with data on the package, to which the user upgraded.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringGame DRM platform.
purchase.pin_codes.upgrade.currency
stringPurchase currency. Three-letter currency code per ISO 4217.
purchase.pin_codes.upgrade.amount
floatPrice in real currency.
purchase.total
objectTotal price of purchase (object).
purchase.total.currency
stringCurrency of the purchase. Three-letter currency code per ISO 4217.
purchase.total.amount
floatTotal payment amount.
user
objectUser details (object).
user.ip
stringUser IP.
user.phone
stringUser phone.
user.email
stringUser email.
user.id
stringUser ID. Required.
user.name
stringUsername.
user.country
stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.zip
stringUser's ZIP or postal code.
transaction
objectTransaction details (object). Required.
transaction.id
integerTransaction ID.
transaction.external_id
stringTransaction external ID.
transaction.dry_run
integerTest transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
transaction.agreement
integerAgreement ID.
refund_details
objectRefund details (object).
refund_details.code
integerCode ID.
refund_details.reason
stringRefund reason.
refund_details.author
stringRefund initiator.
payment_details
objectPayment details (object). Required.
payment_details.payment
objectAmount paid by the user (object).
payment_details.payment.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payment.amount
stringAmount.
payment_details.payment_method_sum
objectAmount debited from the payment system.
payment_details.payment_method_sum.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payment_method_sum.amount
stringAmount.
payment_details.xsolla_balance_sum
objectAmount debited from Xsolla balance.
payment_details.xsolla_balance_sum.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.xsolla_balance_sum.amount
stringAmount.
payment_details.payout
objectPayout details (object).
payment_details.payout.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payout.amount
floatAmount.
payment_details.vat
objectVAT details (object; EU only).
payment_details.vat.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.vat.amount
floatAmount.
payment_details.payout_currency_rate
floatExchange rate between payment and payout currencies.
payment_details.xsolla_fee
objectXsolla fee (object).
payment_details.xsolla_fee.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.xsolla_fee.amount
floatAmount.
payment_details.payment_method_fee
objectPayment system fee.
payment_details.payment_method_fee.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.payment_method_fee.amount
floatAmount.
payment_details.sales_tax
objectSales tax (object; USA and Canada only).
payment_details.sales_tax.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.sales_tax.amount
floatAmount.
payment_details.direct_wht
objectDirect withholding tax.
payment_details.direct_wht.currency
stringCurrency. Three-letter currency code per ISO 4217.
payment_details.direct_wht.amount
floatAmount.
payment_details.repatriation_commission
objectObject with data on repatriation costs, imposed on Xsolla by third parties.
payment_details.repatriation_commission.currency
stringRepatriation costs currency. Three-letter currency code per ISO 4217.
payment_details.repatriation_commission.amount
floatRepatriation costs amount.
custom_parameters
objectYour custom parameters.

Refund codes:

CodeReasonDescription
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.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringNotification type. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
purchase
objectObject with the purchase data. Required.
purchase.pin_codes
objectObject with data on the purchased game packages.
purchase.pin_codes.purchase_type
stringPurchase type. Can be “regular” (purchasing the package) or “upgrade” (upgrading the package).
purchase.pin_codes.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.DRM
stringGame DRM platform.
purchase.pin_codes.currency
stringPurchase currency. Three-letter currency code per ISO 4217.
purchase.pin_codes.amount
floatPrice in real currency.
purchase.pin_codes.transaction
objectObject with the transaction data.
purchase.pin_codes.transaction.id
integerTransaction ID.
purchase.pin_codes.upgrade
objectObject with the upgrade data.
purchase.pin_codes.upgrade.digital_content_from
objectObject with data on the package, from which the user upgraded.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringGame DRM platform.
purchase.pin_codes.upgrade.digital_content_to
objectObject with data on the package, to which the user upgraded.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringGame SKU set in Publisher Account.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringGame DRM platform.
ownership
objectObject with data on packages owned by the user. Required.
ownership.digital_content
stringGame SKU set in Publisher Account.
ownership.DRM
stringGame DRM platform.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.ip
stringUser IP.
user.phone
stringUser phone.
user.email
stringUser email.
user.id
stringUser ID. Required.
user.name
stringUsername.
user.country
stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.zip
stringUser's ZIP or postal code.
transaction
objectTransaction details (object). Required.
transaction.id
integerTransaction ID.
transaction.external_id
stringTransaction external ID.
transaction.dry_run
integerTest transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
transaction.agreement
integerAgreement ID.
refund_details
objectRefund details (object).
refund_details.code
integerCode ID.
refund_details.reason
stringRefund reason.
refund_details.author
stringRefund initiator.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
event
objectObject with information about AFS blocklist event. Required.
event.action
stringType of event. Possible values: adding, removing.
event.reason
stringCause 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
stringName 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
stringValue of parameter by which event occurred.
event.date_of_last_action
stringTime of the latest AFS blocklist event in the ISO 8601 format.
event.transaction_id
stringTransaction ID associated with the parameter by which the event occurred.
Copy
Full screen
Small screen
http
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
subscription
objectSubscription details (object).
subscription.plan_id
stringPlan ID (external if the plan was created via API).
subscription.tags
arrayPlan tags.
subscription.subscription_id
integerSubscription ID in Xsolla database.
subscription.product_id
stringProduct ID (if sent in the access token).
subscription.date_create
stringSubscription creation date. Date and time per ISO 8601.
subscription.date_next_charge
stringNext billing date. Date and time per ISO 8601.
subscription.trial
objectTrial period (object).
subscription.trial.value
integerTrial period.
subscription.trial.type
stringTrial period type: day.
custom_parameters
objectYour custom parameters.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
subscription
objectSubscription details (object).
subscription.plan_id
stringPlan ID (external if the plan was created via API).
subscription.tags
arrayPlan tags.
subscription.subscription_id
integerSubscription ID in Xsolla database.
subscription.product_id
stringProduct ID (if sent in the access token).
subscription.date_next_charge
stringNext billing date. Date and time per ISO 8601.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
subscription
objectSubscription details (object).
subscription.plan_id
stringPlan ID (external if the plan was created via API).
subscription.tags
arrayPlan tags.
subscription.subscription_id
integerSubscription ID in Xsolla database.
subscription.product_id
stringProduct ID (if sent in the access token).
subscription.date_create
stringSubscription creation date. Date and time per ISO 8601.
subscription.date_end
stringSubscription termination date. Date and time per ISO 8601.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account. Required.
settings.merchant_id
integerMerchant ID.
notification_type
stringType of notification. Required.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
user.email
stringUser email.
subscription
objectSubscription details (object).
subscription.subscription_id
integerSubscription ID in Xsolla database.
subscription.plan_id
stringPlan ID (external if the plan was created via API).
subscription.date_create
stringSubscription creation date. Date and time per ISO 8601.
subscription.date_next_charge
stringNext 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
stringSubscription currency. Three-letter currency code per ISO 4217.
subscription.amount
floatPrice in real currency.

Get Game Keys

We will be making API calls to your server to obtain game activation codes after each successful payment.

ParameterTypeDescription
notification_type
stringType of notification.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
pin_code
objectGame keys details (object).
pin_code.digital_content
stringGame SKU.
pin_code.DRM
stringDRM platform used to distribute the game.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringNotification type.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
key
stringActivation key.
sku
stringUnique key package ID.
user_id
stringUser ID.
activation_date
datetimeKey activation date in the YYYYMMDDHHMMSS format per ISO 8601.
user_country
stringUser country. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
restriction
objectObject 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
stringUnique cluster ID.
restriction.name
stringCluster name.
restriction.types
arrayArray of restriction types.
restriction.countries
arrayArray of countries in the cluster.
restriction.servers
arrayArray of game servers.
restriction.locales
arrayArray of locales.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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

Copy
Full screen
Small screen

GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1

ParameterTypeDescription
notification_type
stringID that defines the type of request to get the list of friends. The value is 'friends_list'.
user
stringUnique ID of the user buying the gift.
query
stringFriend’s name or ID (full or partial).
limit
stringLimit for the number of elements on the page. Required.
offset
integerNumber of the element from which the list is generated (the count starts from 0).
sign
stringSignature line, generated as follows:
  • Concatenate notification_type + parameter values sorted alphabetically by the key + secret_key
  • Apply SHA-1 to the resulting string
Copy
Full screen
Small screen
http
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
operation_type
stringType of operation.
id_operation
integerOperation ID in Xsolla database.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
user.email
stringUser email.
virtual_currency_balance
objectUser balance data (object).
virtual_currency_balance.old_value
stringBalance before transaction.
virtual_currency_balance.new_value
stringBalance after transaction.
virtual_currency_balance.diff
stringQuantity of virtual currency in the purchase.
transaction
objectTransaction details (object). Required.
transaction.id
integerTransaction ID.
transaction.date
stringDate of transaction.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
operation_type
stringType of operation.
id_operation
integerOperation ID in Xsolla database.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
user.email
stringUser email.
virtual_currency_balance
objectUser balance data (object).
virtual_currency_balance.old_value
stringBalance before transaction.
virtual_currency_balance.new_value
stringBalance after transaction.
virtual_currency_balance.diff
stringQuantity of virtual currency in the purchase.
items_operation_type
stringType of operation made with virtual items.
items
arrayVirtual items within the purchase (array of objects).
items.sku
stringItem ID.
items.amount
integerItem quantity.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
operation_type
stringType of operation.
id_operation
integerOperation ID in Xsolla database.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
user.email
stringUser email.
virtual_currency_balance
objectUser balance data (object).
virtual_currency_balance.old_value
stringBalance before transaction.
virtual_currency_balance.new_value
stringBalance after transaction.
virtual_currency_balance.diff
stringQuantity of virtual currency in the purchase.
items_operation_type
stringType of operation made with virtual items.
items
arrayVirtual items within the purchase (array of objects).
items.sku
stringItem ID.
items.amount
integerItem quantity.
coupon
objectCoupon details (object).
coupon.coupon_code
stringCoupon code.
coupon.campaign_code
stringCampaign code.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
operation_type
stringType of operation.
id_operation
integerOperation ID in Xsolla database.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
user.email
stringUser email.
virtual_currency_balance
objectUser balance data (object).
virtual_currency_balance.old_value
stringBalance before transaction.
virtual_currency_balance.new_value
stringBalance after transaction.
virtual_currency_balance.diff
stringQuantity of virtual currency in the purchase.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
operation_type
stringType of operation.
id_operation
integerOperation ID in Xsolla database.
user
objectUser details (object).
user.id
stringUser ID. Required.
user.name
stringUsername.
user.email
stringUser email.
virtual_currency_balance
objectUser balance data (object).
virtual_currency_balance.old_value
stringBalance before transaction.
virtual_currency_balance.new_value
stringBalance after transaction.
virtual_currency_balance.diff
stringQuantity of virtual currency in the purchase.
transaction
objectTransaction details (object). Required.
transaction.id
integerTransaction ID.
transaction.date
stringDate of transaction.
items_operation_type
stringType of operation made with virtual items.
items
arrayVirtual items within the purchase (array of objects).
items.sku
stringItem ID.
items.amount
integerItem quantity.
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.ip
stringUser IP.
user.email
stringUser email.
user.id
stringUser ID. Required.
user.name
stringUsername.
user.country
stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.zip
stringUser's ZIP or postal code.
payment_account
objectPayment account details (object).
payment_account.id
stringPayment account ID. Required.
payment_account.name
stringThe payment account name in the payment system (e.g., payment card number, email).
payment_account.payment_method
integerPayment method ID.
payment_account.type
stringType of payment account (e.g., card, PayPal).
Copy
Full screen
Small screen
http
  • http
  • curl
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.

ParameterTypeDescription
notification_type
stringType of notification. Required.
settings
objectCustom project settings (object).
settings.project_id
integerGame’s Xsolla ID. Can be found in Publisher Account.
settings.merchant_id
integerMerchant ID.
user
objectUser details (object).
user.email
stringUser email.
user.id
stringUser ID. Required.
user.name
stringUsername.
payment_account
objectPayment account details (object).
payment_account.id
stringPayment account ID. Required.
payment_account.name
stringThe payment account name in the payment system (e.g., payment card number, email).
payment_account.payment_method
integerPayment method ID.
payment_account.type
stringType of payment account (e.g., card, PayPal).
Copy
Full screen
Small screen
http
  • http
  • curl
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:

CodeMessage
INVALID_USERInvalid user.
INVALID_PARAMETERInvalid parameter.
INVALID_SIGNATUREInvalid signature.
INCORRECT_AMOUNTIncorrect amount.
INCORRECT_INVOICEIncorrect invoice.
Copy
Full screen
Small screen

HTTP/1.1 400 Bad Request

{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}