Отслеживание статуса заказа

Отслеживание статуса заказа требуется, чтобы убедиться, что оплата прошла успешно, и начислить товары пользователю.

Вы можете отслеживать статус заказа как на клиентской, так и на серверной части вашего приложения. Однако мы рекомендуем настроить обработчик вебхуков и получать информацию о заказе на серверной части вашего приложения. Это позволит реализовать дополнительную валидацию совершенных покупок.

Выберите способ отслеживания статуса заказа:

Выберите наиболее подходящий для вашего проекта способ обращения к данным Xsolla:

Если у вас нет своего сервера или вы используете логику обработки покупок на стороне клиента, вы можете использовать следующие способы:

Xsolla API для событий.
WebSocket API.
Простые запросы (Short-polling).

Используйте в качестве примера реализации тестовые веб-приложения:

Java;
TypeScript.

Xsolla API для событий

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

Xsolla API для событий — это альтернатива использованию вебхуков. Он позволяет вам получать информацию о платежных событиях напрямую с клиента вашего приложения через запросы к серверу Xsolla. Такой подход исключает необходимость настройки и обслуживания собственного сервера для обработки вебхуков. Подробная информация об использовании Xsolla API для событий приведена в документации.

Получение статуса заказа на стороне клиента с помощью веб-сокет-соединения

Решение предусматривает использование веб-сокетов для получения статусов заказа без получения подробной информации о самом заказе. Этот способ является предпочтительным: между клиентом (например, вашим сайтом или мобильным приложением) и сервером Xsolla устанавливается только одно подключение, поэтому нет дополнительной нагрузки ни на клиент, ни на сервер.

Если у вас нет своего сервера для обработки вебхуков или вы используете логику обработки покупок на стороне клиента, вы можете использовать веб-сокет-соединение с помощью Centrifuge SDK.

Выполните следующие действия:

Для того чтобы веб-сокет-сервер Xsolla и ваш клиент могли идентифицировать сообщения со статусом заказа, создайте соединение:

Copy

Full screen

Small screen

 1const client = new Centrifuge(
 2connectionURL,
 3{
 4data: {
 5  user_external_id: user_external_id,
 6  auth: auth,
 7  project_id: project_id
 8}
 9}
10)
11connectionURL - wss://ws-store.xsolla.com/connection/websocket
12auth - user JWT token

Чтобы получать новые сообщения о статусах заказов, подпишитесь на события с помощью функции client.on:

Copy

Full screen

Small screen

1client.on('publication', (ctx) => {
2   //handle the status
3});

Установите соединение:

Copy

Full screen

Small screen

1client.connect()

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

Copy

Full screen

Small screen

 1client.on('subscribed', function (ctx) {
 2   client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
 3resp.publications.forEach((ctx) => {
 4   /handle the status
 5});
 6
 7   }, function (err) {
 8       //handle the status
 9   });
10});

Пример тела сообщения:

Copy

Full screen

Small screen

1{
2order_id: 59614241,
3status: "new"
4}

Возможны следующие статусы заказа:

New — заказ создан и еще не оплачен.
Paid — заказ оплачен.
Done — заказ полностью доставлен (в том числе отправлены все чеки, выполнены доставки на стороне Xsolla, внешних платформ и т.д.).
Canceled — заказ отменен, оплата возвращена пользователю.

Рекомендации при работе с веб-сокетами:

Установите максимальное время ожидания ответча через веб-сокет — 5 минут.
Устанавливайте соединение при открытии платежного интерфейса.
Прерывайте соединение после получения финального статуса заказа: Canceled или Done.
По истечении времени жизни веб-сокета или при возникновении проблем с соединением используйте простые запросы.

Простые запросы (short-polling)

Чтобы получить детальную информацию о товарах в заказе после перехода в нужный статус, используйте API-метод Получение заказа.

Используется периодический опрос статуса заказа — простой HTTP-запрос, который получает текущий статус заказа, а также информацию по нему. Рекомендуемая задержка между запросами — 3 секунды.

Для отслеживания статусов создаваемых заказов и их валидации вам потребуется настроить обработку вебхуков на серверной части вашего приложения.

PHP SDK

Используйте готовые классы для обработки вебхуков

На стороне Xsolla настроено 2 варианта отправки вебхуков при покупке и возврате товаров — информация с данными платежа и транзакции и информация о купленных товарах может приходить отдельно или может быть объединена в один вебхук. По умолчанию во всех новых проектах настроена отправка объединенных вебхуков.

Для перехода к новому варианту с получением объединенных вебхуков обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

Подробнее о вариантах получения вебхуков

Получение информации в объединенных вебхуках:

Если вы зарегистрировались в Личном кабинете после 22 января 2025 г., вы получаете всю информацию в вебхуках Успешная оплата заказа (order_paid) и Отмена заказа (order_canceled). В этом случае вам не требуется обрабатывать вебхуки Успешный платеж (payment) и Возврат платежа (refund).

Получение информации в отдельных вебхуках:

Если вы зарегистрировались в Личном кабинете до 22 января 2025 г. включительно, вы получаете вебхуки:

Успешный платеж (payment) и Возврат платежа (refund) с информацией о данных платежа и детали транзакции.
Успешная оплата заказа (order_paid) и Отмена заказа (order_canceled) с информацией о купленных товарах.

Вам необходимо обрабатывать все поступающие вебхуки.

Для полноценной работы внутриигрового магазина и управления платежами, необходимо реализовать обработку основных вебхуков:

Название вебхука	Описание
Проверка пользователей > Проверка существования пользователя (`user_validation`)	Отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре.
Игровые сервисы > Объединенные вебхуки > Успешная оплата заказа (`order_paid`)	Данные платежа, детали транзакции и информация о купленных товарах. Используйте данные вебхука для начисления товаров пользователю.
Игровые сервисы > Объединенные вебхуки > Отмена заказа (`order_canceled`)	Данные отмененного платежа, детали транзакции и информацию о купленных товарах. Используйте данные вебхука для списания купленных товаров у пользователя.

Ниже приведена схема покупки и возврата товаров с использованием объединенных вебхуков.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant User as Пользователь
    participant GameClient as Клиент игры
    participant Xsolla as Xsolla
    participant GameServer as Сервер игры
    %% Item Purchase
    rect rgb(243, 243, 241)
        Note over User, GameServer: Покупка товара
    end
        User ->> GameClient: Авторизуется
        activate GameClient
        GameClient ->> Xsolla: Отправляет запрос аутентификации пользователя
        activate Xsolla
        Xsolla -->> GameClient: Возвращает JWT / OAuth 2.0 токен
        deactivate Xsolla
        GameClient ->> Xsolla: Отправляет JWT, ID проекта и параметры пагинации
        activate Xsolla
        Xsolla -->> GameClient: Возвращает массив товаров
        deactivate Xsolla
        GameClient -->> User: Отображает витрину
        deactivate GameClient
        User ->> GameClient: Выбирает товар и нажимает Купить
        activate GameClient
        GameClient ->> Xsolla: Отправляет запрос на создание заказа
        deactivate GameClient
        activate Xsolla
        Xsolla -->> GameClient: Возвращает платежный токен
        deactivate Xsolla
        activate GameClient
        GameClient ->> Xsolla: Открывает URL платежного интерфейса с полученным токеном
        deactivate GameClient
        activate Xsolla
        Xsolla ->> GameServer: Отправляет вебхук Проверка пользователя
        activate GameServer
        GameServer -->> Xsolla: Возвращает статус успешного выполнения
        deactivate GameServer
        Xsolla -->> User: Отображает платежный интерфейс
        deactivate Xsolla
        User ->> Xsolla: Выбирает способ оплаты и нажимает Оплатить
        activate Xsolla
        Xsolla ->> GameServer: Отправляет вебхук Успешная оплата заказа
        activate GameServer
        activate GameServer
        Note right of GameServer: Начисляет покупки пользователю
        deactivate GameServer
        GameServer -->> Xsolla: Возвращает статус успешного выполнения
        deactivate GameServer
        Xsolla -->> User: Отображает экран успешной покупки
        deactivate Xsolla
    %% Refund / Chargeback
    rect rgb(243, 243, 241)
        Note over User, GameServer: Возврат / Чарджбэк
    end
        User ->> Xsolla: Запрашивает возврат или чарджбэк
        activate Xsolla
        Xsolla ->> GameServer: Отправляет вебхук Отмена заказа
        activate GameServer
        activate GameServer
        Note right of GameServer: Удаляет товары из инвентаря пользователя
        deactivate GameServer
        GameServer -->> Xsolla: Возвращает статус успешного выполнения
        deactivate GameServer
        Xsolla -->> User: Возвращает платеж
        deactivate Xsolla

Возврат и чарджбэк могут быть инициированы не только пользователем, но также Xsolla или платежным провайдером.

Если вы используете персонализацию каталога товаров, реализованную на стороне вашего приложения, настройте обработку вебхука Персонализация каталога на стороне партнера.

Чтобы принимать реальные платежи, достаточно подписать лицензионный договор и реализовать обработку вебхуков:

Успешный платеж, Успешная оплата заказа и Проверка существования пользователя, если вы получаете отдельные вебхуки.
Успешная оплата заказа и Проверка существования пользователя, если вы получаете объединенные вебхуки.

Полный список вебхуков и общая информация о работе с ними приведены в документации по вебхукам.

Настройка отправки вебхуков

Чтобы настроить вебхуки на стороне Xsolla:

В проекте в Личном кабинете перейдите в раздел Настройки > Вебхуки.
В поле Сервер для вебхуков укажите URL-адрес вашего сервера для получения вебхуков в формате https://example.com. Вы также можете ввести URL-адрес из инструмента для тестирования вебхуков.

Для тестирования вебхуков вы также можете выбрать любой специализированный сайт, например webhook.site, или платформу, например ngrok. Для реального проекта вам потребуется добавить логику валидации покупки.

Секретный ключ проекта для подписи вебхуков генерируется по умолчанию. Если вы хотите изменить его, нажмите значок обновления.
Нажмите Получать вебхуки.

Реализация обработчика вебхуков

Обработчик вебхуков — это программный код, который позволяет принимать поступающие вебхуки на указанный URL-адрес, генерировать подпись и отправлять ответ на вебхук на сервер Xsolla.

Генерация подписи

При получении вебхука необходимо обеспечить безопасность передачи данных. Для этого из данных вебхука необходимо сгенерировать подпись и проверить, что она совпадает с подписью, отправленной в заголовке HTTP-запроса.

Чтобы сгенерировать подпись:

Осуществите конкатенацию JSON из тела запроса и секретного ключа проекта.
Примените SHA-1 криптографическую хэш-функцию к получившейся на первом шаге строке.

Отправка ответов на вебхук

Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:

200, 201, или 204 HTTP-код в случае успешного ответа.
400 HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.

Ваш обработчик вебхуков также может возвращать код 5xx при временных проблемах на вашем сервере.

Если на вебхуки Успешная оплата заказа и Отмена заказа сервер Xsolla не получил ответ или получил ответ с кодом 5xx, осуществляется повторная отправка вебхуков по следующему расписанию:

2 попытки с интервалом 5 минут;
7 попыток с интервалом 15 минут;
10 попыток с интервалом 60 минут.

Максимально осуществляется 20 попыток отправки вебхуков в течение 12 часов с момента первой попытки.

Логика повторной отправки вебхуков Успешный платеж и Возврат платежа описана на странице соответствующего вебхука.

Если на вебхук Проверка существования пользователя сервер Xsolla не получил ответ или получил ответ с 400 или 5xx HTTP-кодом, повторная отправка вебхука Проверка существования пользователя не осуществляется.

Пользователь увидит ошибку, вебхуки Успешный платеж и Успешная оплата заказа отправлены не будут.

Полный список и механизм работы вебхуков с примерами обработки подробно описан в документации по вебхукам.

Настройка информации о товарах в вебхуках

Вы можете настроить, какие данные о товарах передаются в вебхуках Успешная оплата заказа и Отмена заказа в массиве items.

Подключение передачи дополнительных параметров

Подключите передачу дополнительных параметров, которые показывают:

является ли товар бесплатным (is_free);
является ли товар бонусом (is_bonus);
входит ли товар в состав бандла (is_bundle_content).

Чтобы получать эти параметры, переключите вебхуки на версию 2 с помощью метода API Обновление информации о настройках вебхуков. В версии 1 (используется по умолчанию) эти параметры отсутствуют.

Пример массива items с дополнительными параметрами:

Copy

Full screen

Small screen

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Отключение передачи содержимого бандла

По умолчанию в вебхуках все товары из бандла передаются как список отдельных товаров, входящих в бандл. Вы можете получать только бандл без его содержимого.

В этом случае товары, входящие в состав бандла, не будут включены в массив items. В приведенном выше примере будет исключен товар с SKU com.xsolla.gold_1, являющийся частью бандла.

Пример массива items без содержимого бандла:

Copy

Full screen

Small screen

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Чтобы отключить передачу содержимого бандла, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

Спасибо за обратную связь!

Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.

Последнее обновление: 15 мая 2026

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Содержание

Xsolla API для событий
Получение статуса заказа на стороне клиента с помощью веб-сокет-соединения
Простые запросы (short-polling)
Настройка отправки вебхуков
Реализация обработчика вебхуков
Генерация подписи
Отправка ответов на вебхук
Настройка информации о товарах в вебхуках
Подключение передачи дополнительных параметров
Отключение передачи содержимого бандла