Получение информации о подписках
Вы можете получать информацию о действиях с подписками следующими способами:
- запрашивать информацию с помощью 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 (по умолчанию английский).
- curl
curl -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'
- javascript
{
"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
}
Настройка вебхуков
Для продукта Subscriptions доступны вебхуки при следующих событиях:
- Продление подписки:
- Отмена подписки: Отмена подписки (подписка отменена через Личный кабинет или отменены платежи за все действующие периоды).
- Отмена платежа:
- Отмена платежа (Платеж отменен через Личный кабинет);
- Изменение подписки (Платеж отменен, но подписка продолжает действовать. Ситуация возможна, если пользователь случайно дважды оплатил подписку и отменил последний платеж);
- Отмена подписки (Подписка отменена через Личный кабинет или отменены все платежи за все действующие периоды).
- В Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
- Установите переключатель в блоке Вебхуки в положение Вкл.
- Укажите URL, на который будут приходить вебхуки. Нажмите Сохранить настройки.
- Протестируйте вебхуки в Личном кабинете.
- Протестируйте покупку подписки.
- Протестируйте продление подписки.
- Протестируйте отмену подписки.
Тестирование вебхуков в Личном кабинете
- В Личном кабинете в разделе Настройки проекта > Вебхуки перейдите на вкладку Subscriptions.
- Чтобы проверить работу системы вебхуков, укажите значения из проекта (User ID, Invoice ID), которые будут отправлены в запросе на указанный URL. При отсутствии реальных значений допускается ввод произвольных значений. Заполните поля:
- ID пользователя;
- ID заявки в Xsolla;
- сумма;
- валюта;
- ID плана;
- продукт подписки (опционально);
- Invoice ID — внутренний номер заказа (опционально);
- пробный период (для тестирования покупки подписки без пробного периода или тестирования продления подписки укажите значение
0
).
- Нажмите Тестировать.
- Убедитесь, что получено сообщение об успешном завершении тестирования. При успешной обработке запроса необходимо возвращать 204 HTTP код. В случае возникновения ошибки — 400-е или 500-е HTTP коды вместе с описанием ошибки.
Тестирование покупки подписки
При тестировании оплаты на указанный при настройке вебхуков URL будут отправлены вебхуки Проверка существования пользователя, Успешный платеж, Создание подписки. Для тестирования процесса оплаты вы можете:- использовать тестовое окружение (для подписок без пробного периода);
- провести реальный платеж, а затем сделать возврат через Личный кабинет (для подписок с пробным периодом).
Тестовое окружение
- Получите токен для перехода к тестовому окружению. Для параметра Пробный период (
trial_days
) передайте значение0
. - Выберите группу способов оплаты Банковские карты.
- Введите реквизиты тестовой банковской карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.
- Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.
Реальный платеж
Чтобы протестировать оплату подписки с пробным периодом, используйте реальный платеж. Для этого:- Выполните тестирование вебхуков в Личном кабинете и активируйте модуль Subscriptions.
- Подпишите Лицензионный договор.
- Получите токен для проведения реальных платежей.
“mode”:“sandbox”
перед тем, как начать принимать реальные платежи.- Откройте платежный интерфейс. Для этого используйте ссылку
https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN
, гдеACCESS_TOKEN
— токен, полученный на предыдущем шаге. - Выберите группу способов оплаты Банковские карты.
- Введите реквизиты действующей карты.
- Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.
- Выполните возврат платежа. Для этого перейдите в Личный кабинет в раздел Поддержка > Поиск транзакций.
- Выберите тестовую транзакцию, нажмите значок Расширенные настройки (•••), чтобы открыть меню. Затем нажмите Возврат (транзакция должна находиться в статусе Выполнена). При этом будут отправлены вебхуки Отмена подписки, Возврат платежа.
Тестирование продления подписки
- Получите токен для перехода к тестовому окружению. Для параметра Пробный период (
trial_days
) передайте значение0
. - Оплатите подписку любым способом оплаты.
- Повторно откройте платежный интерфейс в тестовом окружении.
- Повторно оплатите подписку любым способом оплаты.
- Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.
Тестирование отмены подписки
Чтобы протестировать отмену подписки используйте:Поиск по подписке
- В Личном кабинете перейдите в раздел Поддержка > Подписчики.
- Найдите подписку, которую необходимо отменить.
- Откройте меню статуса подписки и выберите:
- Отменить с возвратом платежа для получения вебхуков Отмена подписки, Возврат платежа.
- Отменить без возврата платежа для получения вебхука Отмена подписки.
Поиск по транзакциям
- В Личном кабинете перейдите в раздел Поддержка > Поиск транзакций.
- Выполните поиск транзакции, которую необходимо отменить.
- Нажмите значок Расширенные настройки (•••), чтобы открыть меню. Затем нажмите Возврат для получения вебхуков Отмена подписки, Возврат платежа.
Через методы API
Используйте метод Изменение подписки, чтобы изменить статус подписки на Canceled и получить вебхук Отмена подписки.Открытие платежного интерфейса в тестовом окружении
Чтобы открыть тестовый платежный интерфейс, необходимо получить токен с активированным режимомsandbox
. Ссылку с таким токеном можно получить двумя способами:Через Личный кабинет
- Протестируйте вебхуки в Личном кабинете. Для тестирования подписки без пробного периода в поле Пробный период укажите значение
0
. После получения сообщения об успешном завершении тестирования под заголовком URL тестового окружения появится ссылка с нужным токеном.
- Перейдите по ссылке URL тестового окружения.
Через метод API
- Передайте в метод Создание токена параметр
"settings":{"mode":"sandbox"}
. Для тестирования подписки без пробного периода передайте параметр"purchase": {"subscription":{"trial_days": 0}}
. - Используйте ссылку
https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN
, гдеACCESS_TOKEN
— токен, полученный на предыдущем шаге.
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.