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