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

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

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

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

  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

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

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

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

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

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

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

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

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

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

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

• 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.

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