Начисление покупок пользователю

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

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

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

  %%{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

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

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

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

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

3. Создайте секретный ключ:

1. В разделе Secret keys нажмите Add key.
2. В открывшемся модальном окне введите название ключа, которое позволит идентифицировать его в общем списке.
3. Нажмите Create key.
4. Нажмите Copy secret и сохраните созданный ключ на вашей стороне.
5. Нажмите Done.
6. Подтвердите, что вы сохранили ключ, и нажмите Ok, close.

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

Ротация секретных ключей

В одном проекте вы можете создать до 5 секретных ключей, чтобы обеспечить их ротацию.

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

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

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

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

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

Также протестировать отправку вебхуков можно при проверке процесса оплаты в тестовом или боевом окружении. Протестировать вебхук Возврат платежа можно только в боевом окружении.

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

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

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

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

Следующие шаги

1. Настройте продажу подписок (опционально).
2. Настройте аутентификацию пользователя.

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

Вы можете настроить, какие данные о товарах передаются в вебхуках Успешная оплата заказа и Отмена заказа в массиве 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.

Полезные ссылки