Overview
Xsolla API includes:
Pay Station API — payment UI and tokenization methods.Commerce API — methods for working with In-Game Store and Buy Button modules.Subscription API — methods for Subscriptions.Publisher Account API — methods for working with Publisher Account projects and users, reports, and support tickets.Login API — methods for user authentication using your own interface (see integration guide).
Xsolla API uses the REST architecture. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. The API always responds in the JSON format, including in case of errors.
The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.
Xsolla API uses the following endpoint paths:
https://api.xsolla.com— Pay Station API,Commerce API , Publisher Account APIhttps://login.xsolla.com/api— Login API
Requests and Responses
The requests to Xsolla API must:
- be sent over HTTPS,
- use TLS 1.2 or higher,
- contain authentication parameters,
- contain an additional header:
Content-Type: application/jsonfor PUT and POST requests.
Copy
Authorization: Basic <your_authorization_basic_key>
Content-Type: application/jsonBy default, all requests return a response with JSON data in the body and Content-Type: application/json in the header.
API Changes
Xsolla may change the API functionality as follows:
- Add new API resources
- Add optional request parameters
- Add new properties to existing API responses
- Add new values for existing parameters with enumerable values
- Add new webhook types and JSON parameters
- Add optional HTTP request headers
- Reject any request in which valid parameters contain invalid values
- Reject improperly formed requests that were previously accepted due to lenient parsing, if the parsing logic is changed
- Add, change, or remove undocumented functionality at any time
Your client should remain functional regardless of such changes. For example, new JSON parameters that aren’t recognized by your client should not hinder its normal operation.
Versioning
All Xsolla API methods support versioning. We will issue a new version every time there are changes incompatible with the current version. The version is identified by "v1"/"v2"/etc. following the "/merchant" prefix in the URL.
If this is your first time working with the API, use the latest version. If you omit the version, we will use the first version by default.
Info:
Keep in mind that we can only guarantee API integrity within the same version.
Authentication
Xsolla API uses basic access authentication. All requests to API must contain the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant_id:api_key pair encoded according to the Base64 standard.
Go to Xsolla Publisher Account to find values of the merchant_id and api_key parameters:
- merchant_id: Company settings > Company > Merchant ID
- api_key: Company settings > API key
Notice:
- Keep your API key in secret. It provides access to your personal account and your projects in Publisher Account.
- Changing the API key may stop payments to all your projects. API calls that use your current key will stop working until you update them with your new key.
Copy
http
- http
- curl
- php
- C#
- python
- ruby
- java
- js
Example
GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
Headers:
Authorization: Basic <your_authorization_basic_key>curl --request GET \
--url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'<?php
// if you use Xsolla SDK for PHP
use Xsolla\SDK\API\XsollaClient;
$xsollaClient = XsollaClient::factory(array(
'merchant_id' => MERCHANT_ID,
'api_key' => API_KEY
));
$eventsList = $client->ListEvents(array());
// if you don’t use Xsolla SDK for PHP
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Basic <your_authorization_basic_key>'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);
import http.client
conn = http.client.HTTPSConnection("api.xsolla.com")
headers = { 'authorization': "Basic <your_authorization_basic_key>" }
conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))require 'uri'
require 'net/http'
url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'
response = http.request(request)
puts response.read_bodyOkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
.get()
.addHeader("authorization", "Basic <your_authorization_basic_key>")
.build();
Response response = client.newCall(request).execute();var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
xhr.send(data);
Endpoint Types
The type of an endpoint indicates what kind of data it handles and what action it performs on it. The most common actions are:| Action | HTTP Method | Description |
|---|---|---|
| Create | POST | Creates and saves an entity of the specified type. |
| List | GET | Returns a list of entities matching the query. To get details on an entity, first find out its ID using the corresponding List endpoint, and then provide this ID to the corresponding Retrieve endpoint. |
| Retrieve | GET | Provides details on the entity with the specified ID. |
| Replace | PUT | Modifies all fields of the entity with the specified ID. |
| Update | PATCH | Modifies specified fields of the entity with the specified ID. |
| Delete | DELETE | Deletes the entity with the specified ID. |
Date Format
All dates are specified as strings according to ISO 8601. You can specify date strings either in UTC (e.g., 2013-01-15T00:00:00Z), or indicating the UTC offset (e.g., 2013-01-15T00:00:00-08:00 for eight hours behind UTC). In the latter case, make sure to take into account the daylight saving time, if applicable.Pagination
List endpoints might paginate the results they return. This means that, instead of returning all results in a single response, these endpoints might return some of the results, along with a response header that links to the next set of results. For this purpose we use offset and limit parameters.Errors Handling
List of supported HTTP errors:
- 200, 201, 204 — No error
- 400 Bad Request — This often indicates a required parameter missing. Refer to the response body for details
- 401 Unauthorized — No valid API key provided
- 402 Request Failed — Request failed despite valid parameters
- 403 Forbidden — No permission. Refer to the response body for details
- 404 Not Found — The requested item doesn’t exist
- 409, 422 — Invalid request parameters
- 412 Precondition Failed — The project has not been activated yet (used in the Get Token method)
- 415 Unsupported Media Type —
Content-Type: application/jsonmissing 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. |
Copy
- http
{
"http_status_code": 500,
"message": "Internal Server Error",
"extended_message": null,
"request_id": "6445b85"
}Webhooks
Overview
Webhooks allow you to receive notifications of events that happen to your Xsolla transactions. Use webhooks to automate back-end and supplementary functions, such as providing status and other transaction-related information.
We use webhooks for:
- Payments, including purchases of virtual currency and items, bank card payments, and so on
- Recurring payments and subscription actions
- Transaction-related charge-backs/refunds
In most cases, webhooks are triggered by user actions on your website. But they can come from other actions, too. For example, a back-end process on your website may invoke an API method to refund a payment, or the payment system may send a notification about a disputed charge.
You must write or use a so-called listener, or handler, to receive and process webhooks. This is a program that waits for a webhook and usually passes it to an internal workflow of yours, which responds appropriately.
For example, you can do the following after receiving a webhook:
- Filling up a user’s balance
- Unlocking new item for a user
- Starting subscription service
- Blocking user after fraud detection
Listen to webhooks at the following IP addresses: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
Notice:
Your database must NOT contain two successful transactions with the same ID. If your listener receives a webhook with an existing transaction ID, it must return the latest result for that transaction. Avoid charging the user twice or creating duplicate records in your database.
We cannot guarantee that your listener will receive all the webhooks we send. As internet connection is not 100% reliable, webhooks may fail to come on time or at all. Moreover, your listener may return a 5xx HTTP code for a temporary error on your server. For example, your listener returns a 500 HTTP response code in case a virtual item that a user purchased successfully was not added to the user’s inventory.
To address these issues, we provide a retry mechanism that resends failed messages at various intervals until your listener receives them. A repeated webhook may be sent within 12 hours after the previous one. The maximum number of retries is 12.
Note:
Although connection problems may indeed result in lost, delayed, or duplicate webhooks, the most common cause is faulty logic on the listener side.
Sign Requests
Digital signatures enable secure data transmission. To generate the signature, (1) concatenate the request’s JSON body with your project’s secret key and (2) apply SHA-1 hashing to the resulting string.
Make sure that the created signature matches the one passed in the HTTP header.
Copy
http
- http
- curl
Request
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
"notification_type":
"user_validation",
"user":
{
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": 1234567,
"name": "Xsolla User",
"country": "US"
}
}'Response Codes
Xsolla API accepts conventional HTTP response codes for successful and failed requests. Code 204 indicates successful processing. Return code 400 in case of an error in the provided information (e.g., a required parameter missing, a failed recharge, etc.). Use code 500 for temporary errors with your servers.Webhooks List
The type of notification is sent in the notification_type parameter.| Notification Type | Description |
|---|---|
| user_validation | Check if a user exists in the game. |
| user_search | Get user info based on Public User ID. |
| payment | Sent when a user completes a payment. |
| refund | Sent when a payment must be canceled for any reason. |
| afs_reject | Sent when a transaction is declined during an AFS check. |
| afs_black_list | Sent when the AFS blocklist is updated. |
| create_subscription | Sent when a user creates a subscription. |
| update_subscription | Sent when a subscription is renewed or changed. |
| cancel_subscription | Sent when a subscription is canceled. |
| non_renewal_subscription | Sent when status is set to nonrenewing. |
| get_pincode | Sent when Xsolla API needs to obtain the game keys. |
| user_balance_operation | Sent when a user balance changes (the type of operation is sent in operation_type). |
| redeem_key | Sent when a user activates a key. |
| upgrade_refund | Sent when the upgrade is cancelled. |
| payment_account_add | Sent when a user adds or saves payment account. |
| payment_account_remove | Sent when a user removes the payment account from saved accounts. |
User Validation
Sent to verify that a user exists in the game.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.ip | string | User IP. |
user.phone | string | User phone. |
user.email | string | User email. |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.country | string | User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'user_validation',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email'=> 'email@example.com',
'id'=> '1234567',
'country' => 'US'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type": "user_validation",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type":"user_validation",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isUserValidation()) {
$userArray = $message->getUser();
$userId = $message->getUserId();
$messageArray = $message->toArray();
//TODO if user not found, you should throw InvalidUserException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentUser Search
Sent to retrieve user details using their Public User ID — a parameter that uniquely identifies the user and is known to them (email, screen name, etc). It allows the user to make purchases outside the game store (e.g., via cash kiosks).| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). Required. |
user.public_id | string | Public user ID. |
user.id | string | User ID. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'user_search',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'user' => array(
'public_id' => 'public_email@example.com'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type": "user_search",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"public_id": "public_email@example.com"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type": "user_search",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"public_id": "public_email@example.com"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
$callback = function (Message $message) {
if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
$userArray = $message->getUser();
$userPublicId = $message->getUserPublicId();
// TODO get a user from your database and fill the user data to model.
$user = new \Xsolla\SDK\Webhook\User();
$user->setId('user_id')
->setPublicId($userPublicId)
->setEmail('user_email') //Optional field
->setPhone('user_phone') //Optional field
->setName('user_name'); //Optional field
//TODO if user not found, you should throw InvalidUserException
return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json
{
"user": {
"public_id": "public_email@example.com",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User"
}
}{
"user": {
"public_id": "public_email@example.com",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User"
}
}Payment
Sent whenever a user completes a payment. Includes payment details.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
purchase | object | Purchase details (object). |
purchase.virtual_currency | object | Virtual currency to purchase (object). |
purchase.virtual_currency.name | string | Virtual currency name. |
purchase.virtual_currency.sku | string | Virtual currency package SKU (if set for the virtual currency package). |
purchase.virtual_currency.quantity | float | Quantity. |
purchase.virtual_currency.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_currency.amount | float | Price in real currency. |
purchase.checkout | object | Checkout details (object). |
purchase.checkout.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.checkout.amount | float | Purchase amount. |
purchase.subscription | object | Subscription details (object). |
purchase.subscription.plan_id | string | Plan ID (external if the plan was created via API). |
purchase.subscription.subscription_id | integer | Subscription ID in Xsolla database. |
purchase.subscription.product_id | string | Product ID (if sent in the access token). |
purchase.subscription.tags | array | Plan tags. |
purchase.subscription.date_create | string | Subscription creation date. Date and time per ISO 8601. |
purchase.subscription.date_next_charge | string | Next billing date. Date and time per ISO 8601. |
purchase.subscription.currency | string | Subscription currency. Three-letter currency code per ISO 4217. |
purchase.subscription.amount | float | Price in real currency. |
purchase.virtual_items | object | Virtual items in purchase (object). |
purchase.virtual_items.items | array | Item data (array). |
purchase.virtual_items.items.sku | string | Item ID. |
purchase.virtual_items.items.amount | integer | Item quantity. |
purchase.virtual_items.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_items.amount | float | Purchase amount. |
purchase.pin_codes | object | Game keys (array). |
purchase.pin_codes.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.drm | string | DRM platform used to distribute the game. Can be steam, playstation, xbox, uplay, origin, drmfree, gog, epicgames, nintendo_eshop, discord_game_store, or oculus. Make sure that you have configured the required DRM platforms in your Publisher Account. |
purchase.pin_codes.currency | string | Currency that the game keys is purchased for. Three-letter currency code per ISO 4217. |
purchase.pin_codes.amount | float | Price. |
purchase.pin_codes.upgrade | object | Object with upgrade data. |
purchase.pin_codes.upgrade.digital_content_from | object | Object with data on the package, from which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_from.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_from.DRM | string | Game DRM platform. |
purchase.pin_codes.upgrade.digital_content_to | object | Object with data on the package, to which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_to.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_to.DRM | string | Game DRM platform. |
purchase.pin_codes.upgrade.currency | string | Purchase currency. Three-letter currency code per ISO 4217. |
purchase.pin_codes.upgrade.amount | float | Price in real currency. |
purchase.gift | object | Gift details (object). |
purchase.gift.giver_id | string | Giver ID. |
purchase.gift.receiver_id | string | Gift recipient ID. |
purchase.gift.receiver_email | string | Gift recipient email. |
purchase.gift.message | string | Message from the giver. |
purchase.gift.hide_giver_from_receiver | string | Whether to hide the giver identity from the recipient. |
purchase.total | object | Total price of purchase (object). Required. |
purchase.total.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.total.amount | float | Total payment amount. |
purchase.promotions | array | Promotions applied to this transaction (array). |
purchase.promotions.technical_name | string | Technical name of the promotion. |
purchase.promotions.id | integer | Promotion ID. |
purchase.coupon | object | Coupon details (object; if a coupon was used when creating the subscription). |
purchase.coupon.coupon_code | string | Coupon code. |
purchase.coupon.campaign_code | string | Campaign code. |
user | object | User details (object). |
user.ip | string | User IP. |
user.phone | string | User phone. |
user.email | string | User email. |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.country | string | User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.zip | string | User’s ZIP or postal code. |
transaction | object | Transaction details (object). Required. |
transaction.id | integer | Transaction ID. |
transaction.external_id | string | Transaction external ID. |
transaction.payment_date | string | Date of payment. |
transaction.payment_method | integer | Payment method identifier. |
transaction.payment_method_order_id | string | Payment ID in the payment system. |
transaction.dry_run | integer | Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real. |
transaction.agreement | integer | Agreement ID. |
payment_details | object | Payment details (object). Required. |
payment_details.payment | object | Amount paid by the user (object). |
payment_details.payment.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment.amount | string | Amount. |
payment_details.payment_method_sum | object | Amount debited from the payment system. |
payment_details.payment_method_sum.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_sum.amount | string | Amount. |
payment_details.xsolla_balance_sum | object | Amount debited from Xsolla balance. |
payment_details.xsolla_balance_sum.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_balance_sum.amount | string | Amount. |
payment_details.payout | object | Payout details (object). |
payment_details.payout.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payout.amount | float | Amount. |
payment_details.vat | object | VAT details (object; EU only). |
payment_details.vat.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.vat.amount | float | Amount. |
payment_details.payout_currency_rate | float | Exchange rate between payment and payout currencies. |
payment_details.xsolla_fee | object | Xsolla fee (object). |
payment_details.xsolla_fee.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_fee.amount | float | Amount. |
payment_details.payment_method_fee | object | Payment system fee. |
payment_details.payment_method_fee.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_fee.amount | float | Amount. |
payment_details.sales_tax | object | Sales tax (object; USA and Canada only). |
payment_details.sales_tax.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.sales_tax.amount | float | Amount. |
payment_details.direct_wht | object | Direct withholding tax. |
payment_details.direct_wht.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.direct_wht.amount | float | Amount. |
payment_details.repatriation_commission | object | Object with data on repatriation costs, imposed on Xsolla by third parties. |
payment_details.repatriation_commission.currency | string | Repatriation costs currency. Three-letter currency code per ISO 4217. |
payment_details.repatriation_commission.amount | float | Repatriation costs amount. |
custom_parameters | object | Your custom parameters. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'payment',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'purchase' => array(
'virtual_currency' => array(
'name' => 'Coins',
'quantity' => 100,
'currency' => 'USD',
'amount' => 9.99
),
'total' => array(
'currency' => 'USD',
'amount' => 9.99
)
),
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email' => 'email@example.com',
'id' => '1234567',
'country' => 'US'
),
'transaction' => array(
'id' => 87654321,
'payment_date' => '2014-09-23T19:25:25+04:00',
'payment_method' => 1380,
'payment_method_order_id' => 1234567890123456789,
'dry_run' => 1
),
'payment_details' => array(
'payment' => array(
'currency' => 'USD',
'amount' => 9.99
),
'vat' => array(
'currency' => 'USD',
'amount' => 0
),
'sales_tax' => array(
'currency' => 'USD',
'amount' => 0
),
'direct_wht' => array(
'currency' => 'USD',
'amount' => 70
),
'payout_currency_rate' => 1,
'payout' => array(
'currency' => 'USD',
'amount' => 9.49
),
'xsolla_fee' => array(
'currency' => 'USD',
'amount' => 0.19
),
'payment_method_fee' => array(
'currency' => 'USD',
'amount' => 0.31
),
'repatriation_commission' => array(
'currency' => 'USD',
'amount' => 0.2
)
)
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1721
Authorization: Signature 34553d151e656110c656696c919f9a10e05de542
{
"notification_type": "payment",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"purchase":{
"virtual_currency": {
"name": "Coins",
"sku": "test_package1",
"quantity": 10,
"currency": "USD",
"amount": 100
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_next_charge": "2014-10-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout": {
"currency": "USD",
"amount": 50
},
"virtual_items": {
"items": [
{
"sku": "test_item1",
"amount": 1
}
],
"currency": "USD",
"amount": 50
},
"total": {
"currency": "USD",
"amount": 200
},
"promotions": [{
"technical_name": "Demo Promotion",
"id": "853"
}],
"coupon": {
"coupon_code": "ICvj45S4FUOyy",
"campaign_code": "1507"
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction": {
"id": 1,
"external_id": 1,
"payment_date": "2014-09-24T20:38:16+04:00",
"payment_method": 1,
"payment_method_order_id": 1234567890123456789,
"dry_run": 1,
"agreement": 1
},
"payment_details": {
"payment": {
"currency": "USD",
"amount": 230
},
"vat": {
"currency": "USD",
"amount": 0
},
"sales_tax": {
"currency": "USD",
"amount": 0
},
"direct_wht": {
"currency": "USD",
"amount": 0.70
},
"payout_currency_rate": 1,
"payout": {
"currency": "USD",
"amount": 200
},
"xsolla_fee": {
"currency": "USD",
"amount": 10
},
"payment_method_fee": {
"currency": "USD",
"amount": 20
},
"repatriation_commission": {
"currency": "USD",
"amount": "10"
}
},
"custom_parameters": {
"parameter1": "value1",
"parameter2": "value2"
}
}$curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type": "payment",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"purchase": {
"virtual_currency": {
"name": "Coins",
"sku": "test_package1",
"quantity": 10,
"currency": "USD",
"amount": 100
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_next_charge": "2014-10-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout": {
"currency": "USD",
"amount": 50
},
"virtual_items": {
"items": [
{
"sku": "test_item1",
"amount": 1
}
],
"currency": "USD",
"amount": 50
},
"total": {
"currency": "USD",
"amount": 200
},
"promotions": [{
"technical_name": "Demo Promotion",
"id": "853"
}],
"coupon": {
"coupon_code": "ICvj45S4FUOyy",
"campaign_code": "1507"
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction": {
"id": 1,
"external_id": 1,
"payment_date": "2014-09-24T20:38:16+04:00",
"payment_method": 1,
"payment_method_order_id": 1234567890123456789,
"dry_run": 1,
"agreement": 1
},
"payment_details": {
"payment": {
"currency": "USD",
"amount": 230
},
"vat": {
"currency": "USD",
"amount": 0
},
"sales_tax": {
"currency": "USD",
"amount": 0
},
"direct_wht": {
"currency": "USD",
"amount": 0.70
},
"payout_currency_rate": 1,
"payout": {
"currency": "USD",
"amount": 200
},
"xsolla_fee": {
"currency": "USD",
"amount": 10
},
"payment_method_fee": {
"currency": "USD",
"amount": 20
},
"repatriation_commission": {
"currency": "USD",
"amount": "10"
}
},
"custom_parameters": {
"parameter1": "value1",
"parameter2": "value2"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isPayment()) {
$userArray = $message->getUser();
$paymentArray = $message->getTransaction();
$paymentId = $message->getPaymentId();
$externalPaymentId = $message->getExternalPaymentId();
$paymentDetailsArray = $message->getPaymentDetails();
$customParametersArray = $message->getCustomParameters();
$isDryRun = $message->isDryRun();
$messageArray = $message->toArray();
// TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentRefund
Sent whenever a payment is canceled. Includes payment details. Learn more about a refund process in the recipe.
| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
purchase | object | Purchase details (object). |
purchase.virtual_currency | object | Virtual currency to purchase (object). |
purchase.virtual_currency.name | string | Virtual currency name. |
purchase.virtual_currency.quantity | float | Quantity. |
purchase.virtual_currency.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_currency.amount | float | Price in real currency. |
purchase.checkout | object | Checkout details (object). |
purchase.checkout.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.checkout.amount | float | Purchase amount. |
purchase.subscription | object | Subscription details (object). |
purchase.subscription.plan_id | string | Plan ID (external if the plan was created via API). |
purchase.subscription.tags | array | Plan tags. |
purchase.subscription.subscription_id | integer | Subscription ID in Xsolla database. |
purchase.subscription.date_create | string | Subscription creation date. Date and time per ISO 8601. |
purchase.subscription.currency | string | Subscription currency. Three-letter currency code per ISO 4217. |
purchase.subscription.amount | float | Price in real currency. |
purchase.virtual_items | object | Virtual items in purchase (object). |
purchase.virtual_items.items | array | Item data (array). |
purchase.virtual_items.items.sku | string | Item ID. |
purchase.virtual_items.items.amount | integer | Item quantity. |
purchase.virtual_items.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.virtual_items.amount | float | Purchase amount. |
purchase.pin_codes | object | Game keys (object). |
purchase.pin_codes.upgrade | object | Object with upgrade data. |
purchase.pin_codes.upgrade.digital_content_from | object | Object with data on the package, from which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_from.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_from.DRM | string | Game DRM platform. |
purchase.pin_codes.upgrade.digital_content_to | object | Object with data on the package, to which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_to.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_to.DRM | string | Game DRM platform. |
purchase.pin_codes.upgrade.currency | string | Purchase currency. Three-letter currency code per ISO 4217. |
purchase.pin_codes.upgrade.amount | float | Price in real currency. |
purchase.total | object | Total price of purchase (object). |
purchase.total.currency | string | Currency of the purchase. Three-letter currency code per ISO 4217. |
purchase.total.amount | float | Total payment amount. |
user | object | User details (object). |
user.ip | string | User IP. |
user.phone | string | User phone. |
user.email | string | User email. |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.country | string | User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.zip | string | User’s ZIP or postal code. |
transaction | object | Transaction details (object). Required. |
transaction.id | integer | Transaction ID. |
transaction.external_id | string | Transaction external ID. |
transaction.dry_run | integer | Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real. |
transaction.agreement | integer | Agreement ID. |
refund_details | object | Refund details (object). |
refund_details.code | integer | Code ID. |
refund_details.reason | string | Refund reason. |
refund_details.author | string | Refund initiator. |
payment_details | object | Payment details (object). Required. |
payment_details.payment | object | Amount paid by the user (object). |
payment_details.payment.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment.amount | string | Amount. |
payment_details.payment_method_sum | object | Amount debited from the payment system. |
payment_details.payment_method_sum.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_sum.amount | string | Amount. |
payment_details.xsolla_balance_sum | object | Amount debited from Xsolla balance. |
payment_details.xsolla_balance_sum.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_balance_sum.amount | string | Amount. |
payment_details.payout | object | Payout details (object). |
payment_details.payout.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payout.amount | float | Amount. |
payment_details.vat | object | VAT details (object; EU only). |
payment_details.vat.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.vat.amount | float | Amount. |
payment_details.payout_currency_rate | float | Exchange rate between payment and payout currencies. |
payment_details.xsolla_fee | object | Xsolla fee (object). |
payment_details.xsolla_fee.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.xsolla_fee.amount | float | Amount. |
payment_details.payment_method_fee | object | Payment system fee. |
payment_details.payment_method_fee.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.payment_method_fee.amount | float | Amount. |
payment_details.sales_tax | object | Sales tax (object; USA and Canada only). |
payment_details.sales_tax.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.sales_tax.amount | float | Amount. |
payment_details.direct_wht | object | Direct withholding tax. |
payment_details.direct_wht.currency | string | Currency. Three-letter currency code per ISO 4217. |
payment_details.direct_wht.amount | float | Amount. |
payment_details.repatriation_commission | object | Object with data on repatriation costs, imposed on Xsolla by third parties. |
payment_details.repatriation_commission.currency | string | Repatriation costs currency. Three-letter currency code per ISO 4217. |
payment_details.repatriation_commission.amount | float | Repatriation costs amount. |
custom_parameters | object | Your custom parameters. |
Refund codes:
| Code | Reason | Description |
|---|---|---|
| 1. | Cancellation by the user request / the game request. | Cancellation initiated from Publisher Account. |
| 2. | Charge-back. | Transaction charge-back requested. |
| 3. | Integration Error. | Issues in integration between Xsolla and the game. Recommendation: Do not blacklist the user. |
| 4. | Fraud. | Fraud suspected. |
| 5. | Test Payment. | Test transaction followed by cancellation. Recommendation: Do not blacklist the user. |
| 6. | Expired Invoice. | Invoice overdue (used for postpaid model). |
| 7. | PS debt cancel. | Payout refused by payment system. Recommendation: Do not blacklist the user. |
| 8. | Cancellation by the PS request. | Cancellation requested by payment system. Recommendation: Do not blacklist the user. |
| 9. | Cancellation by the user request. | The user was not satisfied with the game or the purchase for any reason. Recommendation: Do not blacklist the user. |
| 10. | Cancellation by the game request. | Cancellation requested by the game. Recommendation: Do not blacklist the user. |
| 11. | Account holder called to report fraud. | The account owner states that they didn’t make the transaction. |
| 12. | Friendly fraud. | Friendly fraud reported. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'refund',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'purchase' => array(
'virtual_currency' => array(
'name' => 'Coins',
'quantity' => 100,
'currency' => 'USD',
'amount' => 9.99
),
'total' => array(
'currency' => 'USD',
'amount' => 9.99
)
),
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email' => 'email@example.com',
'id' => '1234567',
'country' => 'US'
),
'transaction' => array(
'id' => 87654321,
'payment_date' => '2014-09-23T19:25:25+04:00',
'payment_method' => 1380,
'dry_run' => 1
),
'refund_details' => array(
'code' => 1,
'reason' => 'Fraud'
),
'payment_details' => array(
'payment' => array(
'currency' => 'USD',
'amount' => 9.99
),
'vat' => array(
'currency' => 'USD',
'amount' => 0
),
'sales_tax' => array(
'currency' => 'USD',
'amount' => 0
),
'direct_wht' => array(
'currency' => 'USD',
'amount' => 70
),
'payout_currency_rate' => 1,
'payout' => array(
'currency' => 'USD',
'amount' => 9.49
),
'xsolla_fee' => array(
'currency' => 'USD',
'amount' => 0.19
),
'payment_method_fee' => array(
'currency' => 'USD',
'amount' => 0.31
),
'repatriation_commission' => array(
'currency' => 'USD',
'amount' => 0.2
)
)
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
{
"notification_type": "refund",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"purchase": {
"virtual_currency": {
"name": "Coins",
"quantity": 10,
"currency": "USD",
"amount": 100
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"date_create": "2014-09-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout": {
"currency": "USD",
"amount": 50
},
"virtual_items": {
"items": [
{
"sku": "test_item1",
"amount": 1
}
],
"currency": "USD",
"amount": 50
},
"total": {
"currency": "USD",
"amount": 200
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction": {
"id": 1,
"external_id": 1,
"dry_run": 1,
"agreement": 1
},
"refund_details": {
"code": 1,
"reason": "Fraud"
},
"payment_details": {
"sales_tax": {
"currency": "USD",
"amount": 0
},
"direct_wht": {
"currency": "USD",
"amount": 0.70
},
"xsolla_fee": {
"currency": "USD",
"amount": "10"
},
"payout": {
"currency": "USD",
"amount": "200"
},
"payment_method_fee": {
"currency": "USD",
"amount": "20"
},
"payment": {
"currency": "USD",
"amount": "230"
},
"repatriation_commission": {
"currency": "USD",
"amount": "10"
}
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type": "refund",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"purchase": {
"virtual_currency": {
"name": "Coins",
"quantity": 10,
"currency": "USD",
"amount": 100
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"date_create": "2014-09-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"checkout": {
"currency": "USD",
"amount": 50
},
"virtual_items": {
"items": [
{
"sku": "test_item1",
"amount": 1
}
],
"currency": "USD",
"amount": 50
},
"total":{
"currency": "USD",
"amount": 200
}
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "email@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction": {
"id": 1,
"external_id": 1,
"dry_run": 1,
"agreement": 1
},
"refund_details": {
"code": 1,
"reason": "Fraud"
},
"payment_details": {
"sales_tax": {
"currency": "USD",
"amount": 0
},
"direct_wht": {
"currency": "USD",
"amount": 0.70
},
"xsolla_fee": {
"currency": "USD",
"amount": "10"
},
"payout": {
"currency": "USD",
"amount": "200"
},
"payment_method_fee": {
"currency": "USD",
"amount": "20"
},
"payment": {
"currency": "USD",
"amount": "230"
},
"repatriation_commission": {
"currency": "USD",
"amount": "10"
}
}
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isRefund()) {
$userArray = $message->getUser();
$paymentArray = $message->getTransaction();
$paymentId = $message->getPaymentId();
$externalPaymentId = $message->getExternalPaymentId();
$paymentDetailsArray = $message->getPaymentDetails();
$customParametersArray = $message->getCustomParameters();
$isDryRun = $message->isDryRun();
$refundArray = $message->getRefundDetails();
$messageArray = $message->toArray();
// TODO if you cannot handle the refund, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentUpgrade Refund
When a user refunds the payment associated with the upgrade, Xsolla sends the data on all cancelled upgrades and the current game package to the webhook URL.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Notification type. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
purchase | object | Object with the purchase data. Required. |
purchase.pin_codes | object | Object with data on the purchased game packages. |
purchase.pin_codes.purchase_type | string | Purchase type. Can be regular (purchasing the package) or upgrade (upgrading the package). |
purchase.pin_codes.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.DRM | string | Game DRM platform. |
purchase.pin_codes.currency | string | Purchase currency. Three-letter currency code per ISO 4217. |
purchase.pin_codes.amount | float | Price in real currency. |
purchase.pin_codes.transaction | object | Object with the transaction data. |
purchase.pin_codes.transaction.id | integer | Transaction ID. |
purchase.pin_codes.upgrade | object | Object with the upgrade data. |
purchase.pin_codes.upgrade.digital_content_from | object | Object with data on the package, from which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_from.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_from.DRM | string | Game DRM platform. |
purchase.pin_codes.upgrade.digital_content_to | object | Object with data on the package, to which the user upgraded. |
purchase.pin_codes.upgrade.digital_content_to.digital_content | string | Game SKU set in Publisher Account. |
purchase.pin_codes.upgrade.digital_content_to.DRM | string | Game DRM platform. |
ownership | object | Object with data on packages owned by the user. Required. |
ownership.digital_content | string | Game SKU set in Publisher Account. |
ownership.DRM | string | Game DRM platform. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array (
'notification_type' => 'upgrade_refund',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'purchase' =>
array (
'pin_codes' =>
array (
0 =>
array (
'purchase_type' => 'regular',
'digital_content' => 'silver',
'DRM' => 'drmfree',
'currency' => 'USD',
'amount' => 40,
'transaction' =>
array (
'id' => '361697569',
),
),
1 =>
array (
'purchase_type' => 'upgrade',
'upgrade' =>
array (
'digital_content_from' =>
array (
'digital_content' => 'silver',
'DRM' => 'drmfree',
),
'digital_content_to' =>
array (
'digital_content' => 'gold',
'DRM' => 'drmfree',
),
),
'currency' => 'USD',
'amount' => 20,
'transaction' =>
array (
'id' => '361697570'
),
),
2 =>
array (
'purchase_type' => 'upgrade',
'upgrade' =>
array (
'digital_content_from' =>
array (
'digital_content' => 'gold',
'DRM' => 'drmfree',
),
'digital_content_to' =>
array (
'digital_content' => 'platinum',
'DRM' => 'drmfree',
),
),
'currency' => 'USD',
'amount' => 20,
'transaction' =>
array (
'id' => '361697571'
),
),
),
),
'ownership' =>
array (
'digital_content' => NULL,
'DRM' => NULL,
),
)
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Authorization: Signature <signature>
{
"notification_type": "upgrade_refund",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"purchase": {
"pin_codes": [
{
"purchase_type": "regular",
"digital_content": "silver",
"DRM": "drmfree",
"currency": "USD",
"amount": "40",
"transaction": {
"id": "361697569"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "silver",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "gold",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697570"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "gold",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "platinum",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697571"
}
}
]
},
"ownership": {
"digital_content": null,
"DRM": null
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type": "upgrade_refund",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"purchase": {
"pin_codes": [
{
"purchase_type": "regular",
"digital_content": "silver",
"DRM": "drmfree",
"currency": "USD",
"amount": "40",
"transaction": {
"id": "361697569"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "silver",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "gold",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697570"
}
},
{
"purchase_type": "upgrade",
"upgrade": {
"digital_content_from": {
"digital_content": "gold",
"DRM": "drmfree"
},
"digital_content_to": {
"digital_content": "platinum",
"DRM": "drmfree"
}
},
"currency": "USD",
"amount": "20",
"transaction": {
"id": "361697571"
}
}
]
},
"ownership": {
"digital_content": null,
"DRM": null
}
}'Response
AFS Rejected Transaction
When a transaction is declined during an AFS check, Xsolla sends transaction details to the URL webhook. To enable this notification, contact the Account Manager.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.ip | string | User IP. |
user.phone | string | User phone. |
user.email | string | User email. |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.country | string | User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.zip | string | User’s ZIP or postal code. |
transaction | object | Transaction details (object). Required. |
transaction.id | integer | Transaction ID. |
transaction.external_id | string | Transaction external ID. |
transaction.dry_run | integer | Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real. |
transaction.agreement | integer | Agreement ID. |
refund_details | object | Refund details (object). |
refund_details.code | integer | Code ID. |
refund_details.reason | string | Refund reason. |
refund_details.author | string | Refund initiator. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'afs_reject',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'user' => array(
'ip' => '127.0.0.1',
'phone' => '18777976552',
'email' => 'email@example.com',
'id' => '1234567',
'country' => 'US'
),
'transaction' => array(
'id' => 87654321,
'payment_date' => '2014-09-23T19:25:25+04:00',
'payment_method' => 1380,
'dry_run' => 1
),
'refund_details' => array(
'code' => 4,
'reason' => 'Potential fraud'
)
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
{
"notification_type": "afs_reject",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "semail@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction": {
"id": 1,
"external_id": 1,
"dry_run": 1,
"agreement": 1
},
"refund_details": {
"code": 4,
"reason": "Potential fraud"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
"notification_type": "afs_reject",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"ip": "127.0.0.1",
"phone": "18777976552",
"email": "semail@example.com",
"id": "1234567",
"name": "Xsolla User",
"country": "US"
},
"transaction": {
"id": 1,
"external_id": 1,
"dry_run": 1,
"agreement": 1
},
"refund_details": {
"code": 4,
"reason": "Potential fraud"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message->isRefund()) {
$userArray = $message->getUser();
$paymentArray = $message->getTransaction();
$paymentId = $message->getPaymentId();
$externalPaymentId = $message->getExternalPaymentId();
$customParametersArray = $message->getCustomParameters();
$isDryRun = $message->isDryRun();
$refundArray = $message->getRefundDetails();
$messageArray = $message->toArray();
// TODO if you cannot handle the refund, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentAFS Updated Blocklist
When the AFS blocklist is updated (add or remove a parameter), Xsolla sends the notification to the webhook URL. The parameter addition is performed automatically on the Xsolla side or on request. Parameter removing is possible only on request. To enable this notification, contact the Account Manager.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
event | object | Object with information about AFS blocklist event. Required. |
event.action | string | Type of event. Possible values: adding, removing. |
event.reason | string | Cause of event. Possible values:
|
event.parameter | string | Name of parameter by which event occurred. Possible values: nick — user’s nickname, email — user’s email address, ps_account — user’s billing account, ip_address — user’s IP address, card_issuer — user’s credit card issuing bank, phone — user’s phone number. |
event.parameter_value | string | Value of parameter by which event occurred. |
event.date_of_last_action | string | Time of the latest AFS blocklist event in the ISO 8601 format. |
event.transaction_id | string | Transaction ID associated with the parameter by which the event occurred. |
Copy
http
- http
- curl
Request
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 233
Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6
{
"event": {
"action": "adding",
"date_of_last_action": "2020-11-27T10:09:05+03:00",
"parameter": "email",
"parameter_value": "some_cool_email@gmail.com",
"reason": "ps_reported_fraud",
"transaction_id": "111111111"
},
"notification_type": "afs_black_list"
}$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \
-d '{
"event": {
"action": "adding",
"date_of_last_action": "2020-11-27T10:09:05+03:00",
"parameter": "email",
"parameter_value": "some_cool_email@gmail.com",
"reason": "ps_reported_fraud",
"transaction_id": "111111111"
},
"notification_type": "afs_black_list"
}'Response
HTTP/1.1 204 No ContentCreated Subscription
When a user creates a subscription, we send a notification to your payment notification script.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
subscription | object | Subscription details (object). |
subscription.plan_id | string | Plan ID (external if the plan was created via API). |
subscription.tags | array | Plan tags. |
subscription.subscription_id | integer | Subscription ID in Xsolla database. |
subscription.product_id | string | Product ID (if sent in the access token). |
subscription.date_create | string | Subscription creation date. Date and time per ISO 8601. |
subscription.date_next_charge | string | Next billing date. Date and time per ISO 8601. |
subscription.trial | object | Trial period (object). |
subscription.trial.value | integer | Trial period. |
subscription.trial.type | string | Trial period type: day. |
custom_parameters | object | Your custom parameters. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'create_subscription',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'user' => array(
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => array(
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_next_charge' => '2015-01-22T19:25:25+04:00',
'trial' => array(
'value' => 90,
'type' => 'day'
)
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type": "create_subscription",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"id": "1234567",
"name": "Xsolla User"
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_next_charge": "2015-01-22T19:25:25+04:00",
"trial": {
"value": 90,
"type": "day"
}
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type": "create_subscription",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"id": "1234567",
"name": "Xsolla User"
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_next_charge": "2015-01-22T19:25:25+04:00",
"trial": {
"value": 90,
"type": "day"
}
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof CreateSubscriptionMessage) {
$messageArray = $message->toArray();
// TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentUpdated Subscription
If some parameters in subscription (plan_id, date_next_charge) were changed and in case of every subscription renewal, we send the notification update_subscription on your webhook URL.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
subscription | object | Subscription details (object). |
subscription.plan_id | string | Plan ID (external if the plan was created via API). |
subscription.tags | array | Plan tags. |
subscription.subscription_id | integer | Subscription ID in Xsolla database. |
subscription.product_id | string | Product ID (if sent in the access token). |
subscription.date_next_charge | string | Next billing date. Date and time per ISO 8601. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'update_subscription',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'user' => array(
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => array(
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_next_charge' => '2015-01-22T19:25:25+04:00'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type": "update_subscription",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"id": "1234567",
"name": "Xsolla User"
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_next_charge": "2015-01-22T19:25:25+04:00"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type": "update_subscription",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"id": "1234567",
"name": "Xsolla User"
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_next_charge": "2015-01-22T19:25:25+04:00"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UpdateSubscriptionMessage) {
$messageArray = $message->toArray();
// TODO if the subscription renewing fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentCanceled Subscription
When a subscription is canceled for any reason, we send a notification to your payment notification script.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
subscription | object | Subscription details (object). |
subscription.plan_id | string | Plan ID (external if the plan was created via API). |
subscription.tags | array | Plan tags. |
subscription.subscription_id | integer | Subscription ID in Xsolla database. |
subscription.product_id | string | Product ID (if sent in the access token). |
subscription.date_create | string | Subscription creation date. Date and time per ISO 8601. |
subscription.date_end | string | Subscription termination date. Date and time per ISO 8601. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'cancel_subscription',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'user' => array(
'id' => '1234567',
'name' => 'Xsolla User'
),
'subscription' => array(
'plan_id' => 'b5dac9c8',
'subscription_id' => '10',
'product_id' => 'Demo Product',
'date_create' => '2014-09-22T19:25:25+04:00',
'date_end' => '2015-01-22T19:25:25+04:00',
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type": "cancel_subscription",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user":{
"id": "1234567",
"name": "Xsolla User"
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_end": "2015-01-22T19:25:25+04:00"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type": "cancel_subscription",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"id": "1234567",
"name": "Xsolla User"
},
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"product_id": "Demo Product",
"date_create": "2014-09-22T19:25:25+04:00",
"date_end": "2015-01-22T19:25:25+04:00"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof CancelSubscriptionMessage) {
$messageArray = $message->toArray();
// TODO if the subscription canceling fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentNonrenewing Subscription
When a subscription status is set to nonrenewing for any reason, we send the notification non_renewal_subscription to your webhook URL. To enable this notification, contact your Account Manager.| Parameter | Type | Description |
|---|---|---|
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. Required. |
settings.merchant_id | integer | Merchant ID. |
notification_type | string | Type of notification. Required. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.email | string | User email. |
subscription | object | Subscription details (object). |
subscription.subscription_id | integer | Subscription ID in Xsolla database. |
subscription.plan_id | string | Plan ID (external if the plan was created via API). |
subscription.date_create | string | Subscription creation date. Date and time per ISO 8601. |
subscription.date_next_charge | string | Next billing date. This is the date when a next payment was expected before user subscription was set to non-renew. Date and time per ISO 8601. |
subscription.currency | string | Subscription currency. Three-letter currency code per ISO 4217. |
subscription.amount | float | Price in real currency. |
Get Game Keys
We will be making API calls to your server to obtain game activation codes after each successful payment.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
pin_code | object | Game keys details (object). |
pin_code.digital_content | string | Game SKU. |
pin_code.DRM | string | DRM platform used to distribute the game. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array (
'notification_type' => 'get_pincode',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'user' =>
array (
'id' => '1234567',
'name' => 'Xsolla User',
),
'pin_code' =>
array (
'digital_content' => 'Game SKU',
'DRM' => 'Steam',
),
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"notification_type": "get_pincode",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"id": "1234567",
"name": "Xsolla User"
},
"pin_code": {
"digital_content": "Game SKU",
"DRM": "Steam"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type": "get_pincode",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"id": "1234567",
"name": "Xsolla User"
},
"pin_code": {
"digital_content": "Game SKU",
"DRM": "Steam"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof GetPinCodeMessage) {
$userArray = $message->getUser();
$drmSku = $message->getDRM();
$digitalContentSku = $message->getDigitalContent();
// TODO get a pin code from your database or generate a new one. Put the pin code into variable $newPinCode
$newPinCode = 'NEW_PIN_CODE';
// TODO if the pin code creation or generation fail for some reason, you should throw XsollaWebhookException
return new \Xsolla\SDK\Webhook\Response\PinCodeResponse($newPinCode);
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json
{
"pin_code": "PIN_CODE"
}Activate key
When a user activates a key, Xsolla sends a notification to your webhook URL.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Notification type. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
key | string | Activation key. |
sku | string | Unique key package ID. |
user_id | string | User ID. |
activation_date | datetime | Key activation date in the YYYYMMDDHHMMSS format per ISO 8601. |
user_country | string | User country. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used. |
restriction | object | Object with regional restriction cluster settings. The cluster includes a restriction type and a list of countries, servers and locales for which the game is available. |
restriction.sku | string | Unique cluster ID. |
restriction.name | string | Cluster name. |
restriction.types | array | Array of restriction types. |
restriction.countries | array | Array of countries in the cluster. |
restriction.servers | array | Array of game servers. |
restriction.locales | array | Array of locales. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'notification_type' => 'redeem_key',
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'key' => ‘wqdqwwddq9099022’,
'sku' => 123,
'user_id' => ‘sample_user’,
'activation_date' => ‘2018-11-20T08:38:51+03:00’,
'user_country' => ‘EN’,
'restriction' =>
array(
'name' => ‘cls_1’,
'types' =>
array(
‘activation’
),
'countries' =>
array(
‘RU’
),
),
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
"notification_type": "redeem_key",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"key": "wqdqwwddq9099022",
"sku": "123",
"user_id": "sample_user",
"activation_date": "2018-11-20T08:38:51+03:00",
"user_country": "EN",
"restriction": {
"name": "cls_1",
"types": [
"activation"
],
"countries": [
"RU"
]
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"notification_type": "redeem_key",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"key": "wqdqwwddq9099022",
"sku": "123",
"user_id": "sample_user",
"activation_date": "2018-11-20T08:38:51+03:00",
"user_country": "EN",
"restriction": {
"name": "cls_1",
"types": [
"activation"
],
"countries": [
"RU"
]
}
}'Response
<?php
$response = null;
HTTP/1.1 204 No ContentGet Friends
The API should be implemented on the partner’s side. The maximum number of friends is 2000. See the recipe.
HTTP REQUEST
Copy
- http
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:
|
Copy
http
- http
- curl
Request
GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1 HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7$ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
-X GET \
-u merchant_id:merchant_api_keyResponse
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"friends": [
{
"id": "1",
"name": "doctor",
"email": "doctor@hospital.com",
"image_url": "https://partner/link/doctor.jpg"
},
{
"id": "2",
"name": "cook",
"email": "cook@kitchen.com",
"image_url": "https://partner/link/cook.jpg"
},
{
"id": "3",
"name": "teacher",
"email": "teacher@school.com"
},
{
"id": "4",
"name": "god",
"email": "god@heaven.com",
"image_url": "https://partner/link/god.jpg"
}
],
"total": 10
}
][
{
"friends": [
{
"id": "1",
"name": "John Carter",
"email": "carter@xsolla.com",
"image_url": "https://partner/link/doctor.jpg"
},
{
"id": "2",
"name": "John Smith",
"email": "smith@xsolla.com",
"image_url": "https://partner/link/cook.jpg"
}
],
"total": 10
}
]User Balance: Payment
Sent whenever a user makes a payment.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
operation_type | string | Type of operation. |
id_operation | integer | Operation ID in Xsolla database. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.email | string | User email. |
virtual_currency_balance | object | User balance data (object). |
virtual_currency_balance.old_value | string | Balance before transaction. |
virtual_currency_balance.new_value | string | Balance after transaction. |
virtual_currency_balance.diff | string | Quantity of virtual currency in the purchase. |
transaction | object | Transaction details (object). Required. |
transaction.id | integer | Transaction ID. |
transaction.date | string | Date of transaction. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '200',
'diff' => '200'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'transaction' => array(
'id' => '123456789',
'date' => '2015-05-19T15:54:40+03:00'
),
'operation_type' => 'payment',
'notification_type' => 'user_balance_operation',
'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "200",
"diff": "200"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"transaction": {
"id": "123456789",
"date": "2015-05-19T15:54:40+03:00"
},
"operation_type": "payment",
"notification_type": "user_balance_operation",
"id_operation": "66989"
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "200",
"diff": "200"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"transaction": {
"id": "123456789",
"date": "2015-05-19T15:54:40+03:00"
},
"operation_type": "payment",
"notification_type": "user_balance_operation",
"id_operation": "66989"
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentUser Balance: Purchase
Sent when a user purchases something inside the game. Specifies the change in the user’s balance.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
operation_type | string | Type of operation. |
id_operation | integer | Operation ID in Xsolla database. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.email | string | User email. |
virtual_currency_balance | object | User balance data (object). |
virtual_currency_balance.old_value | string | Balance before transaction. |
virtual_currency_balance.new_value | string | Balance after transaction. |
virtual_currency_balance.diff | string | Quantity of virtual currency in the purchase. |
items_operation_type | string | Type of operation made with virtual items. |
items | array | Virtual items within the purchase (array of objects). |
items.sku | string | Item ID. |
items.amount | integer | Item quantity. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '200',
'diff' => '200'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'operation_type' => 'inGamePurchase',
'notification_type' => 'user_balance_operation',
'items_operation_type' => 'add',
'items' => array(
'sku' => '1468',
'amount' => '2'
),
'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "200",
"diff": "200"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"operation_type": "inGamePurchase",
"notification_type": "user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation": "66989"
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "200",
"diff": "200"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"operation_type": "inGamePurchase",
"notification_type": "user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation": "66989"
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentUser Balance: Redeem Coupon
Sent when a user redeems a coupon to receive virtual items or virtual currency.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
operation_type | string | Type of operation. |
id_operation | integer | Operation ID in Xsolla database. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.email | string | User email. |
virtual_currency_balance | object | User balance data (object). |
virtual_currency_balance.old_value | string | Balance before transaction. |
virtual_currency_balance.new_value | string | Balance after transaction. |
virtual_currency_balance.diff | string | Quantity of virtual currency in the purchase. |
items_operation_type | string | Type of operation made with virtual items. |
items | array | Virtual items within the purchase (array of objects). |
items.sku | string | Item ID. |
items.amount | integer | Item quantity. |
coupon | object | Coupon details (object). |
coupon.coupon_code | string | Coupon code. |
coupon.campaign_code | string | Campaign code. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '0',
'diff' => '0'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'operation_type' => 'coupon',
'notification_type' => 'user_balance_operation',
'items_operation_type' => 'add',
'items' => array(
'sku' => '1468',
'amount' => '2'
),
'id_operation' => '66989',
'coupon' => array(
'coupon_code' => 'test123',
'campaign_code' => 'Xsolla Campaign'
)
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "0",
"diff": "0"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"operation_type": "coupon",
"notification_type": "user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation": "66989",
"coupon": {
"coupon_code": "test123",
"campaign_code": "Xsolla Campaign"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "0",
"diff": "0"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"operation_type": "coupon",
"notification_type": "user_balance_operation",
"items_operation_type": "add",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation": "66989",
"coupon": {
"coupon_code": "test123",
"campaign_code": "Xsolla Campaign"
}
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentUser Balance: Manual Update
Sent when a user’s balance is changed manually.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
operation_type | string | Type of operation. |
id_operation | integer | Operation ID in Xsolla database. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.email | string | User email. |
virtual_currency_balance | object | User balance data (object). |
virtual_currency_balance.old_value | string | Balance before transaction. |
virtual_currency_balance.new_value | string | Balance after transaction. |
virtual_currency_balance.diff | string | Quantity of virtual currency in the purchase. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '100',
'diff' => '100'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'operation_type' => 'internal',
'notification_type' => 'user_balance_operation',
'id_operation' => '67002'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "100",
"diff": "100"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"operation_type": "internal",
"notification_type": "user_balance_operation",
"id_operation": "67002"
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "100",
"diff": "100"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"operation_type": "internal",
"notification_type": "user_balance_operation",
"id_operation": "67002"
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentUser Balance: Refund
Sent when a user cancels a payment. Specifies the change in the user’s balance.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
operation_type | string | Type of operation. |
id_operation | integer | Operation ID in Xsolla database. |
user | object | User details (object). |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.email | string | User email. |
virtual_currency_balance | object | User balance data (object). |
virtual_currency_balance.old_value | string | Balance before transaction. |
virtual_currency_balance.new_value | string | Balance after transaction. |
virtual_currency_balance.diff | string | Quantity of virtual currency in the purchase. |
transaction | object | Transaction details (object). Required. |
transaction.id | integer | Transaction ID. |
transaction.date | string | Date of transaction. |
items_operation_type | string | Type of operation made with virtual items. |
items | array | Virtual items within the purchase (array of objects). |
items.sku | string | Item ID. |
items.amount | integer | Item quantity. |
Copy
php
- php
- http
- curl
Request
<?php
$request = array(
'settings' => array(
'project_id' => 18404,
'merchant_id' => 2340
),
'virtual_currency_balance' => array(
'old_value' => '0',
'new_value' => '0',
'diff' => '0'
),
'user' => array(
'name' => 'Xsolla User',
'id' => '1234567',
'email' => 'email@example.com'
),
'transaction' => array(
'id' => '123456789',
'date' => '2015-05-19T15:54:40+03:00'
),
'operation_type' => 'cancellation',
'notification_type' => 'user_balance_operation',
'items_operation_type' => 'remove',
'items' => array(
'sku' => '1468',
'amount' => '2'
),
'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "0",
"diff": "0"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"transaction": {
"id": "123456789",
"date": "2015-05-19T15:54:40+03:00"
},
"operation_type": "cancellation",
"notification_type": "user_balance_operation",
"items_operation_type": "remove",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation": "66989"
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"virtual_currency_balance": {
"old_value": "0",
"new_value": "0",
"diff": "0"
},
"user": {
"name": "Xsolla User",
"id": "1234567",
"email": "email@example.com"
},
"transaction": {
"id": "123456789",
"date": "2015-05-19T15:54:40+03:00"
},
"operation_type": "cancellation",
"notification_type": "user_balance_operation",
"items_operation_type": "remove",
"items": [{
"sku": "1468",
"amount": "2"
}],
"id_operation": "66989"
}'Response
<?php
use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
$callback = function (Message $message) {
if ($message instanceof UserBalanceMessage) {
$messageArray = $message->toArray();
// TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
}
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No ContentAdd Payment Account
Sent whenever a user adds a payment account manually or saves payment account when purchasing something inside the game. To enable this notification, contact the Account Manager.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.ip | string | User IP. |
user.email | string | User email. |
user.id | string | User ID. Required. |
user.name | string | Username. |
user.country | string | User’s country. Two-letter uppercase country code per ISO 3166-1 alpha-2. |
user.zip | string | User’s ZIP or postal code. |
payment_account | object | Payment account details (object). |
payment_account.id | string | Payment account ID. Required. |
payment_account.name | string | The payment account name in the payment system (e.g., payment card number, email). |
payment_account.payment_method | integer | Payment method ID. |
payment_account.type | string | Type of payment account (e.g., card, PayPal). |
Copy
http
- http
- curl
Request
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Length: 255
Content-Type: application/json
Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843
{
"notification_type": "payment_account_add",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"ip": "127.0.0.1",
"email": "email@example.com",
"id": "1234567",
"name": "John Smith",
"country": "RU",
"zip": "12345"
},
"payment_account": {
"id": "12345678",
"name": "email@example.com",
"payment_method": "24",
"type": "paypal"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
"notification_type":"payment_account_add",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"ip": "127.0.0.1",
"email": "email@example.com",
"id": "1234567",
"name": "John Smith",
"country": "RU",
"zip": "12345"
},
"payment_account": {
"id": "12345678",
"name": "email@example.com",
"payment_method": "24",
"type": "paypal"
}
}'Response
HTTP/1.1 204 No ContentRemove Payment Account
Sent whenever a user removes the payment account from saved accounts. To enable this notification, please contact the Account Manager.| Parameter | Type | Description |
|---|---|---|
notification_type | string | Type of notification. Required. |
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account. |
settings.merchant_id | integer | Merchant ID. |
user | object | User details (object). |
user.email | string | User email. |
user.id | string | User ID. Required. |
user.name | string | Username. |
payment_account | object | Payment account details (object). |
payment_account.id | string | Payment account ID. Required. |
payment_account.name | string | The payment account name in the payment system (e.g., payment card number, email). |
payment_account.payment_method | integer | Payment method ID. |
payment_account.type | string | Type of payment account (e.g., card, PayPal). |
Copy
http
- http
- curl
Request
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Length: 258
Content-Type: application/json
Authorization: Signature d90d319f05df7b0f86d2485f48e7079f0f752523
{
"notification_type": "payment_account_remove",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"email": "email@example.com",
"id": "1234567",
"name": "John Smith"
},
"payment_account": {
"id": "12345678",
"name": "email@example.com",
"payment_method": "24",
"type": "paypal"
}
}$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
"notification_type": "payment_account_remove",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"user": {
"email": "email@example.com",
"id": "1234567",
"name": "John Smith"
},
"payment_account": {
"id": "12345678",
"name": "email@example.com",
"payment_method": "24",
"type": "paypal"
}
}'Response
HTTP/1.1 204 No ContentWebhooks 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. |
Copy
- http
HTTP/1.1 400 Bad Request
{
"error":{
"code":"INVALID_USER",
"message":"Invalid user"
}
}Was this article helpful?
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.Rate this page
Rate this page
Don’t want to answer
Thank you for your feedback!
Found a typo or other text error? Select the text and press Ctrl+Enter.
