С чего начать

Введение

API Иксоллы включает в себя:

  • In-Game Store API — методы для работы с Внутриигровым магазином;
  • Pay Station API — платежный интерфейс и методы токенизации;
  • Subscription API — методы для подписок;
  • Store API — методы для работы с модулями Виртуальная валюта, Виртуальные предметы, Игровые ключи, акции, купоны;
  • Publisher Account API — управление проектами и пользователями Личного кабинета, методы для работы с отчетами, тикетами поддержки;
  • Login API — методы аутентификации пользователей через собственный интерфейс (см. руководство по интеграции).

API Иксоллы использует REST-архитектуру. В API мы используем HTTP коды ответов для обозначения ошибок и URL, аналогичных структуре каталогов. Ответы API (включая ошибки) возвращаются в виде JSON.

Мы используем встроенные особенности HTTP, такие как HTTP аутентификация и HTTP методы, которые понимаются всеми HTTP клиентами, также мы поддерживаем CORS (Cross-origin resource sharing) для обеспечения безопасной работы с API вашего клиентского приложения.

API Иксоллы работает со следующими базовыми URL:

  • https://api.xsolla.com — Pay Station API, Store API, Publisher Account API
  • https://login.xsolla.com/api — Login API
Многие ресурсы включают в себя параметр merchant_id, который указывает, что приложение работает именно от вашего имени.

Запрос и ответ

Запросы к API Иксоллы должны:

  • отправляться по протоколу HTTPS;
  • использовать TLS версии 1.2 и выше;
  • содержать параметры аутентификации;
  • содержать дополнительный заголовок Content-Type: application/json для запросов типа PUT и POST.

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

По умолчанию все запросы возвращают ответ в виде JSON с заголовком Content-Type: application/json.

Изменения API

Иксолла может изменять функциональные возможности API:

  • Добавлять новые ресурсы API;
  • Добавлять необязательные параметры запроса;
  • Добавлять новые свойства к существующим ответам API;
  • Добавлять новые значения для параметров, имеющих перечисление возможных значений;
  • Добавлять новые типы вебхуков и новые параметры в JSON;
  • Добавлять необязательные заголовки в HTTP-запросы;
  • Отклонять любой запрос, если его параметры принимают недопустимые значения;
  • Ошибочно сформированные запросы могут быть приняты из-за избыточно мягкого анализа синтаксиса. В будущем, если проверка будет более строгой, подобные запросы могут быть отклонены;
  • Добавлять, изменять или удалять незадокументированные функциональные возможности в любое время.

Ваш клиент должен продолжать работать независимо от этих изменений. К примеру, новые параметры JSON, которые не распознаются вашим клиентом, не должны мешать его работе.

Версионирование

Все разделы API Иксоллы поддерживают версионирование. Мы будем выпускать новую версию всякий раз, когда будут появляться несовместимые с текущей версией изменения. Версия обозначается идентификатором ("v1"/"v2" и т. п.), который указывается в URL после префикса "/merchant".

Если вы начинаете работу с API, используйте самую последнюю версию. Если вы не указали версию команды, то по умолчанию будет вызвана первая версия.

Info: Целостность работы API гарантируется в рамках одной версии.

Аутентификация

API Иксоллы использует базовую HTTP-аутентификацию. Все запросы к API должны содержать заголовок Authorization: Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара merchant_id:api_key, закодированная по стандарту Base64.

Значения параметров merchant_id и api_key вы можете найти в Личном кабинете Иксолла:

  • merchant_id: Настройки компании > Компания > ID продавца
  • api_key: Настройки компании > Ключ API

Notice:
  • Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
  • Изменения ключа API может остановить платежи во все ваши проекты. Вызовы API, которые используют старый ключ, перестанут работать до тех пор, пока вы не обновите их с помощью нового ключа.
Copy
Full screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Пример
GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request GET \
--url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'
<?php

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

xhr.send(data);

Команды управления ресурсами

Все команды API указывают на тип данных, который должен быть обработан, и на действие, которое требуется совершить с этими данными. Стандартный список действий:

ДействиеHTTP-методОписание
СозданиеPOSTСоздает и сохраняет сущность соответствующего типа.
СписокGETВозвращает список сущностей, удовлетворяющих запросу.
ПолучениеGETВозвращает данные по конкретному идентификатору, которые вы присылаете в запросе.
ЗаменаPUTЗаменяет все поля для сущности, переданной в запросе.
ИзменениеPATCHИзменяет только указанные поля существующего объекта, который соответствует идентификатору из запроса
УдалениеDELETEУдаляет существующий объект, который соответствует идентификатору из запроса.

Формат даты

Все представления дат передаются в строках согласно ISO 8601. Вы можете либо передавать дату в UTC (например, 2013-01-15T00:00:00Z), либо смещение от UTC для обозначения часового пояса (например, 2013-01-15T00:00:00-08:00 8 часов от UTC).

Постраничная навигация

Результат запроса должен выводиться постранично. Это означает, что вместо вывода всех результатов выполнения запроса выводится только часть. Для этого необходимо использовать параметры limit и offset.

Типы ошибок

Список поддерживаемых HTTP ответов:

  • 200, 201, 204 — Успешный ответ.
  • 400 Bad Request — Отсутствует обязательный параметр. Полное описание можно найти в теле ответа.
  • 401 Unauthorized — Недействительный ключ API.
  • 402 Request Failed — Параметры верны, но запрос не прошел.
  • 403 Forbidden — Нет прав доступа. Полное описание можно найти в теле ответа.
  • 404 Not Found — Соответствующего ресурса нет по данному URI.
  • 409, 422 — Параметры не верны.
  • 412 Precondition Failed — Ошибка происходит, когда проект не активирован (используется в методе получения токена).
  • 415 Unsupported Media Type — Content-Type: application/json HTTP заголовок не был отправлен.
  • 500, 502, 503, 504 Server Errors — что-то пошло не так.

Иксолла использует стандартные HTTP коды для обозначения успешных или неуспешных запросов. В общем случае код в 2xx диапазоне обозначает успех, код диапазона 4хх означает ошибку в результате передачи некорректных параметров (например, обязательный параметр не передан, или авторизация не прошла и т.д.), код 5хх диапазона означает серверную ошибку.

Не все ошибки в точности соответствуют HTTP кодам. Например, если запрос был верным, но не смог завершиться успешно, мы вернем 422 ошибку.

В случае ошибочного ответа мы возвращаем JSON объект со следующими полями:

{< T "api_table_name" >}}ТипОписание
http_status_codeintegerHTTP код.
messagestringПонятное сообщение с описанием ошибки. Текст всегда на английском языке. Вы не должны использовать это поле в случае какой-либо ошибки, так как значение может измениться в будущем.
extended_messagestringРасширенное описание ошибки.
request_idstringУникальный ID запроса, используется, чтобы помочь нам диагностировать проблему.
{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

Токен

Для обеспечения безопасности проведения платежа API Иксоллы использует токен, который содержит внутри себя платежные параметры, вместо прямого получения данных через HTTP GET запрос на страницу оплаты. Перед открытием страницы оплаты вы должны получить новый токен. Время жизни токена — 24 часа.

Получение токена

HTTP-ЗАПРОС

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

Можно создать токен с любыми параметрами пользователя. Вы отправляете нам эти параметры при получении токена, а мы отправляем их вам после успешной оплаты. Токен может содержать только описанные ниже параметры, либо параметры, предопределенные партнером.

ПараметрТипОписание
user
objectОбъект с информацией о пользователе.
user.id
objectОбъект с данными об ID пользователя. Обязательный.
user.id.value
stringID пользователя.
user.name
objectОбъект с информацией о нике пользователя.
user.name.value
stringНик пользователя.
user.email
objectEmail пользователя (объект). Параметр user.email используется при построении моделей антифрода и проведения платежей. Его передача является обязательным требованием Иксоллы и платежных систем. Отсутствие этого параметра может влиять на конверсию платежей. Обязательный.
user.email.value
stringEmail пользователя. Должен быть валидным в соответствии с протоколом RFC 822. Обязательный.
user.phone
objectОбъект с информацией о телефоне пользователя.
user.phone.value
stringНомер телефона пользователя.
user.country
objectОбъект с информацией о стране пользователя.
user.country.value
stringИспользуется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
user.country.allow_modify
booleanМожет ли пользователь изменить страну на странице оплаты. 'false' по умолчанию.
user.attributes
objectОбъект с данными об атрибутах пользователя, необходимых для фильтрации списка предметов. Параметры передаются в json хэше парами ключ-значение.
user.steam_id
objectОбъект с данными о Steam ID пользователя.
user.steam_id.value
stringSteam ID пользователя.
user.tracking_id
objectОбъект с данными о Tracking ID пользователя.
user.tracking_id.value
stringУникальный Tracking ID (используется для проведения рекламных кампаний).
user.public_id.value
stringПараметр позволяет однозначно идентифицировать пользователя, а также, в отличие от user ID, известен пользователю (адрес электронной почты, никнейм, и т.д.). Параметр может использоваться при оплате покупки вне игрового магазина (например, кнопка игры в терминалах оплаты).
user.utm
objectОбъект с данными о характеристиках трафика.
user.utm.utm_source
stringИсточник трафика
user.utm.utm_medium
stringКанал трафика (контекстная реклама, медийная реклама, email-рассылка).
user.utm.utm_campaign
stringНазвание кампании. В данный параметр следует указывать транслитерированное или переведенное на английский язык название кампании.
user.utm.utm_term
stringКлючевое слово кампании. При использовании этого параметра в статистике будут собираться данные по тем ключевым словам, которые используются для таргетинга вашей рекламной кампании (а не по поисковым запросам). В Google Analytics содержимое метки utm_term попадает в единый отчет с поисковыми запросами.
user.utm.utm_content
stringСодержание кампании.
booleanЯвляется ли пользователь юридическим лицом.
objectОбъект с реквизитами юридического лица. Объект и все его параметры являются обязательными, если в user.is_legal передано значение ‘true’.
stringПолное юридическое наименование.
stringПолный юридический адрес.
stringИндивидуальный идентификатор налогоплательщика.
stringСтрана регистрации. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
settings
objectОбъект, содержащий настройки проекта.
settings.external_id
stringВнешний ID транзакции.
settings.project_id
integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете. Обязательный.
settings.language
stringЯзык интерфейса. Используется двухбуквенное обозначение (в нижнем регистре) согласно стандарту ISO 639-1.
settings.return_url
stringПользователь будет перенаправлен на данную страницу после совершения платежа. Параметры 'user_id', 'foreigninvoice', 'invoice_id' и 'status' будут автоматически добавлены к ссылке.
settings.currency
stringПредпочтительная валюта платежа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
settings.mode
stringПередайте значение 'sandbox', чтобы провести тестовые платежи. Обратите внимание, что URL для страницы оплаты будет https://sandbox-secure.xsolla.com.
settings.payment_method
integerID способа оплаты.
settings.payment_widget
stringВиджет оплаты. Принимает значения 'paybycash' или 'giftcard'. При передаче этого параметра пользователь перенаправляется на виджет Pay with Cash или Gift Cards.
settings.ui
objectОбъект с настройками интерфейса.
settings.ui.theme
stringВнешний вид интерфейса оплаты. Может принимать значения 'default' (по умолчанию) или 'default_dark'.
settings.ui.size
stringРазмер платежного интерфейса. В зависимости от требуемых размеров платежного интерфейса, параметр может принимать следующие значения:
  • small: Наименьший размер платежного интерфейса. Используется в случаях, когда размеры окна строго ограничены (размер: 620 x 630)
  • medium: Рекомендуемый размер платежного интерфейса. Оптимален при открытии в lightbox (размер: 740 x 760)
  • large: желательно открывать в новом окне/вкладке (размер: 820 x 840)
settings.ui.version
stringТип устройства. Может принимать значения 'desktop' (по умолчанию) или 'mobile'.
settings.ui.desktop
objectОбъект с данными настроек для desktop-версии.
settings.ui.desktop.header
objectОбъект с настройками header.
settings.ui.desktop.header.is_visible
booleanДолжен ли header отображаться на странице оплаты.
booleanЕсли значение 'true', то логотип будет отображаться в header (необходимо сначала прислать файл с логотипом вашему менеджеру).
settings.ui.desktop.header.visible_name
booleanДолжно ли название игры отображаться в header.
settings.ui.desktop.header.visible_purchase
booleanДолжно ли описание покупки (purchase.description.value) отображаться в header, по умолчанию ‘true’.
settings.ui.desktop.header.type
stringВнешний вид header. Может принимать значения 'compact' (название игры и ID пользователя не будут показываться в header) или 'normal'.
settings.ui.desktop.header.close_button
booleanПоказывать ли кнопку Закрыть в настольной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре "settings.return_url". 'false' по умолчанию.
settings.ui.desktop.subscription_list
objectОбъект с данными настройки списка подписок.
settings.ui.desktop.subscription_list.layout
stringШаблон списка. Принимает значения 'list' (по умолчанию) или 'grid'.
settings.ui.desktop.subscription_list.description
stringЗдесь вы можете передать текст про подписки. Текст появится перед списком рекуррентных планов в интерфейсе оплаты.
settings.ui.desktop.subscription_list.display_local_price
booleanЕсли значение 'true' и если локальная валюта пользователя отличается от базовой валюты плана, пользователь будет видеть две цены: цену в локальной валюте и цену в базовой валюте плана.
settings.ui.desktop.virtual_item_list
objectОбъект с данными настройки списка предметов.
settings.ui.desktop.virtual_item_list.layout
stringШаблон списка. Принимает значения 'list' (по умолчанию) или 'grid'.
settings.ui.desktop.virtual_item_list.button_with_price
booleanЕсли значение 'true', то цена за предмет будет показана внутри кнопки. Если 'false', то цена будет слева от кнопки. 'false' по умолчанию.
settings.ui.desktop.virtual_item_list.view
stringВывод списка групп виртуальных предметов либо в виде вертикального меню, либо над окном в виде горизонтального меню. Принимает значения 'horizontal_navigation' или 'vertical' (по умолчанию).
settings.ui.desktop.virtual_currency_list
objectОбъект с данными настройки списка пакетов виртуальной валюты.
settings.ui.desktop.virtual_currency_list.description
stringЗдесь вы можете передать текст про виртуальную валюту. Текст появится перед списком пакетов виртуальной валюты в интерфейсе оплаты.
settings.ui.desktop.virtual_currency_list.button_with_price
booleanЕсли значение 'true', то цена за предмет будет показана внутри кнопки. Если 'false', то цена будет слева от кнопки. 'false' по умолчанию.
settings.ui.header.visible_virtual_currency_balance
booleanДолжен ли этот элемент быть видимым в интерфейсе оплаты. 'true' по умолчанию.
settings.ui.mobile.mode
stringПользователь может совершить платеж только через сохраненные способы оплаты. Принимает значение 'saved_accounts'.
settings.ui.mobile.header.close_button
booleanПоказывать ли кнопку Закрыть в мобильной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре "settings.return_url". 'false' по умолчанию.
booleanСкрывать или нет footer в мобильной версии платежного интерфейса.
settings.ui.license_url
stringСсылка на лицензионное соглашение.
settings.ui.components
objectОбъект с данными настройки пунктов меню.
settings.ui.components.virtual_items
objectОбъект с данными настройки меню предметов.
settings.ui.components.virtual_items.order
integerМесто вкладки в меню.
settings.ui.components.virtual_items.hidden
booleanДолжна ли вкладка отображаться в меню.
settings.ui.components.virtual_items.selected_group
stringГруппа, которая будет выбрана при открытии вкладки.
settings.ui.components.virtual_items.selected_item
stringПредмет, который будет выбран при открытии вкладки. Должен быть передан артикул предмета.
settings.ui.components.virtual_currency
objectОбъект с данными настройки меню виртуальной валюты.
settings.ui.components.virtual_currency.custom_amount
booleanВозможность ввода произвольного количества виртуальной валюты в интерфейсе оплаты.
settings.ui.components.virtual_currency.order
integerМесто вкладки в меню.
settings.ui.components.virtual_currency.hidden
booleanДолжна ли вкладка отображаться в меню.
settings.ui.components.subscriptions
objectОбъект с данными настройки меню подписок.
settings.ui.components.subscriptions.order
integerМесто вкладки в меню.
settings.ui.components.subscriptions.hidden
booleanДолжна ли вкладка отображаться в меню.
settings.ui.mode
stringПлатежный интерфейс в режиме Личного кабинета. Принимает значение 'user_account'. Header содержит только навигационное меню Личного кабинета; исключается возможность выбора предмета и оплата покупки; режим Личного кабинета доступен только в desktop-режиме.
settings.ui.user_account
objectОбъект с данными об аккаунте пользователя.
settings.ui.user_account.info
objectСтраница 'Мой аккаунт'.
settings.ui.user_account.info.order
integerМесто вкладки в меню.
settings.ui.user_account.info.enable
booleanДолжна ли вкладка отображаться в меню. 'false' по умолчанию.
settings.ui.user_account.history
objectСтраница 'История' пользователя.
settings.ui.user_account.history.order
integerМесто вкладки в меню.
settings.ui.user_account.history.enable
booleanДолжна ли вкладка отображаться в меню. 'false' по умолчанию.
settings.ui.user_account.payment_accounts
objectСтраница 'Мои платежные аккаунты'.
settings.ui.user_account.payment_accounts.order
integerМесто вкладки в меню.
settings.ui.user_account.payment_accounts.enable
booleanДолжна ли вкладка отображаться в меню. 'false' по умолчанию.
settings.ui.user_account.subscriptions
objectСтраница 'Управление подписками'.
settings.ui.user_account.subscriptions.order
integerМесто вкладки в меню.
settings.ui.user_account.subscriptions.enable
booleanДолжна ли вкладка отображаться в меню. 'false' по умолчанию.
settings.shipping_enabled
booleanОтображение страницы ввода адреса заставки. 'false' по умолчанию.
purchase
objectОбъект с информацией о заказе.
purchase.virtual_currency
objectОбъект с данными о виртуальной валюте.
purchase.virtual_currency.quantity
floatКоличество виртуальной валюты в заказе.
purchase.virtual_currency.currency
stringВалюта пакета виртуальной валюты, на основе которой будут сделаны все расчеты.
purchase.virtual_items
objectОбъект с данными о предметах.
purchase.virtual_items.currency
stringВалюта предмета в заказе, на основе которой будут сделаны все расчеты.
purchase.virtual_items.items
arrayМассив с данными о предмете.
purchase.virtual_items.items.sku
stringID предмета (артикул).
purchase.virtual_items.items.amount
integerКоличество этого предмета в заказе.
purchase.virtual_items.available_groups
arrayМассив с данными о группах предметов. Только предметы из указанных групп будут показаны в интерфейсе оплаты.
purchase.subscription
objectОбъект с данными о подписке.
purchase.subscription.plan_id
stringID рекуррентного плана.
purchase.subscription.operation
stringТип операции, применяемой к плану подписки пользователя. Чтобы изменить план подписки, передайте в параметре значение ‘change_plan’. В параметре purchase.subscription.plan_id необходимо передать ID нового плана подписки.
purchase.subscription.product_id
stringID рекуррентного продукта.
purchase.subscription.currency
stringВалюта рекуррентного плана в заказе, на основе которой будут сделаны все расчеты.
purchase.subscription.available_plans
arrayМассив с данными о планах подписок. Только планы из этого списка будут показаны в платежном интерфейсе.
purchase.subscription.trial_days
integerКоличество дней триального периода.
purchase.pin_codes
objectОбъект с данными о ключе.
purchase.pin_codes.currency
stringВалюта ключа в заказе, на основе которой будут сделаны все расчеты.
purchase.pin_codes.codes
arrayМассив с данными о ключах.
purchase.pin_codes.codes.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.codes.drm
stringDRM-платформа, на которой игра будет доступна. Может принимать значения 'steam', 'playstation', 'xbox', 'uplay', 'origin', 'drmfree', 'gog', 'epicgames', 'nintendo_eshop', 'discord_game_store' или 'oculus'. Пожалуйста, убедитесь, что нужная DRM-платформа настроена в Личном кабинете. Если значение не передано в токене, будет выбрана платформа, указанная пользователем в платежном интерфейсе.
purchase.pin_codes.upgrade
objectОбъект с информацией об апгрейде.
purchase.pin_codes.upgrade.id_user_history
integerID записи, содержащей данные о пользователе и пакетах, которыми он владеет.
purchase.pin_codes.upgrade.id
integerID апгрейда.
purchase.checkout
objectОбъект с информацией о заказе.
purchase.checkout.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.checkout.amount
floatСумма заказа.
purchase.description
objectОбъект с описанием предмета.
purchase.description.value
stringОбщее описание покупки. Будет отображаться в интерфейсе оплаты и в email чеке. Если вы хотите передавать по отдельности каждый предмет, используйте параметры массива purchase.description.items.
purchase.description.items
array of objectsМассив предметов.
purchase.description.items.name
stringНаименование предмета.
purchase.description.items.image_url
stringСсылка на изображение предмета.
purchase.description.items.description
stringОписание предмета в покупке.
purchase.description.items.price
objectОбъект со стоимостью предмета.
purchase.description.items.price.amount
stringСтоимость предмета.
purchase.description.items.quantity
integerКоличество предметов в покупке.
purchase.description.items.is_bonus
booleanЯвляется ли товар бесплатным и предоставляемым в качестве бонуса. По умолчанию 'false'.
purchase.gift
objectОбъект с информацией о подарке.
purchase.gift.giver_id
stringID дарителя.
purchase.gift.message
stringСообщение от дарителя.
purchase.gift.hide_giver_from_receiver
stringПоказывать ли данные дарителя получателю подарка. 'true' по умолчанию.
purchase.gift.friends
arrayМассив с данными о друзьях.
purchase.gift.friends.id
stringID получателя подарка.
purchase.gift.friends.name
stringНикнейм получателя подарка.
purchase.gift.friends.email
stringEmail получателя подарка.
purchase.coupon_code
objectОбъект с информацией о промокоде на скидку или бонусы при покупке.
purchase.coupon_code.value
stringЗначение промокода.
purchase.coupon_code.hidden
booleanСкрыть поле для ввода промокода в интерфейсе оплаты. 'false' по умолчанию.
custom_parameters
objectВаши дополнительные параметры. Параметры передаются в json хеше парами ключ-значение.

Если какой-либо параметр был передан в некорректном формате, токен не может быть выдан. Мы вернем 422 HTTP код, в JSON объекте в теле ответа будет содержаться информация об ошибке. В параметре "extended_message" мы указываем, какие именно параметры были переданы неверно.

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

Copy
Full screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Запрос
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

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

Body:
  {
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "amount": 1,
          "sku": "SKU01"
        }
      ]
    }
  },
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 16184,
    "ui": {
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      },
      "desktop": {
        "virtual_item_list": {
          "button_with_price": true,
          "layout": "list"
        }
      },
      "size": "medium"
    }
  },
  "user": {
    "country": {
      "allow_modify": true,
      "value": "US"
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    }
  }
}
curl --request POST \
  --url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'
<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>',
  'content-type' => 'application/json'
));

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

echo $response->getBody();
var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import http.client

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

payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

headers = {
    'content-type': "application/json",
    'authorization': "Basic <your_authorization_basic_key>"
    }

conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, headers)

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

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

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

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

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

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

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();
var data = JSON.stringify({
  "user": {
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "country": {
      "value": "US",
      "allow_modify": true
    }
  },
  "settings": {
    "project_id": 16184,
    "currency": "USD",
    "language": "en",
    "ui": {
      "size": "medium",
      "desktop": {
        "virtual_item_list": {
          "layout": "list",
          "button_with_price": true
        }
      },
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      }
    }
  },
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "sku": "SKU01",
          "amount": 1
        }
      ]
    }
  }
});

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

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

xhr.open("POST", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);
Ответ
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

Список дополнительных параметров

Вы можете передавать в токене в объекте custom_parameters дополнительные параметры, которые могут использоваться для настройки антифрод-фильтров. Рекомендуемые параметры приведены в таблице ниже, при необходимости данный список можно расширить.

Посмотреть рецепт

ПараметрТипОписание
registration_date
stringДата регистрации аккаунта согласно стандарту ISO 8601.
total_hours
integerОбщее количество часов, проведенных в игре.
total_characters
integerКоличество персонажей игрока.
social_networks_added
booleanПодключил ли игрок профили в социальных сетях.
profile_image_added
booleanЗагрузил ли игрок изображение профиля.
active_date
stringДата последнего посещения согласно стандарту ISO 8601.
total_friends
integerКоличество друзей игрока.
additional_verification
booleanИспользует ли игрок дополнительные способы защиты аккаунта.
win_rate
integerРейтинг побед игрока.
last_change_password_date
stringДата последней смены пароля согласно стандарту ISO 8601.
chat_activity
booleanПишет ли игрок в чате.
forum_activity
booleanПишет ли игрок в форуме.
total_bans
integerКоличество банов игрока в чате/на форуме.
profile_completed
booleanДобавил ли игрок дополнительную информацию в профиль.
notifications_enabled
booleanПодписался ли игрок на рассылку уведомлений.
user_level
integerУровень игрока, репутация или ранг.
karma_points
integerКарма игрока.
total_sum
floatОбщая сумма платежей.
non_premium_currency
floatСумма непремиальной валюты игрока.
total_game_events
integerКоличество внутриигровых событий, в которых участвовал игрок.
total_gifts
integerКоличество подарков, отправленных или полученных игроком.
tutorial_completed
booleanЗавершил ли игрок обучение в игре.
completed_tasks
integerКоличество выполненных заданий.
items_used
booleanИспользует ли игрок купленные в игре предметы.
pvp_activity
booleanУчаствует ли игрок в PvP.
total_clans
integerКоличество кланов, в которых состоит игрок.
unlocked_achievements
integerКоличество разблокированных умений.
total_inventory_value
floatСуммарная стоимость инвентаря во внутриигровой валюте.
character_customized
booleanНастраивал ли игрок персонажа.
session_time
stringПериод времени, который пользователь проводит в игре, согласно стандарту ISO 8601.

Оповещения

Введение

Используйте webhook-и для оповещения о событиях, которые происходят с транзакцией в Иксолле. Вы можете использовать оповещения для автоматизации бэк-офиса и функций, таких как отображение статуса.

Webhook — это сервис для оповещения о событиях, таких как:

  • совершение платежей, включая покупку виртуальной валюты, покупку предметов, и других
  • рекуррентные платежи и действия с подписками
  • Chargeback/refund по транзакции

В большинстве случаев действие, которое вызывает webhook, является следствием действия пользователя на странице оплаты. Тем не менее и другие действия могут вызывать webhook.

Например, вы можете отменить платеж через API Иксоллы, либо платежная система может нас оповестить об оспариваемой операции.

Примеры действий в результате обработки webhook:

  • Пополнение баланса пользователя
  • Предоставление новых предметов пользователю
  • Начало предоставления подписки
  • Блокировка пользователя в случае подозрения в мошенничестве

Вы должны принимать оповещения со следующих IP адресов: 185.30.20.0/24, 185.30.21.0/24

Notice: В вашей базе данных не должно быть двух успешных транзакций с одинаковым ID. Если ваш обработчик оповещений получил оповещение с ID, который уже есть в вашей базе, вы должны вернуть результат предыдущей обработки данной транзакции. Пожалуйста, не зачисляйте пользователю покупку еще раз и не создавайте дублирующих записей в базе данных.

Мы не гарантируем, что ваш обработчик получит все оповещения. Поскольку интернет-соединение не является на 100% надежным, оповещения могут теряться или задерживаться. Ваш обработчик оповещений также может возвращать код статуса HTTP 5xx при временных проблемах на вашем сервере. Например, если пользователь совершил успешную покупку виртуального предмета, но она не была добавлена в инвентарь, обработчик вернет код статуса HTTP 500.

Для решения этой проблемы сервис оповещений Иксоллы включает в себя механизм повторных оповещений. Повторные оповещения отправляются в течение 12 часов с момента первой попытки, пока ваш обработчик не подтвердит получение. Максимальное количество попыток — 12.

Note: Хотя интернет-соединение является частой причиной проблем с оповещениями, наиболее вероятной причиной все же является проблема в логике обработчика оповещений.

Подпись запроса

Подпись обеспечивает безопасность передачи данных. Генерация подписи состоит из двух шагов. Первый шаг — конкатенация JSON из тела запроса и секретного ключа проекта. Второй шаг — применение SHA-1 криптографической хэш-функции к получившейся на первом шаге строке.

Вы должны проверить, что подпись, которую вы сформировали, совпадает с подписью, отправленной в HTTP заголовке.

Copy
Full screen
http
  • http
  • curl
Запрос
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"}}'

Ответ

Иксолла использует HTTP коды ответа для обозначения успешного или ошибочного запроса. Код 204 обозначает успешную обработку оповещения. В случае возникновения ошибки вы должны вернуть 400 код (например, отсутствует обязательный параметр, или пополнение баланса невозможно). Код 500 обозначает временную серверную ошибку.

Список типов оповещения

Тип оповещения передается в параметре 'notification_type'.

Тип оповещенияОписание
user_validationПроверка существования пользователя в игре.
user_searchПолучение информации о пользователе по параметру Public user ID.
paymentОповещение об успешном платеже.
refundОповещение об отмене платежа.
afs_rejectОповещение об отмене транзакциии AFS системой.
create_subscriptionОповещение о создании подписки.
update_subscriptionОповещение о продлении подписки или о смене каких-либо параметров внутри подписки.
cancel_subscriptionОповещение об отмене подписки.
non_renewal_subscriptionОповещение о смене статуса на непродлеваемый.
get_pincodeЗапрос на получение ключа.
user_balance_operationОповещение об изменении баланса пользователя (тип операции отправляется в оповещении operation_type).
redeem_keyОповещение об активации ключа.
upgrade_refundОповещение об отмене апгрейда.
inventory_getОтправка списка предметов из инвентаря игры на вторичный рынок.
inventory_pullОтправка предметов из инвентаря игры на вторичный рынок.
inventory_pushПолучение предметов в инвентарь игры со вторичного рынка.
payment_account_addОповещение о добавлении или сохранении платежного аккаунта.
payment_account_removeОповещение об удалении платежного аккаунта.

Проверка существования пользователя

Сервер Иксоллы отправляет запрос на webhook URL, чтобы удостовериться, что данный пользователь существует в игре.

ПараметрТипОписание
user
objectОбъект с информацией о пользователе.
user.ip
stringIP адрес пользователя.
user.phone
stringНомер телефона пользователя (в международном формате).
user.email
stringEmail пользователя.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.country
stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'user_validation',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
    "notification_type":"user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}'
Ответ
<?php

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

$callback = function (Message $message) {
    if ($message->isUserValidation()) {
       $userArray = $message->getUser();
       $userId = $message->getUserId();
       $messageArray = $message->toArray();
       //TODO if user not found, you should throw InvalidUserException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Public User ID — параметр, по которому можно однозначно идентифицировать пользователя и который хорошо известен пользователю в отличие от User ID (в качестве Public User ID может быть email, никнейм и т.д.). Этот webhook используется, когда есть возможность совершить оплату вне игры (например, при оплате на кнопку игры в терминале).

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе. Обязательный.
user.public_id
stringPublic ID пользователя.
user.id
stringID пользователя.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'user_search',
    'user' => array(
        'public_id' => 'public_email@example.com'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"user_search",
    "user": {
        "public_id": "public_email@example.com"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
    "notification_type":"user_search",
    "user": {
        "public_id": "public_email@example.com"
    }
}'
Ответ
<?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"
    }
}

Успешный платеж

Когда пользователь успешно совершает оплату, мы отправляем детали о платеже на webhook URL.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
purchase
objectОбъект с информацией о заказе.
purchase.virtual_currency
objectОбъект с данными о приобретенной виртуальной валюте.
purchase.virtual_currency.name
stringНазвание виртуальной валюты.
purchase.virtual_currency.sku
stringАртикул пакета виртуальной валюты (если задан для пакета виртуальной валюты).
purchase.virtual_currency.quantity
floatКоличество бонусного товара.
purchase.virtual_currency.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.virtual_currency.amount
floatСумма покупки.
purchase.checkout
objectОбъект с информацией о заказе.
purchase.checkout.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.checkout.amount
floatСумма заказа.
purchase.subscription
objectОбъект с данными о подписке.
purchase.subscription.plan_id
stringID плана (внешний id, если план был создан через API).
purchase.subscription.subscription_id
integerID подписки в базе данных Иксоллы.
purchase.subscription.product_id
stringID продукта (если был отправлен в токене).
purchase.subscription.tags
arrayТеги плана.
purchase.subscription.date_create
stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
purchase.subscription.date_next_charge
stringДата следующего списания. Дата и время согласно стандарту ISO 8601.
purchase.subscription.currency
stringВалюта рекуррентного плана. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.subscription.amount
floatСумма покупки.
purchase.virtual_items
objectОбъект с данными о предметах в покупке.
purchase.virtual_items.items
arrayМассив с данными о предмете.
purchase.virtual_items.items.sku
stringID предмета (артикул).
purchase.virtual_items.items.amount
integerКоличество этого предмета в заказе.
purchase.virtual_items.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.virtual_items.amount
floatСумма заказа.
purchase.pin_codes
objectМассив с данными о ключах.
purchase.pin_codes.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.drm
stringDRM-платформа, на которой игра будет доступна. Может принимать значения 'steam', 'playstation', 'xbox', 'uplay', 'origin', 'drmfree', 'gog', 'epicgames', 'nintendo_eshop', 'discord_game_store' или 'oculus'. Пожалуйста, убедитесь, что нужная DRM-платформа настроена в Личном кабинете.
purchase.pin_codes.currency
stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.pin_codes.amount
floatСтоимость ключа
purchase.pin_codes.upgrade
objectОбъект с информацией об апгрейде.
purchase.pin_codes.upgrade.digital_content_from
objectОбъект с информацией о пакете пользователя, с которого был произведен апгрейд.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringDRM-платформа игры.
purchase.pin_codes.upgrade.digital_content_to
objectОбъект с информацией о пакете, на который пользователь перешел в рамках апгрейда.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringDRM-платформа игры.
purchase.pin_codes.upgrade.currency
stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.pin_codes.upgrade.amount
floatСумма покупки.
purchase.gift
objectОбъект с информацией о подарке.
purchase.gift.giver_id
stringID дарителя.
purchase.gift.receiver_ID
stringID получателя подарка.
purchase.gift.receiver_email
stringEmail получателя подарка.
purchase.gift.message
stringСообщение от дарителя.
purchase.gift.hide_giver_from_receiver
stringФлаг, показывать ли дарителя получателю подарка.
purchase.total
objectОбъект с данными об общей стоимости покупки. Обязательный.
purchase.total.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.total.amount
floatОбщая сумма покупки.
purchase.promotions
arrayМассив с данными акций, которые действуют на данную покупку.
purchase.promotions.technical_name
stringТехническое название акции.
purchase.promotions.id
integerID акции.
purchase.coupon
objectОбъект с информацией о купоне (если при создании подписки был использован купон).
purchase.coupon.coupon_code
stringКод купона.
purchase.coupon.campaign_code
stringКод кампании купонов.
user
objectОбъект с информацией о пользователе.
user.ip
stringIP адрес пользователя.
user.phone
stringНомер телефона пользователя (в международном формате).
user.email
stringEmail пользователя.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.country
stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
user.zip
stringПочтовый индекс.
transaction
objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
transaction.id
integerID транзакции.
transaction.external_id
stringВнешний ID транзакции.
transaction.payment_date
stringДата платежа.
transaction.payment_method
integerID способа оплаты в системе Иксоллы.
transaction.payment_method_order_id
stringID платежа в платежной системе.
transaction.dry_run
integerПризнак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.
transaction.agreement
integerID соглашения.
payment_details
objectОбъект с финансовыми данными платежа. Обязательный.
payment_details.payment
objectОбъект с данными о сумме, которую оплатил пользователь.
payment_details.payment.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payment.amount
stringСумма.
payment_details.payment_method_sum
objectОбъект с данными о сумме, которая была оплачена из платежной системы.
payment_details.payment_method_sum.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payment_method_sum.amount
stringСумма.
payment_details.xsolla_balance_sum
objectОбъект с данными о сумме, которая была оплачена с Иксолла-баланса.
payment_details.xsolla_balance_sum.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.xsolla_balance_sum.amount
stringСумма.
payment_details.payout
objectОбъект с данными о сумме выплаты.
payment_details.payout.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payout.amount
floatСумма.
payment_details.vat
objectРазмер VAT (только для Евросоюза).
payment_details.vat.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.vat.amount
floatСумма.
payment_details.payout_currency_rate
floatКурс валюты платежа к валюте выплаты.
payment_details.xsolla_fee
objectРазмер комиссии Иксоллы.
payment_details.xsolla_fee.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.xsolla_fee.amount
floatСумма.
payment_details.payment_method_fee
objectРазмер комиссии платежной системы.
payment_details.payment_method_fee.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payment_method_fee.amount
floatСумма.
payment_details.sales_tax
objectРазмер налога (только для США).
payment_details.sales_tax.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.sales_tax.amount
floatСумма.
payment_details.repatriation_commission
objectОбъект с информацией о затратах на репатриацию, возлагаемых на Иксоллу третьими сторонами.
payment_details.repatriation_commission.currency
stringВалюта затрат на репатриацию. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.repatriation_commission.amount
floatСумма затрат на репатриацию.
custom_parameters
objectВаши дополнительные параметры.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'payment',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'payment_method_order_id' => 1234567890123456789,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1721
Authorization: Signature 34553d151e656110c656696c919f9a10e05de542

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

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

$callback = function (Message $message) {
    if ($message->isPayment()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $messageArray = $message->toArray();
        // TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Отмена платежа

При отмене платежа Иксолла присылает детали отмененной транзакции на webhook URL. Подробная информация о процессе возврата платежа приведена в рецепте.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
purchase
objectОбъект с информацией о заказе.
purchase.virtual_currency
objectОбъект с данными о приобретенной виртуальной валюте.
purchase.virtual_currency.name
stringНазвание виртуальной валюты.
purchase.virtual_currency.quantity
floatКоличество бонусного товара.
purchase.virtual_currency.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.virtual_currency.amount
floatСумма покупки.
purchase.checkout
objectОбъект с информацией о заказе.
purchase.checkout.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.checkout.amount
floatСумма заказа.
purchase.subscription
objectОбъект с данными о подписке.
purchase.subscription.plan_id
stringID плана (внешний id, если план был создан через API).
purchase.subscription.tags
arrayТеги плана.
purchase.subscription.subscription_id
integerID подписки в базе данных Иксоллы.
purchase.subscription.date_create
stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
purchase.subscription.currency
stringВалюта рекуррентного плана. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.subscription.amount
floatСумма покупки.
purchase.virtual_items
objectОбъект с данными о предметах в покупке.
purchase.virtual_items.items
arrayМассив с данными о предмете.
purchase.virtual_items.items.sku
stringID предмета (артикул).
purchase.virtual_items.items.amount
integerКоличество этого предмета в заказе.
purchase.virtual_items.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.virtual_items.amount
floatСумма заказа.
purchase.pin_codes
objectОбъект с данными о ключе.
purchase.pin_codes.upgrade
objectОбъект с информацией об апгрейде.
purchase.pin_codes.upgrade.digital_content_from
objectОбъект с информацией о пакете пользователя, с которого был произведен апгрейд.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringDRM-платформа игры.
purchase.pin_codes.upgrade.digital_content_to
objectОбъект с информацией о пакете, на который пользователь перешел в рамках апгрейда.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringDRM-платформа игры.
purchase.pin_codes.upgrade.currency
stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.pin_codes.upgrade.amount
floatСумма покупки.
purchase.total
objectОбъект с данными об общей стоимости покупки.
purchase.total.currency
stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.total.amount
floatОбщая сумма покупки.
user
objectОбъект с информацией о пользователе.
user.ip
stringIP адрес пользователя.
user.phone
stringНомер телефона пользователя (в международном формате).
user.email
stringEmail пользователя.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.country
stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
user.zip
stringПочтовый индекс.
transaction
objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
transaction.id
integerID транзакции.
transaction.external_id
stringВнешний ID транзакции.
transaction.dry_run
integerПризнак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.
transaction.agreement
integerID соглашения.
refund_details
objectОбъект с финансовыми данными рефанда.
refund_details.code
integerID кода.
refund_details.reason
stringПричина отмены.
refund_details.author
stringАвтор рефанда.
payment_details
objectОбъект с финансовыми данными платежа. Обязательный.
payment_details.payment
objectОбъект с данными о сумме, которую оплатил пользователь.
payment_details.payment.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payment.amount
stringСумма.
payment_details.payment_method_sum
objectОбъект с данными о сумме, которая была оплачена из платежной системы.
payment_details.payment_method_sum.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payment_method_sum.amount
stringСумма.
payment_details.xsolla_balance_sum
objectОбъект с данными о сумме, которая была оплачена с Иксолла-баланса.
payment_details.xsolla_balance_sum.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.xsolla_balance_sum.amount
stringСумма.
payment_details.payout
objectОбъект с данными о сумме выплаты.
payment_details.payout.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payout.amount
floatСумма.
payment_details.vat
objectРазмер VAT (только для Евросоюза).
payment_details.vat.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.vat.amount
floatСумма.
payment_details.payout_currency_rate
floatКурс валюты платежа к валюте выплаты.
payment_details.xsolla_fee
objectРазмер комиссии Иксоллы.
payment_details.xsolla_fee.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.xsolla_fee.amount
floatСумма.
payment_details.payment_method_fee
objectРазмер комиссии платежной системы.
payment_details.payment_method_fee.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.payment_method_fee.amount
floatСумма.
payment_details.sales_tax
objectРазмер налога (только для США).
payment_details.sales_tax.currency
stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.sales_tax.amount
floatСумма.
payment_details.repatriation_commission
objectОбъект с информацией о затратах на репатриацию, возлагаемых на Иксоллу третьими сторонами.
payment_details.repatriation_commission.currency
stringВалюта затрат на репатриацию. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
payment_details.repatriation_commission.amount
floatСумма затрат на репатриацию.
custom_parameters
objectВаши дополнительные параметры.

Коды отмены:

КодПричина отменыОписание
1.Cancellation by the user request / the game request.Используется, если отмена произошла из Личного кабинета.
2.Chargeback.Используется, если по транзакции был chargeback.
3.Integration Error.Используется в случае проблем с интеграцией между Иксоллой и игрой. В этом случае мы не рекомендуем заносить пользователя в черный список.
4.Fraud.Используется в случае потенциального фрода.
5.Test Payment.Используется в случае совершения тестового платежа с последующей отменой. В этом случае мы не рекомендуем заносить пользователя в черный список.
6.Expired Invoice.Используется, если был выбран способ оплаты с системой отложенного платежа.
7.PS debt cancel.Используется, если транзакция была совершена через платежную систему, которая не произвела выплату по данной транзакции. В этом случае мы не рекомендуем заносить пользователя в черный список.
8.Cancellation by the PS request.Используется, когда платежная система запросила отмену транзакции. В этом случае мы не рекомендуем заносить пользователя в черный список.
9.Cancellation by the user request.Используется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам. В этом случае мы не рекомендуем заносить пользователя в черный список.
10.Cancellation by the game request.Используется, когда игра просит отменить транзакцию. В этом случае мы не рекомендуем заносить пользователя в черный список.
11.Account holder called to report fraud.Используется, когда владелец аккаунта сообщил, что не совершал данный платеж.
12.Friendly fraud.Используется, если нам сообщили о friendly fraud.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'refund',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => array(
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

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

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

$callback = function (Message $message) {
    if ($message->isRefund()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $refundArray = $message->getRefundDetails();
        $messageArray = $message->toArray();
        // TODO if you cannot handle the refund, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Отмена апгрейда

Если пользователь отменил платеж, связанный с апгрейдом, Иксолла отправляет данные об отмененных апгрейдах и текущем пакете на webhook URL.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
purchase
objectОбъект с информацией о покупке. Обязательный.
purchase.pin_codes
objectОбъект с информацией о купленных пакетах игры.
purchase.pin_codes.purchase_type
stringТип покупки. Принимает значения “regular” – покупка пакета, “upgrade” – апгрейд пакета.
purchase.pin_codes.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.DRM
stringDRM-платформа игры.
purchase.pin_codes.currency
stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
purchase.pin_codes.amount
floatСумма покупки.
purchase.pin_codes.transaction
objectОбъект с информацией о транзакции.
purchase.pin_codes.transaction.id
integerID транзакции.
purchase.pin_codes.upgrade
objectОбъект с информацией об апгрейде.
purchase.pin_codes.upgrade.digital_content_from
objectОбъект с информацией о пакете пользователя, с которого был произведен апгрейд.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringDRM-платформа игры.
purchase.pin_codes.upgrade.digital_content_to
objectОбъект с информацией о пакете, на который пользователь перешел в рамках апгрейда.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringАртикул игры, настраивается в Личном кабинете.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringDRM-платформа игры.
ownership
objectОбъект с информацией о пакетах, которыми владеет пользователь. Обязательный.
ownership.digital_content
stringАртикул игры, настраивается в Личном кабинете.
ownership.DRM
stringDRM-платформа игры.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array (
  'notification_type' => 'upgrade_refund',
  '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",
  "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",
  "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
  }
}'
Ответ

Транзакция отклонена при проверке AFS

Если транзакция была отклонена при проверке AFS, Иксолла присылает детали транзакции на webhook URL. Для включения оповещения, пожалуйста, обратитесь к аккаунт-менеджеру проекта.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе.
user.ip
stringIP адрес пользователя.
user.phone
stringНомер телефона пользователя (в международном формате).
user.email
stringEmail пользователя.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.country
stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
user.zip
stringПочтовый индекс.
transaction
objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
transaction.id
integerID транзакции.
transaction.external_id
stringВнешний ID транзакции.
transaction.dry_run
integerПризнак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.
transaction.agreement
integerID соглашения.
refund_details
objectОбъект с финансовыми данными рефанда.
refund_details.code
integerID кода.
refund_details.reason
stringПричина отмены.
refund_details.author
stringАвтор рефанда.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'afs_reject',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => array(
        'code' => 4,
        'reason' => 'Potential fraud'
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

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

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

$callback = function (Message $message) {
    if ($message->isRefund()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $refundArray = $message->getRefundDetails();
        $messageArray = $message->toArray();
        // TODO if you cannot handle the refund, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Создание подписки

Когда пользователь создает подписку, Иксолла присылает оповещение на webhook URL.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
subscription
objectОбъект с данными о подписке.
subscription.plan_id
stringID плана (внешний id, если план был создан через API).
subscription.tags
arrayТеги плана.
subscription.subscription_id
integerID подписки в базе данных Иксоллы.
subscription.product_id
stringID продукта (если был отправлен в токене).
subscription.date_create
stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
subscription.date_next_charge
stringДата следующего списания. Дата и время согласно стандарту ISO 8601.
subscription.trial
objectОбъект с информацией о триальном периоде подписки.
subscription.trial.value
integerДлительность триального периода.
subscription.trial.type
stringТип триального периода: day.
custom_parameters
objectВаши дополнительные параметры.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'create_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_next_charge' => '2015-01-22T19:25:25+04:00',
        'trial' =>  array(
                'value' =>  90,
                'type' =>  'day'
            )
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Изменение подписки

В случае изменения каких-либо параметров ('plan_id', 'date_next_charge') подписки и в случае каждого продления подписки, мы отправляем оповещение "update_subscription" на ваш webhook URL.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
subscription
objectОбъект с данными о подписке.
subscription.plan_id
stringID плана (внешний id, если план был создан через API).
subscription.tags
arrayТеги плана.
subscription.subscription_id
integerID подписки в базе данных Иксоллы.
subscription.product_id
stringID продукта (если был отправлен в токене).
subscription.date_next_charge
stringДата следующего списания. Дата и время согласно стандарту ISO 8601.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'update_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_next_charge' => '2015-01-22T19:25:25+04:00'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Отмена подписки

Когда подписка отменяется по каким-либо причинам, Иксолла присылает оповещение на webhook URL.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
subscription
objectОбъект с данными о подписке.
subscription.plan_id
stringID плана (внешний id, если план был создан через API).
subscription.tags
arrayТеги плана.
subscription.subscription_id
integerID подписки в базе данных Иксоллы.
subscription.product_id
stringID продукта (если был отправлен в токене).
subscription.date_create
stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
subscription.date_end
stringДата окончания срока действия подписки. Дата и время согласно стандарту ISO 8601.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'notification_type' => 'cancel_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_end' => '2015-01-22T19:25:25+04:00',
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Непродлеваемая подписка

Если по какой-либо причине статус подписки меняется на непродлеваемый, мы отправляем уведомление non_renewal_subscription на ваш webhook URL.

ПараметрТипОписание
settings
objectОбъект, содержащий настройки проекта.
settings.project_id
integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете. Обязательный.
settings.merchant_id
integerID продавца.
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.email
stringEmail пользователя.
subscription
objectОбъект с данными о подписке.
subscription.subscription_id
integerID подписки в базе данных Иксоллы.
subscription.plan_id
stringID плана (внешний, если план был создан через API).
subscription.date_create
stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
subscription.date_next_charge
stringДата следующего списания. Это дата следующего платежа, ожидаемого до того, как статус подписки пользователя был изменен на непродлеваемый. Дата и время согласно стандарту ISO 8601.
subscription.currency
stringВалюта рекуррентного плана. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
subscription.amount
floatСумма покупки.
Copy
Full screen
http
  • http
  • curl
Запрос
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
   "notification_type":"non_renewal_subscription",
   "settings":{
      "project_id":"18404",
      "merchant_id":"2340"
   },
   "user":{
      "id":"1234567",
      "name":"Xsolla User"
      "email":"email@example.com",
   },
   "subscription":{
      "subscription_id":4,
      "plan_id":"TestAutopayment",
      "date_create":"2020-04-30T18:08:28+03:00",
      "date_next_charge":"2020-05-01T21:08:33+03:00",
      "currency":"RUB",
      "amount":10
   }
}
$ 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":"non_renewal_subscription",
       "settings":{
          "project_id":"18404",
          "merchant_id":"2340"
       },
       "user":{
          "id":"1234567",
          "name":"Xsolla User"
          "email":"email@example.com",
       },
       "subscription":{
          "subscription_id":4,
          "plan_id":"TestAutopayment",
          "date_create":"2020-04-30T18:08:28+03:00",
          "date_next_charge":"2020-05-01T21:08:33+03:00",
          "currency":"RUB",
          "amount":10
       }
    }'
Ответ
HTTP/1.1 204 No Content

Получение ключа

Иксолла отправляет API вызовы к вашему серверу для получения ключа игры после каждого успешного платежа.

ПараметрТипОписание
notification_type
stringТип оповещения.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
pin_code
objectОбъект с информацией о ключе.
pin_code.digital_content
stringАртикул игры.
pin_code.DRM
stringDRM-платформа, на которой игра будет доступна.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array (
       'notification_type' => 'get_pincode',
       'user' =>
           array (
               'id' => '1234567',
               'name' => 'Xsolla User',
           ),
       'pin_code' =>
           array (
               'digital_content' => 'Game SKU',
               'DRM' => 'Steam',
           ),
   );
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

Активация ключа

Когда пользователь активирует ключ, Иксолла присылает оповещение на webhook URL.

ПараметрТипОписание
notification_type
stringТип оповещения.
key
stringКлюч активации.
sku
stringУникальный ID пакета ключей.
user_id
stringID пользователя.
activation_date
datetimeДата активации ключа в формате ГГГГММДДЧЧММСС согласно стандарту ISO 8601.
user_country
stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
restriction
objectОбъект с настройками кластера регионального ограничения. Кластер включает в себя тип ограничения, список стран, серверов и языковых версий, для которых доступна игра.
restriction.sku
stringУникальный ID кластера.
restriction.name
stringИмя кластера.
restriction.types
arrayМассив типов ограничений.
restriction.countries
arrayМассив стран, входящих в кластер.
restriction.servers
arrayМассив серверов игры.
restriction.locales
arrayМассив языковых версий игры.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php
$request = array(
    'notification_type' => 'redeem_key',
    'key' => ‘wqdqwwddq9099022’,
    'sku' => 123,
    'user_id' => ‘sample_user’,
    'activation_date' => ‘2018-11-20T08:38:51+03:00,
    'user_country' => ‘EN’,
    'restriction' =>
           array(
                'name' => ‘cls_1’,
                'types' =>
                        array(
                            ‘activation’
                        ),
                'countries' =>
                        array(
                            ‘RU’
                        ),
             ),
);  
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

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

$response = null;
HTTP/1.1 204 No Content

Получение списка друзей

API должен быть реализован на стороне партнера. Максимальный размер списка друзей — 2000. Посмотреть рецепт.

HTTP-ЗАПРОС

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

ПараметрТипОписание
notification_type
stringfriends_list — идентификатор , определяющий тип запрос на список друзей.
user
stringУникальный идентификатор пользователя, который делает покупку другу.
query
stringИмя или идентификатор друга. Может передавать часть имени или идентификатора друга.
limit
stringЛимит количества элементов на странице. Обязательный.
offset
integerНомер элемента, c которого выполняется вывод на странице (нумерация ведется с 0).
sign
stringСтрока для подписи формируется следующим образом:
  • notification_type + значения параметров, отсортированных по ключу в алфавитном порядке + secret_key
  • Второй шаг — применение SHA-1 криптографической хэш-функции к получившейся на первом шаге строке.
Copy
Full screen
http
  • http
  • curl
Запрос
GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1 HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
$ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
-X GET \
-u merchant_id:merchant_api_key
Ответ
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
  }
]

Баланс пользователя: внутренняя операция

Когда пользователь совершает платеж, Иксолла присылает специальное оповещение об изменении баланса пользователя.

ПараметрТипОписание
notification_type
stringТип оповещения.
operation_type
stringТип операции.
id_operation
integerID операции в базе данных Иксоллы.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.email
stringEmail пользователя.
virtual_currency_balance
objectОбъект с данными о балансе пользователя.
virtual_currency_balance.old_value
stringЗначение баланса до совершения данной операции.
virtual_currency_balance.new_value
stringЗначение баланса после совершения данной операции.
virtual_currency_balance.diff
stringКоличество виртуальной валюты в заказе.
transaction
objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
transaction.id
integerID транзакции.
transaction.date
stringДата транзакции.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '200',
        'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'transaction' => array(
        'id' => '123456789',
        'date' => '2015-05-19T15:54:40+03:00'
    ),
    'operation_type' => 'payment',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Баланс пользователя: покупка в игре

Когда пользователь совершает покупку в игре (например, покупка предметов), Иксолла присылает специальное оповещение об изменении баланса пользователя.

ПараметрТипОписание
notification_type
stringТип оповещения.
operation_type
stringТип операции.
id_operation
integerID операции в базе данных Иксоллы.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.email
stringEmail пользователя.
virtual_currency_balance
objectОбъект с данными о балансе пользователя.
virtual_currency_balance.old_value
stringЗначение баланса до совершения данной операции.
virtual_currency_balance.new_value
stringЗначение баланса после совершения данной операции.
virtual_currency_balance.diff
stringКоличество виртуальной валюты в заказе.
items_operation_type
stringТип операции с предметами.
items
arrayМассив данных о предмете в заказе.
items.sku
stringID предмета (артикул).
items.amount
integerКоличество этого предмета в заказе.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Баланс пользователя: активация купона

Если пользователь активировал купон для получения предметов или виртуальной валюты в игре, Иксолла присылает специальное оповещение об изменении баланса пользователя.

ПараметрТипОписание
notification_type
stringТип оповещения.
operation_type
stringТип операции.
id_operation
integerID операции в базе данных Иксоллы.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.email
stringEmail пользователя.
virtual_currency_balance
objectОбъект с данными о балансе пользователя.
virtual_currency_balance.old_value
stringЗначение баланса до совершения данной операции.
virtual_currency_balance.new_value
stringЗначение баланса после совершения данной операции.
virtual_currency_balance.diff
stringКоличество виртуальной валюты в заказе.
items_operation_type
stringТип операции с предметами.
items
arrayМассив данных о предмете в заказе.
items.sku
stringID предмета (артикул).
items.amount
integerКоличество этого предмета в заказе.
coupon
objectОбъект с данными о купоне.
coupon.coupon_code
stringКод купона.
coupon.campaign_code
stringКод кампании купонов.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '0',
        'diff' => '0'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'coupon',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989',
    'coupon' =>  array(
         'coupon_code' =>  'test123',
         'campaign_code' =>  'Xsolla Campaign'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Баланс пользователя: изменение вручную

Если необходимо изменить баланс пользователя вручную, вы можете использовать тип операции "Internal".

ПараметрТипОписание
notification_type
stringТип оповещения.
operation_type
stringТип операции.
id_operation
integerID операции в базе данных Иксоллы.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.email
stringEmail пользователя.
virtual_currency_balance
objectОбъект с данными о балансе пользователя.
virtual_currency_balance.old_value
stringЗначение баланса до совершения данной операции.
virtual_currency_balance.new_value
stringЗначение баланса после совершения данной операции.
virtual_currency_balance.diff
stringКоличество виртуальной валюты в заказе.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '100',
        'diff' => '100'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'internal',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '67002'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Баланс пользователя: отмена платежа

Когда пользователь отменяет платеж, Иксолла присылает специальное оповещение об изменении баланса пользователя.

ПараметрТипОписание
notification_type
stringТип оповещения.
operation_type
stringТип операции.
id_operation
integerID операции в базе данных Иксоллы.
user
objectОбъект с информацией о пользователе.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.email
stringEmail пользователя.
virtual_currency_balance
objectОбъект с данными о балансе пользователя.
virtual_currency_balance.old_value
stringЗначение баланса до совершения данной операции.
virtual_currency_balance.new_value
stringЗначение баланса после совершения данной операции.
virtual_currency_balance.diff
stringКоличество виртуальной валюты в заказе.
transaction
objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
transaction.id
integerID транзакции.
transaction.date
stringДата транзакции.
items_operation_type
stringТип операции с предметами.
items
arrayМассив данных о предмете в заказе.
items.sku
stringID предмета (артикул).
items.amount
integerКоличество этого предмета в заказе.
Copy
Full screen
php
  • php
  • http
  • curl
Запрос
<?php

$request = array(
     'virtual_currency_balance' => array(
         'old_value' => '0',
         'new_value' => '0',
         'diff' => '0'
     ),
     'user' => array(
         'name' => 'Xsolla User',
         'id' => '1234567',
         'email' => 'email@example.com'
     ),
     'transaction' => array(
         'id' => '123456789',
         'date' => '2015-05-19T15:54:40+03:00'
     ),
     'operation_type' => 'cancellation',
     'notification_type' => 'user_balance_operation',
     'items_operation_type' =>  'remove',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
     'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Добавление платежного аккаунта

Когда пользователь добавляет платежный аккаунт вручную или сохраняет платежный аккаунт при совершении покупки, Иксолла присылает оповещение на webhook URL. Для включения оповещения, пожалуйста, обратитесь к аккаунт-менеджеру проекта.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе.
user.ip
stringIP адрес пользователя.
user.email
stringEmail пользователя.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
user.country
stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
user.zip
stringПочтовый индекс.
payment_account
objectОбъект с информацией о платежном аккаунте.
payment_account.id
stringID платежного аккаунта. Обязательный.
payment_account.name
stringНазвание платежного аккаунта в платежной системе. Например, номер карты, email.
payment_account.payment_method
integerID способа оплаты.
payment_account.type
stringТип платежного аккаунта. Например, карта, PayPal.
Copy
Full screen
http
  • http
  • curl
Запрос
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",
    "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",
    "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"
    }
}'
Ответ
HTTP/1.1 204 No Content

Удаление платежного аккаунта

Когда пользователь удаляет платежный аккаунт из сохраненных, Иксолла присылает оповещение на webhook URL. Для включения оповещения, пожалуйста, обратитесь к аккаунт-менеджеру проекта.

ПараметрТипОписание
notification_type
stringТип оповещения. Обязательный.
user
objectОбъект с информацией о пользователе.
user.email
stringEmail пользователя.
user.id
stringID пользователя. Обязательный.
user.name
stringИмя пользователя.
payment_account
objectОбъект с информацией о платежном аккаунте.
payment_account.id
stringID платежного аккаунта. Обязательный.
payment_account.name
stringНазвание платежного аккаунта в платежной системе. Например, номер карты, email.
payment_account.payment_method
integerID способа оплаты.
payment_account.type
stringТип платежного аккаунта. Например, карта, PayPal.
Copy
Full screen
http
  • http
  • curl
Запрос
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",
    "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",
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'
Ответ
HTTP/1.1 204 No Content

Оповещения — ошибки

Коды ошибок:

КодОписание
INVALID_USERНеверный пользователь.
INVALID_PARAMETERНеверный параметр.
INVALID_SIGNATUREНевалидная подпись.
INCORRECT_AMOUNTНекорректная сумма.
INCORRECT_INVOICEНеверный заказ.
HTTP/1.1 400 Bad Request

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