Получение информации о подписках
Вы можете получать информацию о действиях с подписками следующими способами:
- запрашивать информацию с помощью API (подходит при бессерверной интеграции);
- получать информацию при смене статуса подписки автоматически с помощью вебхуков (подходит при серверной интеграции).
Настройка через методы API
В клиентской части вашего приложения реализуйте получение информации о подписках пользователя с использованием HTTP GET-запроса.
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
'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'
- js
{
"items": [
{
"id": 13371337,
"plan_id": 66053,
"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": 5,
"unit": "day"
}
}
],
"has_more": true
}
Настройка вебхуков
Для продукта Подписки доступны вебхуки при следующих событиях:
- Продление подписки:
- Отмена подписки: Отмена подписки (подписка отменена через Личный кабинет или отменены платежи за все действующие периоды).
- Отмена платежа:
- Отмена платежа (Платеж отменен через Личный кабинет);
- Изменение подписки (Платеж отменен, но подписка продолжает действовать. Ситуация возможна, если пользователь случайно дважды оплатил подписку и отменил последний платеж);
- Отмена подписки (Подписка отменена через Личный кабинет или отменены все платежи за все действующие периоды).
Чтобы настроить вебхуки:
- В Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
- Установите переключатель в блоке Вебхуки в положение Вкл.
- Укажите URL, на который будут приходить вебхуки. Нажмите Сохранить настройки.
- Протестируйте вебхуки в Личном кабинете.
- Протестируйте оплату подписки.
- Протестируйте продление подписки.
- Протестируйте отмену подписки.
Тестирование вебхуков в Личном кабинете
- В Личном кабинете в разделе Настройки проекта > Вебхуки перейдите на вкладку Подписки.
- Чтобы проверить работу системы вебхуков, укажите значения из вашего проекта (User ID, Invoice ID), которые будут отправлены в запросе на указанный URL. При отсутствии реальных значений допускается ввод произвольных значений. Заполните поля:
- ID пользователя;
- ID заявки в Иксолле;
- сумма;
- валюта;
- ID плана;
- продукт подписки (опционально);
- Invoice ID — внутренний номер заказа (опционально);
- пробный период (для тестирования оплаты подписки без пробного периода или тестирования продления подписки укажите значение
0
).
- Нажмите Тестировать.
- Убедитесь, что получено сообщение об успешном завершении тестирования. При успешной обработке запроса необходимо возвращать 204 HTTP код. В случае возникновения ошибки — 400-е или 500-е HTTP коды вместе с описанием ошибки.
Тестирование оплаты подписки
При тестировании оплаты на указанный при настройке вебхуков URL будут отправлены вебхуки Проверка существования пользователя, Успешный платеж, Создание подписки. Для тестирования процесса оплаты вы можете:
- использовать тестовое окружение (для подписок без пробного периода);
- провести реальный платеж, а затем сделать возврат через Личный кабинет (для подписок с пробным периодом).
Тестовое окружение
- Получите токен для перехода к тестовому окружению. Для параметра Пробный период (
trial_days
) передайте значение0
. - Выберите группу способов оплаты Банковские карты.
- Введите реквизиты тестовой банковской карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.
- Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.
Реальный платеж
Чтобы протестировать оплату подписки с пробным периодом, используйте реальный платеж. Для этого:
- Выполните тестирование вебхуков в Личном кабинете и активируйте модуль Подписки.
- Подпишите Лицензионный договор. Для этого в Личном кабинете перейдите в раздел Финансы > Лицензионный договор, заполните договор и дождитесь подтверждения согласования.
- Получите токен для проведения реальных платежей.
"mode":"sandbox"
перед тем, как начать принимать реальные платежи.- Откройте платежный интерфейс. Для этого используйте ссылку
https://secure.xsolla.com/paystation3/?access_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/paystation3/?access_token=ACCESS_TOKEN
, гдеACCESS_TOKEN
— токен, полученный на предыдущем шаге.
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.