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

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

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

• Если вы получаете объединенные вебхуки
• Если вы получаете отдельные вебхуки

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

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

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

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

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

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

PHP SDK

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

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

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

1. В проекте в Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
2. В поле Сервер для вебхуков укажите URL-адрес, на который Xsolla будет отправлять вебхуки.

3. Нажмите Получать вебхуки.

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

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

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

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

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

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

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

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

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

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

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

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

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

Если на вебхук Успешный платеж сервер Xsolla не получил ответ или получил ответ с 5xx HTTP-кодом, также осуществляется повторная отправка вебхуков через увеличивающийся временной интервал. Максимально осуществляется 12 попыток в течение 12 часов.

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

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

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

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

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

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

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

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

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

 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      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

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

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

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

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

 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.

Общая информация

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

Взаимодействие между вашей игрой и Xsolla:

Как настроить

Чтобы получать события от Xsolla через API:

1. В вашем проекте в Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
2. Нажмите Использовать API. Настройки будут сохранены автоматически.

3. С клиентской части приложения отправьте запрос к https://getupdate.xsolla.com/events, чтобы получить информацию о платеже. Подробная информация приведена в справочнике API. В ответе вы получите данные о платеже в таком же формате как и в вебхуке Успешный платеж.
4. Если платеж завершен успешно, начислите пользователю товары.

Справочник API

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

1GET https://getupdate.xsolla.com/events

Авторизация: Bearer User JWT token

Пример ответа:

 1{
 2  "events": [
 3   {
 4     "id": 49, // event_id
 5     "status": 0,
 6     "created_at": "2025-04-03T21:21:27Z",
 7     "data": {
 8       "notification_type": "payment",
 9       "purchase": {
10         "order": {
11           "id": 000000001,
12           "lineitems": [
13             {
14               "quantity": 1,
15               "sku": "skill"
16             }
17           ]
18         }
19       },
20       ...
21     }
22   }
23 ]
24}

Пометка события как обработанного

1POST https://getupdate.xsolla.com/events/<event_id>/processed

event_id — это значение параметра events.id, полученного в ответе на вызов метода API Получение списка необработанных событий для пользователя.

Авторизация: Bearer User JWT token