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, Partner Network 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.

Release Notes

Changes in version 2.0:
  • New URL to export transactions: https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/registry.{format}
  • Changed response format:
    • Canceled transactions now have negative values in the following fields:
      • Payment system fee, fixed
      • Xsolla revenue share, fixed
      • Sales Tax
      • Virtual currency purchase amount
      • Simple checkout purchase amount
      • Items purchase amount
      • Repatriation costs, total
      • Fees covered, fixed
      • Fees covered by Balance
      • Payout amount from payment system
      • Payment amount from Balance
      • Payout amount from Balance
      • Pin codes purchase amount
    • New fields added:
      • Payment system type - Payment type
      • VAT - VAT shown to the user
      • VAT, % - VAT percentage in that country
      • Refund reason comment - Comments on the refund reason
      • Direct account - Whether this is a direct account or not
    • Fields removed:
      • Payment system external fee (%)
      • Payment system external fee amount
      • Payment system external fee currency
    • Deducted VAT, % is set to 0 if Deducted VAT is 0
    • Fields renamed:
      • VAT -> Deducted VAT
      • VAT (%) -> Deducted VAT, %
    • The following fields are not filled in if equal to 0:
      • Virtual currency amount
      • Virtual currency purchase amount
      • Simple checkout purchase amount
      • Pin codes purchase amount
    • Virtual currency purchase currency is not filled in if Virtual currency purchase amount equals 0
    • Simple checkout purchase currency is not filled in if Simple checkout purchase amount equals 0
    • Pin codes purchase currency is not filled in if Pin codes purchase amount equals 0. Pin codes purchase cart content remains empty

Requests and Responses

Requests to Xsolla API endpoints must include the following HTTP headers: Authorization, Accept. POST and PUT requests must include one additional header: Content-Type: application/json.

By default, all endpoint responses have JSON data in the response body and include a Content-Type: application/json header.

Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Accept: application/json
Content-Type: application/json

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

Notice: Your API keys carry many privileges, so be sure to keep them secret.

Xsolla uses HTTP Basic Authentication. Provide your Merchant ID as the basic auth username and the API key (see Publisher Account > Settings) as the password.

All API requests must be sent over HTTPS. Requests via HTTP will not work. Make sure to include authentication details with each request.

Note: You must use TLS 1.2 or higher in order to use the API.
Copy
Full screen
  • php
  • http
  • curl
Example
<?php

use Xsolla\SDK\API\XsollaClient;

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));

GET /merchant/v2/merchants/{merchant_id}/events/messages HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
-X GET \
-u merchant_id:merchant_api_key

Endpoint Types

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

Action HTTP Method Description
Create POST Creates and saves an entity of the specified type.
List GET Returns a list of entities matching the query. To get details on an entity, first find out its ID using the corresponding List endpoint, and then provide this ID to the corresponding Retrieve endpoint.
Retrieve GET Provides details on the entity with the specified ID.
Replace PUT Modifies all fields of the entity with the specified ID.
Update PATCH Modifies specified fields of the entity with the specified ID.
Delete DELETE Deletes the entity with the specified ID.

Date Format

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

Pagination

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

Errors Handling

List of supported HTTP errors:

  • 200, 201, 204 — No error
  • 400 Bad Request — This often indicates a required parameter missing. Refer to the response body for details
  • 401 Unauthorized — No valid API key provided
  • 402 Request Failed — Request failed despite valid parameters
  • 403 Forbidden — No permission. Refer to the response body for details
  • 404 Not Found — The requested item doesn’t exist
  • 409, 422 — Invalid request parameters
  • 412 Precondition Failed — The project has not been activated yet (used in the Get Token method)
  • 415 Unsupported Media Type — ‘Content-Type: application/json’ missing in HTTP header
  • 500, 502, 503, 504 Server Errors — Something went wrong

Xsolla uses conventional HTTP response codes to indicate whether the API request was successful. In general, 2xx indicates success, 4xx indicates an error in the provided information (e.g., a required parameter missing, failed authorization, etc.), and 5xx indicates a problem with Xsolla’s servers.

But not all errors perfectly match HTTP response codes. For example, if a request was valid but failed, the API will return the 422 error code.

All API error responses provide a JSON object with the following fields:

{< T “api_table_name” >}} Type Description
http_status_code integer HTTP code.
message string A human-readable message describing the error. This message is always in English. Do not rely on this value for any particular error, because it might change in the future.
extended_message string More detailed error description.
request_id string Unique request ID that might be used for troubleshooting. 
{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

Token

In order to enable secure payments, Xsolla API handles payment parameters within a token instead of receiving them directly through GET requests to the payment page. You have to obtain a new token before rendering the payment page. A token is valid for 24 hours.

Get Token

HTTP REQUEST

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

You can create a token with arbitrary user parameters. You send these parameters when obtaining the token, and we send them back to you after a successful payment. A token can only contain parameters either described in this document or predefined by the partner.

Parameter Type Description
user
 object User details (object).
user.id
 object User ID (object). Required.
user.id.value
 string User ID.
user.id.hidden
 boolean Whether or not this element can be hidden on payment UI. ‘true’ by default.
user.id.allow_modify
 boolean Whether or not user can modify the field on payment UI. ‘false’ by default.
user.name
 object User screen name (object).
user.name.value
 string User screen name.
user.name.hidden
 boolean Whether or not this element can be hidden on payment UI. ‘true’ by default.
user.name.allow_modify
 boolean Whether or not user can modify the field on payment UI. ‘false’ by default.
user.email
 object User email (object).
user.email.value
 string User email.
user.email.hidden
 boolean Whether or not this element can be hidden on payment UI. ‘true’ by default.
user.email.allow_modify
 boolean Whether or not user can modify the field on payment UI. ‘false’ by default.
user.phone
 object User phone number (object).
user.phone.value
 string User phone number.
user.phone.hidden
 boolean Whether or not this element can be hidden on payment UI. ‘true’ by default.
user.phone.allow_modify
 boolean Whether or not user can modify the field on payment UI. ‘false’ by default.
user.country
 object User country (object).
user.country.value
 string Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.country.allow_modify
 boolean Whether or not user can change the country on payment UI. ‘false’ by default.
user.attributes
 object User attributes for filtering the item list, represented as a valid JSON set of key-value pairs.
user.steam_id
 object User’s Steam ID (object).
user.steam_id.value
 string Steam ID.
user.tracking_id
 object User tracking ID (object).
user.tracking_id.value
 string Unique tracking ID (used in marketing campaigns).
user.public_id.value
 string Parameter that uniquely identifies the user and is known to the user (email, screen name, etc). Allows the user to make purchases outside the game store (e.g., via cash kiosks).
user.utm
 object Traffic attributes (object).
user.utm.utm_source
 string Traffic source.
user.utm.utm_medium
 string Traffic channel (contextual ads, media ads, email lists, etc.).
user.utm.utm_campaign
 string Campaign title, transliterated or translated to English.
user.utm.utm_term
 string Campaign keyword. If set, statistics will be based on the keywords used for ad targeting rather than on specific search queries. In Google Analytics, the specified ‘utm_term’ is part of the general search terms report.
user.utm.utm_content
 string Campaign content.
boolean Whether the user is a legal entity.
object Object with legal entity details. Object and all its parameters are required if user.is_legal is ‘true’.
string Full legal name.
string Full legal address.
string Individual taxpayer identifier.
string Country of incorporation. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
settings
 object Custom project settings (object).
settings.external_id
 string Transaction’s external ID.
settings.project_id
 integer Game’s Xsolla ID. Can be found in Publisher Account. Required.
settings.language
 string Interface language. Two-letter lowercase language code per ISO 639-1.
settings.return_url
 string Page to redirect the user to after payment. Parameters ‘user_id’, ‘foreinginvoice’, ‘invoice_id’ and ‘status’ will be automatically added to the link.
settings.currency
 string Preferred payment currency. Three-letter currency code per ISO 4217.
settings.mode
 string Set to ‘sandbox’ to test out the payment process. In this case, use https://sandbox-secure.xsolla.com to access the test payment UI.
settings.payment_method
 integer Payment method ID.
settings.payment_widget
 string Payment widget. Can be ‘paybycash’ or ‘giftcard’. If the parameter is set, the user is redirected to the Pay by Cash or Gift Cards widget, respectively.
settings.ui
 object Interface settings (object).
settings.ui.theme
 string Payment UI theme. Can be ‘default’ or ‘default_dark’.
settings.ui.size
 string Payment UI size. Can be:
  • small: the least possible size of the payment UI. Use this value when the window size is strictly limited (dimensions: 620 x 630)
  • medium: recommended size. Use this value to display the payment UI in a lightbox (dimensions: 740 x 760)
  • large: the optimal size for displaying the payment UI in a new window or tab (dimensions: 820 x 840)
settings.ui.version
 string Device type. Can be ‘desktop’ (default) or ‘mobile’.
settings.ui.desktop
 object Interface settings for the desktop version (object).
settings.ui.desktop.header
 object Header settings (object).
settings.ui.desktop.header.is_visible
 boolean Whether to show the header in the payment UI.
boolean If ‘true’, the header will show your logo (please first provide the image to your account manager).
settings.ui.desktop.header.visible_name
 boolean Whether to show the project name in the header.
settings.ui.desktop.header.visible_purchase
 boolean Whether to show the purchase description (purchase.description.value) in the header. ‘true’ by default.
settings.ui.desktop.header.type
 string How to show the header. Can be ‘compact’ (hides project name and user ID) or ‘normal’ (default).
settings.ui.desktop.header.close_button
 boolean Whether to show a Close button in Pay Station desktop. The button closes Pay Station and redirects the user to the URL specified in the “settings.return_url” parameter. ‘false’ by default.
settings.ui.desktop.subscription_list
 object Settings for the list of subscription plans (object).
settings.ui.desktop.subscription_list.layout
 string List template. Can be ‘list’ (default) or ‘grid’.
settings.ui.desktop.subscription_list.description
 string Any text to show above the list of available subscription plans in the payment UI.
settings.ui.desktop.subscription_list.display_local_price
 boolean If ‘true’, and if the user’s local currency is different from the one set for the subscription plan, the user will be able to see both prices: one in the local and one in the basic currency.
settings.ui.desktop.virtual_item_list
 object Settings for the list of virtual items (object).
settings.ui.desktop.virtual_item_list.layout
 string List template. Can be ‘list’ (default) or ‘grid’.
settings.ui.desktop.virtual_item_list.button_with_price
 boolean If ‘true’, the price will be shown on the button. If ‘false’, the price will be shown on the left of the button. ‘false’ by default.
settings.ui.desktop.virtual_items_list.view
 string Display virtual item groups as a vertical/horizontal menu. Can be ‘horizontal_navigation’ or ‘vertical’ (default).
settings.ui.desktop.virtual_currency_list
 object Settings for the list of virtual currencies (object).
settings.ui.desktop.virtual_currency_list.description
 string Any text to show above the list of virtual currencies.
settings.ui.desktop.virtual_currency_list.button_with_price
 boolean If ‘true’, the price will be shown on the button. If ‘false’, the price will be shown on the left of the button. ‘false’ by default.
settings.ui.header.visible_virtual_currency_balance
 boolean Whether or not this element can be hidden on Payment UI. ‘true’ by default.
settings.ui.mobile.mode
 string A user can only pay using their saved payment methods. Can be ‘saved_accounts’.
settings.ui.mobile.header.close_button
 boolean Whether to show a Close button in Pay Station mobile. The button closes Pay Station and redirects the user to the URL specified in the “settings.return_url” parameter. ‘false’ by default.
boolean Whether to hide the footer in the mobile version of the payment UI.
settings.ui.license_url
 string Link to the EULA.
settings.ui.components
 object Menu settings (object).
settings.ui.components.virtual_items
 object Virtual items submenu.
settings.ui.components.virtual_items.order
 integer Position of the submenu in the menu.
settings.ui.components.virtual_items.hidden
 boolean Whether to show the submenu.
settings.ui.components.virtual_items.selected_group
 string Group to show after opening the virtual items tab.
settings.ui.components.virtual_items.selected_item
 string Item to show after opening the virtual items tab (item SKU).
settings.ui.components.virtual_currency
 object Virtual currency submenu.
settings.ui.components.virtual_currency.custom_amount
 boolean Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI.
settings.ui.components.virtual_currency.order
 integer Position of the submenu in the menu.
settings.ui.components.virtual_currency.hidden
 boolean Whether to show the submenu.
settings.ui.components.subscriptions
 object Subscription plans submenu (object).
settings.ui.components.subscriptions.order
 integer Position of the submenu in the menu.
settings.ui.components.subscriptions.hidden
 boolean Whether to show the submenu.
settings.ui.mode
 string Interface mode in Pay Station. Can be ‘user_account’ only: The header contains only the account navigation menu, and the user cannot select a product or make a payment. This mode is only available on the desktop.
settings.ui.user_account
 object User account details (object).
settings.ui.user_account.info
 object Page ‘My account’.
settings.ui.user_account.info.order
 integer Position of the submenu in the menu.
settings.ui.user_account.info.enable
 boolean Whether to show the submenu. ‘false’ by default.
settings.ui.user_account.history
 object History submenu.
settings.ui.user_account.history.order
 integer Position of the submenu in the menu.
settings.ui.user_account.history.enable
 boolean Whether to show the submenu. ‘false’ by default.
settings.ui.user_account.payment_accounts
 object “My payment accounts” submenu.
settings.ui.user_account.payment_accounts.order
 integer Position of the submenu in the menu.
settings.ui.user_account.payment_accounts.enable
 boolean Whether to show the submenu. ‘false’ by default.
settings.ui.user_account.subscriptions
 object “Manage subscriptions” submenu.
settings.ui.user_account.subscriptions.order
 integer Position of the submenu in the menu.
settings.ui.user_account.subscriptions.enable
 boolean Whether to show the submenu. ‘false’ by default.
settings.shipping_enabled
 boolean Whether to display the delivery address form. ‘false’ by default.
purchase
 object Object containing purchase details.
purchase.virtual_currency
 object Object containing virtual currency details.
purchase.virtual_currency.quantity
 float Purchase amount in the virtual currency.
purchase.virtual_currency.currency
 string Currency of the virtual currency package to use in all calculations.
purchase.virtual_items
 object Object with data about the virtual items in purchase.
purchase.virtual_items.currency
 string Currency of the ordered items to use in all calculations.
purchase.virtual_items.items
 array Item data (array).
purchase.virtual_items.items.sku
 string Item ID.
purchase.virtual_items.items.amount
 integer Item quantity.
purchase.virtual_items.available_groups
 array Item groups IDs (array). The payment UI will only include items within the specified group.
purchase.subscription
 object Subscription data (object).
purchase.subscription.plan_id
 string Plan ID.
purchase.subscription.operation
 string The type of operation applied to the user’s subscription plan. To change the subscription plan, pass the ‘change_plan’ value. You need to specify the new plan ID in the purchase.subscription.plan_id parameter.
purchase.subscription.product_id
 string Product ID.
purchase.subscription.currency
 string Currency of the subscription plan to use in all calculations.
purchase.subscription.available_plans
 array Subscription plans (array) to show in the payment UI.
purchase.subscription.trial_days
 integer Trial period in days.
purchase.pin_codes
 object Game keys (object).
purchase.pin_codes.currency
 string Currency of a Game key within the order to use in all calculations.
purchase.pin_codes.codes
 array Game keys (array).
purchase.pin_codes.codes.digital_content
 string Game SKU set in Publisher Account.
purchase.pin_codes.codes.drm
 string DRM platform used to distribute the game. Can be ‘steam’, ‘playstation’, ‘xbox’, ‘uplay’, ‘origin’, or ‘drmfree’. 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.checkout
 object Object containing checkout details.
purchase.checkout.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
 float Purchase amount.
purchase.description
 object Purchase description (object).
purchase.description.value
 string Purchase description to include in the UI and email receipts.
purchase.gift
 object Gift details (object).
purchase.gift.giver_id
 string Giver ID.
purchase.gift.message
 string Message from the giver.
purchase.gift.hide_giver_from_receiver
 string Whether to hide the giver identity from the recipient. ‘true’ by default.
purchase.gift.friends
 array Array with data on friends.
purchase.gift.friends.id
 string Gift recipient ID.
purchase.gift.friends.name
 string Gift recipient nickname.
purchase.gift.friends.email
 string Gift recipient email.
purchase.coupon_code
 object Information about a discount promo code or bonuses upon purchase (object).
purchase.coupon_code.value
 string Promo code value.
purchase.coupon_code.hidden
 boolean Hide the field promo code is entered into in the payment UI. ‘false’ by default.
custom_parameters
 object Your custom parameters, represented as a valid JSON set of key-value pairs.

If any parameter is sent in the wrong format or has the wrong type, no token will be issued. You will receive a 422 HTTP code with the error description in the JSON body. In “extended_message” we will provide you an information what exactly parameters have been send incorrectly.

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

Copy
Full screen
  • php
  • http
  • curl
Request
<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);

POST /merchant/v2/merchants/{merchant_id}/token HTTP/1.1
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
  "user": {
          "id": {
              "value": "1234567",
              "hidden": true
          },
          "email": {
              "value": "email@example.com",
              "allow_modify": true,
              "hidden": false
          },
          "country": {
              "value": "US"
          }
      },
      "settings": {
          "project_id": 14004,
          "language":"en",
          "currency":"USD",
          "ui": {
              "size":"medium"
          }
      },
      "purchase": {
          "virtual_currency": {
              "quantity": 100
          },
          "virtual_items": {
              "items": [{
                  "sku":"SKU01",
                  "amount":1
              }]
          },
          "description": {
              "value": "Test Purchase"
          }
      },
      "custom_parameters": {
          "parameter1": "value1"
      }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "user": {
      "id": {
          "value": "1234567",
          "hidden": true
      },
      "email": {
          "value": "email@example.com",
          "allow_modify": true,
          "hidden": false
      },
      "country": {
          "value": "US"
      }
  },
  "settings": {
      "project_id": 14004,
      "language":"en",
      "currency":"USD",
      "ui": {
          "size":"medium"
      }
  },
  "purchase": {
      "virtual_currency": {
          "quantity": 100
      },
      "virtual_items": {
          "items": [{
              "sku":"SKU01",
              "amount":1
          }]
      },
      "description": {
          "value": "Test Purchase"
      }
  },
  "custom_parameters": {
      "parameter1": "value1"
  }
    }'
Response
<?php

// example response
$token = 'uV0iCEvWkUGVqWerTgbrndWePOMiLAfO';

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "uV0iCEvWkUGVqWerTgbrndWePOMiLAfO"
}
{
    "token": "uV0iCEvWkUGVqWerTgbrndWePOMiLAfO"
}

Additional Parameters List

You can pass additional parameters in the token in order to configure anti-fraud filters. The recommended parameters are shown in the table below. You can extend the list as needed.

Parameter Type Description
registration_date
 string Account creation date per ISO 8601.
total_hours
 integer Total number of in-game hours.
total_characters
 integer Number of in-game characters.
social_networks_added
 boolean Whether the player has connected social media profiles.
profile_image_added
 boolean Whether the player has uploaded a profile image.
active_date
 string Last seen date per ISO 8601.
total_friends
 integer Number of friends.
additional_verification
 boolean Whether the player uses account verification procedures.
win_rate
 integer Win rate.
last_change_password_date
 string Last password change date per ISO 8601.
chat_activity
 boolean Whether the player uses the chat function.
forum_activity
 boolean Whether the player uses the forum function.
total_bans
 integer Number of times the player was banned in the chat/forum.
profile_completed
 boolean Whether the player added additional information to their profile.
notifications_enabled
 boolean Whether the player enabled notifications.
user_level
 integer Player’s level, reputation, or rank.
karma_points
 integer Player’s karma.
total_sum
 float Total amount of payments.
non_premium_currency
 float Amount of non-premium currency.
total_game_events
 integer Number of in-game events the player took part in.
total_gifts
 integer Number of in-game gifts the player has sent/received.
tutorial_completed
 boolean Whether the player has completed the game’s tutorial.
completed_tasks
 integer Number of tasks/objectives completed.
items_used
 boolean Whether the player uses purchased in-game items.
pvp_activity
 boolean Whether the player takes part in PvP battles.
total_clans
 integer Number of clans the player is a member of.
unlocked_achievements
 integer Number of achievements unlocked.
total_inventory_value
 float Total inventory value (in-game currency).
character_customized
 boolean Whether the player has customized their character.
session_time
 string Average session time per ISO 8601.

Webhooks

Overview

Webhooks allow you to receive notifications of events that happen to your Xsolla transactions. Use webhooks to automate back-end and supplementary functions, such as providing status and other transaction-related information.

We use webhooks for:

  • Payments, including purchases of virtual currency and items, bank card payments, and so on
  • Recurring payments and subscription actions
  • Transaction-related chargebacks/refunds

In most cases, webhooks are triggered by user actions on your website. But they can come from other actions, too. For example, a back-end process on your website may invoke an API method to refund a payment, or the payment system may send a notification about a disputed charge.

You must write or use a so-called listener, or handler, to receive and process webhooks. This is a program that waits for a webhook and usually passes it to an internal workflow of yours, which responds appropriately.

For example, you can do the following after receiving a webhook:

  • Filling up user balance
  • Unlocking new item for user
  • Starting subscription service
  • Blocking user after fraud detection

Listen to webhooks at the following IP addresses: 185.30.20.0/24, 185.30.21.0/24.

Note that your database must NOT contain two successful transactions with the same ID. If your listener receives a webhook with an existing transaction ID, it must return the latest result for that transaction. Avoid charging the user twice or creating duplicate records in your database.

Note that we cannot guarantee that your listener will receive all the webhooks we send. As Internet connections are not 100% reliable, webhooks may fail to come on time or at all. To address these issues, we provide a retry mechanism that re-sends failed messages at various intervals until your listener acknowledges their receipt. A repeated webhook may be sent within 12 hours after the previous one. The maximum number of retries is 12.

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

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
  • 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 Type Description
user_validation Check if a user exists in the game.
user_search Get user info based on Public User ID.
payment Sent when a user completes a payment.
refund Sent when a payment must be canceled for any reason.
afs_reject Sent when a transaction is declined during an AFS check.
create_subscription Sent when a user creates a subscription.
update_subscription Sent when a subscription is renewed or changed.
cancel_subscription Sent when a subscription is canceled.
get_pincode Sent when Xsolla API needs to obtain the game keys.
user_balance_operation Sent when a user balance changes (the type of operation is sent in operation_type).
redeem_key Sent when a user activates a key.

User Validation

Sent to verify that a user exists in the game.

Parameter Type Description
user
 object User details (object).
user.ip
 string User IP.
user.phone
 string User phone.
user.email
 string User email.
user.id
 string User ID. Required.
user.name
 string Username.
user.country
 string User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'user_validation',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
    "notification_type":"user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}'
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).

Parameter Type Description
notification_type
 string Type of notification. Required.
user
 object User details (object). Required.
user.public_id
 string Public user ID.
user.id
 string User ID.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'user_search',
    'user' => array(
        'public_id' => 'public_email@example.com'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"user_search",
    "user": {
        "public_id": "public_email@example.com"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
    "notification_type":"user_search",
    "user": {
        "public_id": "public_email@example.com"
    }
}'
Response
<?php
​
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
​
$callback = function (Message $message) {
    if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
        $userArray = $message->getUser();
        $userPublicId = $message->getUserPublicId();
        // TODO get a user from your database and fill the user data to model.
        $user = new \Xsolla\SDK\Webhook\User();
        $user->setId('user_id')
            ->setPublicId($userPublicId)
            ->setEmail('user_email') //Optional field
            ->setPhone('user_phone') //Optional field
            ->setName('user_name'); //Optional field
        //TODO if user not found, you should throw InvalidUserException
        return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
    }
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}
{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}

Payment

Sent whenever a user completes a payment. Includes payment details.

Parameter Type Description
notification_type
 string Type of notification. Required.
purchase
 object Purchase details (object).
purchase.virtual_currency
 object Virtual currency to purchase (object).
purchase.virtual_currency.name
 string Virtual currency name.
purchase.virtual_currency.sku
 string Virtual currency package SKU (if set for the virtual currency package).
purchase.virtual_currency.quantity
 float Quantity.
purchase.virtual_currency.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_currency.amount
 float Price in real currency.
purchase.checkout
 object Checkout details (object).
purchase.checkout.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
 float Purchase amount.
purchase.subscription
 object Subscription detsils (object).
purchase.subscription.plan_id
 string Plan ID (external if the plan was created via API).
purchase.subscription.subscription_id
 integer Subscription ID in Xsolla database.
purchase.subscription.product_id
 string Product ID (if sent in the access token).
purchase.subscription.tags
 array Plan tags.
purchase.subscription.date_create
 string Subscription creation date. Date and time per ISO 8601.
purchase.subscription.date_next_charge
 string Next billing date. Date and time per ISO 8601.
purchase.subscription.currency
 string Subscription currency. Three-letter currency code per ISO 4217.
purchase.subscription.amount
 float Price in real currency.
purchase.virtual_items
 object Virtual items in purchase (object).
purchase.virtual_items.items
 array Item data (array).
purchase.virtual_items.items.sku
 string Item ID.
purchase.virtual_items.items.amount
 integer Item quantity.
purchase.virtual_items.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_items.amount
 integer Purchase amount.
purchase.pin_codes
 object Game keys (array).
purchase.pin_codes.digital_content
 string Game SKU set in Publisher Account.
purchase.pin_codes.drm
 string DRM platform used to distribute the game. Can be ‘steam’, ‘playstation’, ‘xbox’, ‘uplay’, ‘origin’, or ‘drmfree’. Make sure that you have configured the required DRM platforms in your Publisher Account.
purchase.pin_codes.currency
 string Currency that the game keys is purchased for. Three-letter currency code per ISO 4217.
purchase.pin_codes.amount
 float Price.
purchase.gift
 object Gift details (object).
purchase.gift.giver_id
 string Giver ID.
purchase.gift.receiver_id
 string Gift recipient ID.
purchase.gift.receiver_email
 string Gift recipient email.
purchase.gift.message
 string Message from the giver.
purchase.gift.hide_giver_from_receiver
 string Whether to hide the giver identity from the recipient.
purchase.total
 object Total price of purchase (object). Required.
purchase.total.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.total.amount
 float Total payment amount.
purchase.promotions
 array Promotions applied to this transaction (array).
purchase.promotions.technical_name
 string Technical name of the promotion.
purchase.promotions.id
 integer Promotion ID.
purchase.coupon
 object Coupon details (object; if a coupon was used when creating the subscription).
purchase.coupon.coupon_code
 string Coupon code.
purchase.coupon.campaign_code
 string Campaign code.
user
 object User details (object).
user.ip
 string User IP.
user.phone
 string User phone.
user.email
 string User email.
user.id
 string User ID. Required.
user.name
 string Username.
user.country
 string User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.zip
 string User’s ZIP or postal code.
transaction
 object Transaction details (object). Required.
transaction.id
 integer Transaction ID.
transaction.external_id
 string Transaction external ID.
transaction.payment_date
 string Date of payment.
transaction.payment_method
 integer Payment method identifier.
transaction.dry_run
 integer Test transaction. 1 if test transaction, 0 if not.
transaction.agreement
 integer Agreement ID.
payment_details
 object Payment details (object). Required.
payment_details.payment
 object Amount paid by the user (object).
payment_details.payment.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payment.amount
 string Amount.
payment_details.payment_method_sum
 object Amount debited from the payment system.
payment_details.payment_method_sum.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payment_method_sum.amount
 string Amount.
payment_details.xsolla_balance_sum
 object Amount debited from Xsolla balance.
payment_details.xsolla_balance_sum.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.xsolla_balance_sum.amount
 string Amount.
payment_details.payout
 object Payout details (object).
payment_details.payout.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payout.amount
 float Amount.
payment_details.vat
 object VAT details (object; EU only).
payment_details.vat.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.vat.amount
 float Amount.
payment_details.payout_currency_rate
 float Exchange rate between payment and payout currencies.
payment_details.xsolla_fee
 object Xsolla fee (object).
payment_details.xsolla_fee.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.xsolla_fee.amount
 float Amount.
payment_details.payment_method_fee
 object Payment system fee.
payment_details.payment_method_fee.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payment_method_fee.amount
 float Amount.
payment_details.sales_tax
 object Sales tax (object; USA only).
payment_details.sales_tax.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.sales_tax.amount
 float Amount.
payment_details.repatriation_commission
 object Object with data on repatriation costs, imposed on Xsolla by third parties.
payment_details.repatriation_commission.currency
 string Repatriation costs currency. Three-letter currency code per ISO 4217.
payment_details.repatriation_commission.amount
 float Repatriation costs amount.
custom_parameters
 object Your custom parameters.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'payment',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1721
Authorization: Signature 34553d151e656110c656696c919f9a10e05de542

{
    "notification_type":"payment",
    "purchase":{
        "virtual_currency":{
            "name":"Coins",
            "sku":"test_package1",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "total":{
            "currency":"USD",
            "amount":200
        },
        "promotions":[{
            "technical_name":"Demo Promotion",
            "id":"853"
        }],
        "coupon":{
            "coupon_code":"ICvj45S4FUOyy",
            "campaign_code":"1507"
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "payment_date":"2014-09-24T20:38:16+04:00",
        "payment_method":1,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout":{
            "currency":"USD",
            "amount":200
        },
        "xsolla_fee":{
            "currency":"USD",
            "amount":10
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":20
        },
        "repatriation_commission":{
            "currency":"USD",
            "amount":"10"
        }
    },
    "custom_parameters":{
        "parameter1":"value1",
        "parameter2":"value2"
    }
}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type":"payment",
    "purchase":{
        "virtual_currency":{
            "name":"Coins",
            "sku":"test_package1",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "total":{
            "currency":"USD",
            "amount":200
        },
        "promotions":[{
            "technical_name":"Demo Promotion",
            "id":"853"
        }],
        "coupon":{
             "coupon_code":"ICvj45S4FUOyy",
             "campaign_code":"1507"
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "payment_date":"2014-09-24T20:38:16+04:00",
        "payment_method":1,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout":{
            "currency":"USD",
            "amount":200
        },
        "xsolla_fee":{
            "currency":"USD",
            "amount":10
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":20
        },
        "repatriation_commission":{
            "currency":"USD",
            "amount":"10"
        }
    },
    "custom_parameters":{
        "parameter1":"value1",
        "parameter2":"value2"
    }
}'
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.

Parameter Type Description
notification_type
 string Type of notification. Required.
purchase
 object Purchase details (object).
purchase.virtual_currency
 object Virtual currency to purchase (object).
purchase.virtual_currency.name
 string Virtual currency name.
purchase.virtual_currency.quantity
 float Quantity.
purchase.virtual_currency.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_currency.amount
 float Price in real currency.
purchase.checkout
 object Checkout details (object).
purchase.checkout.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.checkout.amount
 float Purchase amount.
purchase.subscription
 object Subscription detsils (object).
purchase.subscription.plan_id
 string Plan ID (external if the plan was created via API).
purchase.subscription.tags
 array Plan tags.
purchase.subscription.subscription_id
 integer Subscription ID in Xsolla database.
purchase.subscription.date_create
 string Subscription creation date. Date and time per ISO 8601.
purchase.subscription.currency
 string Subscription currency. Three-letter currency code per ISO 4217.
purchase.subscription.amount
 float Price in real currency.
purchase.virtual_items
 object Virtual items in purchase (object).
purchase.virtual_items.items
 array Item data (array).
purchase.virtual_items.items.sku
 string Item ID.
purchase.virtual_items.items.amount
 integer Item quantity.
purchase.virtual_items.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.virtual_items.amount
 integer Purchase amount.
purchase.total
 object Total price of purchase (object).
purchase.total.currency
 string Currency of the purchase. Three-letter currency code per ISO 4217.
purchase.total.amount
 float Total payment amount.
user
 object User details (object).
user.ip
 string User IP.
user.phone
 string User phone.
user.email
 string User email.
user.id
 string User ID. Required.
user.name
 string Username.
user.country
 string User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.zip
 string User’s ZIP or postal code.
transaction
 object Transaction details (object). Required.
transaction.id
 integer Transaction ID.
transaction.external_id
 string Transaction external ID.
transaction.dry_run
 integer Test transaction. 1 if test transaction, 0 if not.
transaction.agreement
 integer Agreement ID.
refund_details
 object Refund details (object).
refund_details.code
 integer Code ID.
refund_details.reason
 string Refund reason.
refund_details.author
 string Refund initiator.
payment_details
 object Payment details (object). Required.
payment_details.payment
 object Amount paid by the user (object).
payment_details.payment.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payment.amount
 string Amount.
payment_details.payment_method_sum
 object Amount debited from the payment system.
payment_details.payment_method_sum.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payment_method_sum.amount
 string Amount.
payment_details.xsolla_balance_sum
 object Amount debited from Xsolla balance.
payment_details.xsolla_balance_sum.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.xsolla_balance_sum.amount
 string Amount.
payment_details.payout
 object Payout details (object).
payment_details.payout.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payout.amount
 float Amount.
payment_details.vat
 object VAT details (object; EU only).
payment_details.vat.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.vat.amount
 float Amount.
payment_details.payout_currency_rate
 float Exchange rate between payment and payout currencies.
payment_details.xsolla_fee
 object Xsolla fee (object).
payment_details.xsolla_fee.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.xsolla_fee.amount
 float Amount.
payment_details.payment_method_fee
 object Payment system fee.
payment_details.payment_method_fee.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.payment_method_fee.amount
 float Amount.
payment_details.sales_tax
 object Sales tax (object; USA only).
payment_details.sales_tax.currency
 string Currency. Three-letter currency code per ISO 4217.
payment_details.sales_tax.amount
 float Amount.
payment_details.repatriation_commission
 object Object with data on repatriation costs, imposed on Xsolla by third parties.
payment_details.repatriation_commission.currency
 string Repatriation costs currency. Three-letter currency code per ISO 4217.
payment_details.repatriation_commission.amount
 float Repatriation costs amount.
custom_parameters
 object Your custom parameters.

Refund codes:

Code Reason Description
1. Cancellation by the user request / the game request. Cancellation initiated from Publisher Account.
2. Chargeback. Transaction chargeback requested.
3. Integration Error. Issues in integration between Xsolla and the game. Recommendation: Do not blacklist the user.
4. Fraud. Fraud suspected.
5. Test Payment. Test transaction followed by cancellation. Recommendation: Do not blacklist the user.
6. Expired Invoice. Invoice overdue (used for postpaid model).
7. PS debt cancel. Payout refused by payment system. Recommendation: Do not blacklist the user.
8. Cancellation by the PS request. Cancellation requested by payment system. Recommendation: Do not blacklist the user.
9. Cancellation by the user request. The user was not satisfied with the game or the purchase for any reason. Recommendation: Do not blacklist the user.
10. Cancellation by the game request. Cancellation requested by the game. Recommendation: Do not blacklist the user.
11. Account holder called to report fraud. The account owner states that they didn’t make the transaction.
12. Friendly fraud. Friendly fraud reported.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'refund',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => array(
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
    "notification_type":"refund",
    "purchase":{
        "virtual_currency":{
            "name": "Coins",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "date_create": "2014-09-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "total":{
            "currency":"USD",
            "amount":200
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":1,
        "reason":"Fraud"
    },
    "payment_details":{
        "xsolla_fee":{
            "currency":"USD",
            "amount":"10"
        },
        "payout":{
            "currency":"USD",
            "amount":"200"
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":"20"
        },
        "payment":{
            "currency":"USD",
            "amount":"230"
        },
        "repatriation_commission":{
            "currency":"USD",
            "amount":"10"
        }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type":"refund",
        "purchase":{
            "virtual_currency":{
                "name": "Coins",
                "quantity":10,
                "currency":"USD",
                "amount":100
            },
            "subscription":{
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "date_create": "2014-09-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout":{
                "currency":"USD",
                "amount":50
            },
            "virtual_items":{
                "items":[
                    {
                        "sku": "test_item1",
                        "amount":1
                    }
                ],
                "currency":"USD",
                "amount":50
            },
            "total":{
                "currency":"USD",
                "amount":200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction":{
            "id":1,
            "external_id":1,
            "dry_run":1,
            "agreement":1
        },
        "refund_details":{
            "code":1,
            "reason":"Fraud"
        },
        "payment_details":{
            "xsolla_fee":{
                "currency":"USD",
                "amount":"10"
            },
            "payout":{
                "currency":"USD",
                "amount":"200"
            },
            "payment_method_fee":{
                "currency":"USD",
                "amount":"20"
            },
            "payment":{
                "currency":"USD",
                "amount":"230"
            },
            "repatriation_commission":{
                "currency":"USD",
                "amount":"10"
            }
        }
    }
}'
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

AFS Rejected Transaction

When a transaction is declined during an AFS check, Xsolla sends transaction details to the URL webhook. To enable this notification, please contact the account manager.

Parameter Type Description
notification_type
 string Type of notification. Required.
user
 object User details (object).
user.ip
 string User IP.
user.phone
 string User phone.
user.email
 string User email.
user.id
 string User ID. Required.
user.name
 string Username.
user.country
 string User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
user.zip
 string User’s ZIP or postal code.
transaction
 object Transaction details (object). Required.
transaction.id
 integer Transaction ID.
transaction.external_id
 string Transaction external ID.
transaction.dry_run
 integer Test transaction. 1 if test transaction, 0 if not.
transaction.agreement
 integer Agreement ID.
refund_details
 object Refund details (object).
refund_details.code
 integer Code ID.
refund_details.reason
 string Refund reason.
refund_details.author
 string Refund initiator.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'afs_reject',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => array(
            'code' => 4,
            'reason' => 'Potential fraud'
    )
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
    "notification_type":"afs_reject",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "semail@example.com,
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":4,
        "reason":"Potential fraud"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
  "notification_type":"afs_reject",
  "user": {
      "ip": "127.0.0.1",
      "phone": "18777976552",
      "email": "semail@example.com,
      "id": "1234567",
      "name": "Xsolla User",
      "country": "US"
  },
  "transaction":{
      "id":1,
      "external_id":1,
      "dry_run":1,
      "agreement":1
  },
  "refund_details":{
      "code":4,
      "reason":"Potential fraud"
  }
}'
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

Created Subscription

When a user creates a subscription, we send a notification to your payment notification script.

Parameter Type Description
notification_type
 string Type of notification. Required.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
subscription
 object Subscription details (object).
subscription.plan_id
 string Plan ID (external if the plan was created via API).
subscription.tags
 array Plan tags.
subscription.subscription_id
 integer Subscription ID in Xsolla database.
subscription.product_id
 string Product ID (if sent in the access token).
subscription.date_create
 string Subscription creation date. Date and time per ISO 8601.
subscription.date_end
 string Subscription termination date. Date and time per ISO 8601.
subscription.trial
 object Trial period (object).
subscription.trial.value
 integer Trial period.
subscription.trial.type
 string Trial period type: day.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'create_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_next_charge' => '2015-01-22T19:25:25+04:00',
        'trial' =>  array(
                'value' =>  90,
                'type' =>  'day'
            )
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"create_subscription",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "subscription":{
        "plan_id":"b5dac9c8",
        "subscription_id":"10",
        "product_id":"Demo Product",
        "date_create":"2014-09-22T19:25:25+04:00",
        "date_next_charge":"2015-01-22T19:25:25+04:00",
        "trial": {
                "value": 90,
                "type": "day"
            }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"create_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_next_charge":"2015-01-22T19:25:25+04:00",
            "trial": {
                    "value": 90,
                    "type": "day"
                }
        }
    }'
Response
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof CreateSubscriptionMessage) {
       $messageArray = $message->toArray();
       // TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

Updated Subscription

If some parameters in subscription (“plan_id”, “date_next_charge”) were changed and in case of every subscription renewal, we send the notification “update_subscription” on your webhook URL.

Parameter Type Description
notification_type
 string Type of notification. Required.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
subscription
 object Subscription details (object).
subscription.plan_id
 string Plan ID (external if the plan was created via API).
subscription.tags
 array Plan tags.
subscription.subscription_id
 integer Subscription ID in Xsolla database.
subscription.product_id
 string Product ID (if sent in the access token).
subscription.date_next_charge
 string Next billing date. Date and time per ISO 8601.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'update_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_next_charge' => '2015-01-22T19:25:25+04:00'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"update_subscription",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "subscription":{
        "plan_id":"b5dac9c8",
        "subscription_id":"10",
        "product_id":"Demo Product",
        "date_next_charge":"2015-01-22T19:25:25+04:00"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"update_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_next_charge":"2015-01-22T19:25:25+04:00"
        }
    }'
Response
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
  if ($message instanceof UpdateSubscriptionMessage) {
     $messageArray = $message->toArray();
     // TODO if the subscription renewing fails for some reason, you should throw XsollaWebhookException
  }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

Canceled Subscription

When a subscription is canceled for any reason, we send a notification to your payment notification script.

Parameter Type Description
notification_type
 string Type of notification. Required.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
subscription
 object Subscription details (object).
subscription.plan_id
 string Plan ID (external if the plan was created via API).
subscription.tags
 array Plan tags.
subscription.subscription_id
 integer Subscription ID in Xsolla database.
subscription.product_id
 string Product ID (if sent in the access token).
subscription.date_create
 string Subscription creation date. Date and time per ISO 8601.
subscription.date_end
 string Subscription termination date. Date and time per ISO 8601.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'notification_type' => 'cancel_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_end' => '2015-01-22T19:25:25+04:00',
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"cancel_subscription",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "subscription":{
        "plan_id":"b5dac9c8",
        "subscription_id":"10",
        "product_id":"Demo Product",
        "date_create":"2014-09-22T19:25:25+04:00",
        "date_end":"2015-01-22T19:25:25+04:00"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"cancel_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_end":"2015-01-22T19:25:25+04:00"
        }
    }'
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

Get Game Keys

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

Parameter Type Description
notification_type
 string Type of notification.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
pin_code
 object Game keys details (object).
pin_code.digital_content
 string Game SKU.
pin_code.DRM
 string DRM platform used to distribute the game.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array (
       'notification_type' => 'get_pincode',
       'user' =>
           array (
               'id' => '1234567',
               'name' => 'Xsolla User',
           ),
       'pin_code' =>
           array (
               'digital_content' => 'Game SKU',
               'DRM' => 'Steam',
           ),
   );

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"get_pincode",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "pin_code":{
        "digital_content":"Game SKU",
        "DRM":"Steam"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"get_pincode",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "pin_code":{
            "digital_content":"Game SKU",
            "DRM":"Steam"
        }
    }'
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 the notification to your webhook URL.

Parameter Type Description
notification_type
 string Notification type.
key
 string Activation key.
sku
 string Unique key package ID.
user_id
 string User ID.
activation_date
 datetime Key activation date in the YYYYMMDDHHMMSS format per ISO 8601.
user_country
 string User country. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
restriction
 object Object with regional restriction cluster settings. The cluster includes a restriction type and a list of countries, servers and locales for which the game is available.
restriction.sku
 string Unique cluster ID.
restriction.name
 string Cluster name.
restriction.types
 array Array of restriction types.
restriction_countries
 array Array of countries in the cluster.
restriction.servers
 array Array of game servers.
restriction.locales
 array Array of locales.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php
$request = array(
    'notification_type' => 'redeem_key',
    'key' => ‘wqdqwwddq9099022’,
    'sku' => 123,
    'user_id' => ‘sample_user’,
    'activation_date' => ‘2018-11-20T08:38:51+03:00’,
    'user_country' => ‘EN’,
    'restriction' =>
           array(
                'name' => ‘cls_1’,
                'types' =>
                        array(
                            ‘activation’
                        ),
                'countries' =>
                        array(
                            ‘RU’
                        ),
             ),
);  

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

{
  "notification_type": "redeem_key",
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
        ]
  }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
     "notification_type": "redeem_key",
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
         ]
    }
}'
Response
<?php

$response = null;

HTTP/1.1 204 No Content

Get Friends

The API should be implemented on the partner’s side. The maximum number of friends is 2000. See the recipe.

HTTP REQUEST

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

Parameter Type Description
notification_type
 string ID that defines the type of request to get the list of friends. The value is ‘friends_list’.
user
 string Unique ID of the user buying the gift.
query
 string Friend’s name or ID (full or partial).
limit
 string Limit for the number of elements on the page. Required.
offset
 integer Number of the element from which the list is generated (the count starts from 0).
sign
 string Signature line, generated as follows:
  • Concatenate notification_type + parameter values sorted alphabetically by the key + secret_key
  • Apply SHA-1 to the resulting string
Copy
Full screen
  • 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.

Parameter Type Description
notification_type
 string Type of notification.
operation_type
 string Type of operation.
id_operation
 integer Operation ID in Xsolla database.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
user.email
 string User email.
virtual_currency_balance
 object User balance data (object).
virtual_currency_balance.old_value
 string Balance before transaction.
virtual_currency_balance.new_value
 string Balance after transaction.
virtual_currency_balance.diff
 string Quantity of virtual currency in the purchase.
transaction
 object Transaction details (object). Required.
transaction.id
 integer Transaction ID.
transaction.date
 string Date of transaction.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '200',
        'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'transaction => array(
        'id' => '123456789',
        'date' => '2015-05-19T15:54:40+03:00'
    ),
    'operation_type' => 'payment',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '66989'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"200",
        "diff":"200"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "transaction":{
        "id":"123456789",
        "date":"2015-05-19T15:54:40+03:00"
    },
    "operation_type":"payment",
    "notification_type":"user_balance_operation",
    "id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"200",
            "diff":"200"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "transaction":{
            "id":"123456789",
            "date":"2015-05-19T15:54:40+03:00"
        },
        "operation_type":"payment",
        "notification_type":"user_balance_operation",
        "id_operation":"66989"
    }'
Response
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

User Balance: Purchase

Sent when a user purchases something inside the game. Specifies the change in the user’s balance.

Parameter Type Description
notification_type
 string Type of notification.
operation_type
 string Type of operation.
id_operation
 integer Operation ID in Xsolla database.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
user.email
 string User email.
virtual_currency_balance
 object User balance data (object).
virtual_currency_balance.old_value
 string Balance before transaction.
virtual_currency_balance.new_value
 string Balance after transaction.
virtual_currency_balance.diff
 string Quantity of virtual currency in the purchase.
items_operation_type
 string Type of operation made with virtual items.
items
 array Virtual items within the purchase (array of objects).
items.sku
 string Item ID.
items.amount
 integer Item quantity.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"200",
        "diff":"200"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "operation_type":"inGamePurchase",
    "notification_type":"user_balance_operation",
    "items_operation_type": "add",
         "items": [{
         "sku": "1468",
         "amount": "2"
         }],
    "id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"200",
            "diff":"200"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"inGamePurchase",
        "notification_type":"user_balance_operation",
        "items_operation_type": "add",
             "items": [{
             "sku": "1468",
             "amount": "2"
             }],
        "id_operation":"66989"
    }'
Response
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

User Balance: Redeem Coupon

Sent when a user redeems a coupon to receive virtual items or virtual currency.

Parameter Type Description
notification_type
 string Type of notification.
operation_type
 string Type of operation.
id_operation
 integer Operation ID in Xsolla database.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
user.email
 string User email.
virtual_currency_balance
 object User balance data (object).
virtual_currency_balance.old_value
 string Balance before transaction.
virtual_currency_balance.new_value
 string Balance after transaction.
virtual_currency_balance.diff
 string Quantity of virtual currency in the purchase.
items_operation_type
 string Type of operation made with virtual items.
items
 array Virtual items within the purchase (array of objects).
items.sku
 string Item ID.
items.amount
 integer Item quantity.
coupon
 object Coupon details (object).
coupon.coupon_code
 string Coupon code.
coupon.campaign_code
 string Campaign code.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '0',
        'diff' => '0'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'coupon',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989',
    'coupon' =>  array(
         'coupon_code' =>  'test123',
         'campaign_code' =>  'Xsolla Campaign'
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"0",
        "diff":"0"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "operation_type":"coupon",
    "notification_type":"user_balance_operation",
    "items_operation_type": "add",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation":"66989",
    "coupon": {
         "coupon_code": "test123",
         "campaign_code": "Xsolla Campaign"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"0",
            "diff":"0"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"coupon",
        "notification_type":"user_balance_operation",
        "items_operation_type": "add",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation":"66989",
        "coupon": {
             "coupon_code": "test123",
             "campaign_code": "Xsolla Campaign"
        }
    }'
Response
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

User Balance: Manual Update

Sent when a user’s balance is changed manually.

Parameter Type Description
notification_type
 string Type of notification.
operation_type
 string Type of operation.
id_operation
 integer Operation ID in Xsolla database.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
user.email
 string User email.
virtual_currency_balance
 object User balance data (object).
virtual_currency_balance.old_value
 string Balance before transaction.
virtual_currency_balance.new_value
 string Balance after transaction.
virtual_currency_balance.diff
 string Quantity of virtual currency in the purchase.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '100',
        'diff' => '100'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'internal',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '67002'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"100",
        "diff":"100"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "operation_type":"internal",
    "notification_type":"user_balance_operation",
    "id_operation":"67002"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"100",
            "diff":"100"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"internal",
        "notification_type":"user_balance_operation",
        "id_operation":"67002"
    }'
Response
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

User Balance: Refund

Sent when a user cancels a payment. Specifies the change in the user’s balance.

Parameter Type Description
notification_type
 string Type of notification.
operation_type
 string Type of operation.
id_operation
 integer Operation ID in Xsolla database.
user
 object User details (object).
user.id
 string User ID. Required.
user.name
 string Username.
user.email
 string User email.
virtual_currency_balance
 object User balance data (object).
virtual_currency_balance.old_value
 string Balance before transaction.
virtual_currency_balance.new_value
 string Balance after transaction.
virtual_currency_balance.diff
 string Quantity of virtual currency in the purchase.
transaction
 object Transaction details (object). Required.
transaction.id
 integer Transaction ID.
transaction.date
 string Date of transaction.
items_operation_type
 string Type of operation made with virtual items.
items
 array Virtual items within the purchase (array of objects).
items.sku
 string Item ID.
items.amount
 integer Item quantity.
Copy
Full screen
  • php
  • http
  • curl
Request
<?php

$request = array(
     'virtual_currency_balance' => array(
         'old_value' => '0',
         'new_value' => '0',
         'diff' => '0'
     ),
     'user' => array(
         'name' => 'Xsolla User',
         'id' => '1234567',
         'email' => 'email@example.com'
     ),
     'transaction' => array(
         'id' => '123456789',
         'date' => '2015-05-19T15:54:40+03:00'
     ),
     'operation_type' => 'cancellation',
     'notification_type' => 'user_balance_operation',
     'items_operation_type' =>  'remove',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
     'id_operation' => '66989'
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"0",
        "diff":"0"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "transaction":{
        "id":"123456789",
        "date":"2015-05-19T15:54:40+03:00"
    },
    "operation_type":"cancellation",
    "notification_type":"user_balance_operation",
    "items_operation_type": "remove",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"0",
            "diff":"0"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "transaction":{
            "id":"123456789",
            "date":"2015-05-19T15:54:40+03:00"
        },
        "operation_type":"cancellation",
        "notification_type":"user_balance_operation",
        "items_operation_type": "remove",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation":"66989"
    }'
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

Webhooks Errors

Permanent error codes:

Code Message
INVALID_USER Invalid user.
INVALID_PARAMETER Invalid parameter.
INVALID_SIGNATURE Invalid signature.
INCORRECT_AMOUNT Incorrect amount.
INCORRECT_INVOICE Incorrect invoice. 

HTTP/1.1 400 Bad Request

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