Получение информации о подписках

Если в Web Shop планируется продажа подписок, реализуйте получение информации о действиях с подписками одним из способов:

• с помощью API (подходит при бессерверной интеграции);
• с помощью вебхуков (автоматические оповещения, подходит при серверной интеграции).

Настройка через методы API

В клиентской части вашего приложения реализуйте получение информации о подписках пользователя с использованием HTTP GET-запроса.

Xsolla API использует HTTP-аутентификацию. Запрос должен содержать заголовок Authorization: Bearer <client_user_jwt>, где <client_user_jwt> — уникальный токен, закодированный по стандарту Base64. Используйте для его получения:

• При авторизации по логину и паролю — методы API Register new user и Auth by username and password.
• При авторизации через социальные сети — метод API Auth via social network.

В качестве path-параметра укажите projectId — ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта. В качестве query-параметров укажите:

• limit — лимит количества элементов на странице (по умолчанию на странице выдается 15 записей).
• offset — номер элемента, с которого выполняется вывод на странице (нумерация ведется с 0).
• locale — язык интерфейса, принимает значения в соответствии со стандартом ISO 639-1 (по умолчанию английский).

-X 'GET' \
  'https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'

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

{
  "items": [
    {
      "id": 11111111,
      "plan_id": 11111
      "plan_external_id": "TestChangePlanBase",
      "plan_name": "package_recurrent_name_66053",
      "plan_description": "package_recurrent_description_66053",
      "product_id": null,
      "product_external_id": null,
      "product_name": null,
      "product_description": null,
      "status": "active",
      "date_create": "2021-03-11T13:50:11+03:00",
      "date_next_charge": "2031-04-11T13:51:02+03:00",
      "date_last_charge": "2021-03-11T13:51:02+03:00",
      "charge": {
        "amount": "0.2500",
        "currency": "USD"
      },
      "period": {
        "value": 1,
        "unit": "day"
      }
    }
  ],
  "has_more": true
}

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

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

2. В приложении реализуйте обработку следующих типов вебхуков:
   • Для покупки и продления подписки:
     • Проверка существования пользователя
     • Успешный платеж
     • Создание подписки
     • Изменение подписки
   • Для отмены подписки: Отмена подписки
   • Для отмены платежа: Возврат платежа

3. Протестируйте вебхуки:
   1. В Личном кабинете в разделе Настройки проекта > Вебхуки перейдите на вкладку Subscriptions.

2. Чтобы проверить работу системы вебхуков, укажите значения из проекта (User ID, Invoice ID), которые будут отправлены в запросе на указанный URL. При отсутствии реальных значений допускается ввод произвольных значений. Заполните поля:
   • ID пользователя;
   • ID заявки в Xsolla;
   • сумма;
   • валюта;
   • ID плана;
   • продукт подписки (опционально);
   • Invoice ID — внутренний номер заказа (опционально);
   • пробный период (для тестирования покупки подписки без пробного периода или тестирования продления подписки укажите значение 0).

3. Нажмите Тестировать.
4. Убедитесь, что сообщение об успешном завершении тестирования получено. При успешной обработке запроса ваш сервер должен вернуть:
   • 204 HTTP-код без тела сообщения в случае успешного ответа.
   • 400 или 500 HTTP-коды с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.

4. Протестируйте получение остальных вебхуков:
   1. Используйте тестовое окружение, чтобы протестировать покупку и продление подписки и получить вебхуки Создание подписки, Изменение подписки, Отмена подписки.
   2. Используйте боевое окружение, чтобы протестировать покупку подписки на реальных платежах и получить вебхуки Возврат платежа, Отмена подписки.

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

1. Настройте аутентификацию пользователя.
2. Проверьте работу Web Shop в тестовом окружении.

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

Сценарий интеграции