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

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

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

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

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

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

PHP SDK

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

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

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

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

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

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

Обработчик вебхуков — это программный код, который позволяет принимать поступающие вебхуки на указанный 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 не получил ответ или получил ответ с 400 или 5xx HTTP-кодом, повторная отправка вебхука Проверка существования пользователя не осуществляется.

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

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

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

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

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

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

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

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

 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 без содержимого бандла:

 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.