Xsolla-logo

Основные положения

Вебхуки — это оповещения о происходящих в системе событиях. При наступлении определенного события Xsolla отправляет HTTP-запрос к вашему приложению, в котором передаются данные о событии. Чаще всего отправляется POST-запрос в JSON-формате.

Примеры событий:

  • взаимодействие пользователя с каталогом товаров;
  • оплата или отмена заказа.

Когда происходит настроенное событие, Xsolla через вебхук оповещает вашу систему об этом. В результате вы можете:

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

Пример работы вебхука обработки платежей:

Вебхук обработки 
платежей

Видеоинструкция по интеграции вебхуков Xsolla:

Настройка вебхуков при работе с продуктами и решениями Xsolla:

Продукт/ Решение Обязательно/ Опционально Для чего нужны вебхуки
Payments Обязательно
  • Валидация пользователей.
  • Получение информации о деталях транзакции в случаях успешного платежа или возврата платежа.
  • Начисление купленных товаров пользователю и списание товаров в случае отмены заказа.
In-Game Store Обязательно
  • Валидация пользователей.
  • Получение информации о деталях транзакции в случаях успешного платежа или возврата платежа.
  • Начисление купленных товаров пользователю и списание товаров в случае отмены заказа.
Buy Button Опционально Для продажи ключей не требуется валидация пользователя и начисление ему товаров. Вы можете подключить вебхуки, если вы хотите получать информацию о событиях, например об оплате или отмене заказа.
Если вы подключите вебхуки, важно обрабатывать все поступающие обязательные вебхуки.
Subscriptions Опционально Для получения информации о создании, изменении или отмене подписки. Альтернативный вариант — запрашивать информацию с помощью API.
Web Shop Опционально Для аутентификации пользователей, если вы используете аутентификацию через ID пользователя. Альтернативный вариант — использовать аутентификацию пользователей через Xsolla Login.
Digital Distribution Hub Опционально
  • Валидация пользователей.
  • Связывание ID транзакции со стороны Xsolla с ID транзакции в вашей системе.
  • Передача дополнительных параметров транзакции в заказе.
  • Начисление купленных товаров пользователю и списание их в случае отмены заказа.

Вы можете изучить инструкцию по настройке вебхуков для Digital Distribution Hub.

Список обязательных вебхуков

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

In-Game Store/ Payments

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

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

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

Примечание:

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

Subscriptions

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

  • Проверка существования пользователя (user_validation) — отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре.
  • Успешный платеж (payment) — отправляется, когда заказ оплачен, и содержит информацию о данных платежа и детали транзакции.
  • Создание подписки (create_subscription) — отправляется, когда был получен ответ об успешной обработке вебхука Успешный платеж или пользователь приобрел подписку с пробным периодом. Содержит детали купленной подписки и данные пользователя. Используйте данные вебхука для добавления подписки пользователю.
  • Изменение подписки (update_subscription) — отправляется при продлении или изменении подписки, когда был получен ответ об успешной обработке вебхука Успешный платеж. Содержит детали купленной подписки и данные пользователя. Используйте данные вебхука для продления подписки пользователю или изменения параметров подписки.
  • Возврат платежа (refund) — отправляется, когда заказ был отменен, и содержит информацию о данных отмененного платежа и детали транзакции.
  • Отмена подписки (cancel_subscription) — отправляется, если был получен ответ об успешной обработке вебхука Возврат платежа или подписка была отменена по другой причине. Содержит информацию о подписке и данные пользователя. Используйте данные вебхука для списания купленных подписок у пользователя.

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

Чтобы включить получение вебхуков:

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

Внимание

Для передачи данных используется протокол HTTPS, протокол HTTP не поддерживается.

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

Примечание

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

Внимание

Вы не можете отправлять вебхуки на разные URL-адреса одновременно. Однако вы можете сначала указать в Личном кабинете URL-адрес для тестирования, а затем изменить его на боевой.

Чтобы отключить получение вебхуков:

  1. Откройте проект в Личном кабинете.
  2. Нажмите Настройки проекта в боковом меню и перейдите на вкладку Вебхуки.
  3. Нажмите Отключить вебхуки.

Тестирование вебхуков в Личном кабинете

Тестирование вебхуков помогает убедиться в корректной настройке проекта как на вашей стороне, так и на стороне Xsolla.

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

Название вебхука Тип вебхука
Проверка существования пользователя user_validation
Успешный платеж payment
Отмена заказа order_canceled
Успешная оплата заказа order_paid

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

Раздел тестирования 
вебхуков

Примечание

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

Пример:

Для тестирования вы используете специализированный сайт webhook.site.

В разделе Тестирование ответа на неверную подпись отображается ошибка.

Это происходит, потому что Xsolla отправляет вебхук с неверной подписью и ожидает, что ваш обработчик ответит 4xx HTTP-кодом с указанием кода ошибки INVALID_SIGNATURE.

webhook.site отправляет 200 HTTP-код в ответ на все вебхуки, в том числе на вебхук с неверной подписью. Ожидаемый 4xx HTTP-код не может быть получен, поэтому в результате тестирования отображается ошибка.

Ошибка тестирования

Магазин

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

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

  1. В блоке тестирования вебхуков перейдите на вкладку Магазин.
  2. В раскрывающемся списке выберите тип товара. Если выбранный тип товара еще не настроен в Личном кабинете, нажмите:
    • Подключить – если модуль с товарами данного типа еще не подключен;
    • Настроить – если вы ранее уже подключали модуль, но не завершили настройку.
      При нажатии кнопки вы будете перенаправлены в раздел Личного кабинета, соответствующий типу выбранного товара. После создания товара вернитесь в раздел тестирования вебхуков и перейти к следующему шагу.
  3. Укажите произвольное числовое значение в поле ID заказа Иксоллы.
  4. Выберите артикулы товаров из раскрывающегося списка и укажите количество товаров. Вы можете выбрать несколько товаров. Для этого нажмите + и добавьте товары в новой строке.
  5. Выберите валюту, в которой оплачивается заказ.
  6. Нажмите Тестировать.

На указанный URL-адрес придут вебхуки Успешная оплата заказа и Отмена заказа с указанными данными. Ниже кнопки Тестировать отобразятся результаты тестирования каждого типа вебхука.

Раздел тестирования 
Магазин

Payments

На вкладке Payments вы можете протестировать работу следующих вебхуков:

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

  1. В блоке тестирования вебхуков перейдите на вкладку Payments.
  2. Заполните необходимые поля:

    1. ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
    2. Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если public user ID включен в вашем проекте в разделе Pay Station > Настройки > Дополнительные настройки.
    3. Валюта — выберите валюту из раскрывающегося списка.
    4. ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
    5. Количество — сумма платежа. При тестировании вы можете указать любое числовое значение.
    6. Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр.Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
  3. Нажмите Тестировать вебхуки.

На указанный URL-адрес придут вебхуки с введенными данными. Ниже кнопки Тестировать вебхуки отобразятся результаты тестирования каждого вебхука как для успешного сценария, так и для случая возникновения ошибки. Если в вашем проекте включен public user ID, в результатах тестирования также отобразится проверка поиска пользователя.

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

Раздел тестирования 
платежей

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

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

В вебхуке будет передаваться информация в кастомных параметрах:

  • saved_payment_method:
    • 0 — сохраненный способ оплаты не используется;
    • 1 — способ оплаты был сохранен при совершении текущей транзакции;
    • 2 — используется ранее сохраненный способ оплаты.
  • payment_type:
    • 1 — единоразовый платеж;
    • 2 — рекуррентный платеж.
Добавить объект order в вебхук В вебхуке Успешный платеж будет передаваться информация о заказе в объекте order.
Показывать только необходимую информацию о пользователе без чувствительных данных

В вебхуке о пользователе будет передаваться только следующая информация:

  • ID;
  • страна.
Передавать кастомные параметры В вебхуке будет передаваться информация о кастомных параметрах из токена.
Показывать БИН карты и последние 4 цифры ее номера

В вебхуке будет передаваться следующая информация о номере карты:

  • первые 6 цифр в параметре card_bin;
  • последние 4 цифры в параметре card_suffix.
Показывать бренд карты Бренд карты, с которой была совершена оплата. Например, Mastercard или Visa.

Расширенные 
настройки

Subscriptions

На вкладке Subscriptions вы можете протестировать работу следующих вебхуков при управлении подписками:

Примечание

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

Примечание

Для тестирования вебхуков у вас должен быть создан хотя бы один план подписки в разделе Личный кабинет> Subscriptions > Планы подписки.

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

  1. В блоке тестирования вебхуков перейдите на вкладку Subscriptions.
  2. Заполните необходимые поля:
    1. ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
    2. ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
    3. Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если public user ID включен в вашем проекте в разделе Pay Station > Settings > Additional settings section.
    4. Валюта — выберите валюту из раскрывающегося списка.
    5. ID плана — план подписки. Выберите план из раскрывающегося списка.
    6. Продукт подписки— выберите продукт из раскрывающегося списка (опционально).
    7. Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
    8. Invoice ID— ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр.Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
    9. Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки, укажите значение 0.
  3. Нажмите Тестировать вебхуки.

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

Обработчик вебхуков

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

Примечание

Вы можете использовать библиотеку Pay Station PHP SDK, которая содержит готовые классы для обработки вебхуков.

На стороне вашего приложения реализуйте прием вебхуков со следующих IP-адресов: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197.

Ограничения:

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

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

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

  1. Осуществите конкатенацию JSON из тела запроса и секретного ключа проекта.
  2. Примените SHA-1 криптографическую хэш-функцию к получившейся на первом шаге строке.
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"
      }
    }'

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

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

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

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

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

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

Внимание

Если возврат платежа был инициирован Xsolla и в ответе на вебхук Возврат платежа пришел ответ с `5xx` HTTP-кодом, платеж все равно будет возвращен.

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

Ошибки

Коды ошибок для HTTP-кода 400:

Код Описание
INVALID_USER Неверный пользователь
INVALID_PARAMETER Неверный параметр
INVALID_SIGNATURE Подпись неверна
INCORRECT_AMOUNT Некорректная сумма
INCORRECT_INVOICE Неверный заказ
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Список вебхуков

Примечание

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

Вебхук Тип оповещения Описание
Проверка существования пользователя user_validation Проверка существования пользователя в игре.
Поиск пользователя user_search Получение информации о пользователе по публичному ID пользователя.
Успешный платеж payment Оповещение об успешном платеже.
Возврат платежа refund Оповещение об отмене платежа.
Частичный возврат платежа partial_refund Оповещение о частичном возврате платежа.
Транзакция отклонена при проверке AFS afs_reject Оповещение об отмене транзакции системой расширенного антифрода.
Обновление черного списка AFS afs_black_list Оповещение об изменении черного списка AFS.
Создание подписки create_subscription Оповещение о создании подписки.
Изменение подписки update_subscription Оповещение о продлении подписки или о смене каких-либо параметров внутри подписки.
Отмена подписки cancel_subscription Оповещение об отмене подписки.
Непродлеваемая подписка non_renewal_subscription Оповещение о смене статуса на непродлеваемый.
Добавление платежного аккаунта payment_account_add Оповещение о добавлении или сохранении платежного аккаунта.
Удаление платежного аккаунта payment_account_remove Оповещение об удалении платежного аккаунта.
Проверка пользователя в Web Shop - Отправлено из Web Shop для проверки существования пользователя в игре.
Персонализация каталога на стороне партнера partner_side_catalog Отправляется, когда пользователь взаимодействует с магазином.
Успешная оплата заказа order_paid Отправляется, когда заказ оплачен.
Отмена заказа order_canceled Отправляется, когда заказ отменен.
Диспут dispute Оповещение об открытии нового диспута.