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

Вы можете получать информацию о действиях с подписками следующими способами:

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

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

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

В качестве query-параметров укажите:

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

  '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. В Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
2. Установите переключатель в блоке Вебхуки в положение Вкл.

3. Укажите URL, на который будут приходить вебхуки. Нажмите Сохранить настройки.

4. Протестируйте вебхуки в Личном кабинете.
5. Протестируйте покупку подписки.
6. Протестируйте продление подписки.
7. Протестируйте отмену подписки.

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

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

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

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

Тестирование покупки подписки

При тестировании оплаты на указанный при настройке вебхуков URL будут отправлены вебхуки Проверка существования пользователя, Успешный платеж, Создание подписки. Для тестирования процесса оплаты вы можете:

• использовать тестовое окружение (для подписок без пробного периода);
• провести реальный платеж, а затем сделать возврат через Личный кабинет (для подписок с пробным периодом).

Тестовое окружение

1. Получите токен для перехода к тестовому окружению. Для параметра Пробный период (trial_days) передайте значение 0.
2. Выберите группу способов оплаты Банковские карты.
3. Введите реквизиты тестовой банковской карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.

4. Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.

Реальный платеж

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

1. Выполните тестирование вебхуков в Личном кабинете и активируйте модуль Подписки.
2. Подпишите Лицензионный договор. Для этого в Личном кабинете перейдите в раздел Финансы > Лицензионный договор, заполните договор и дождитесь подтверждения согласования.

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

4. Откройте платежный интерфейс. Для этого используйте ссылку https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.
5. Выберите группу способов оплаты Банковские карты.
6. Введите реквизиты действующей карты.

7. Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.
8. Выполните возврат платежа. Для этого перейдите в Личный кабинет в раздел Поддержка > Поиск транзакций.
9. Выберите тестовую транзакцию, нажмите значок Расширенные настройки (•••), чтобы открыть меню. Затем нажмите Возврат (транзакция должна находиться в статусе Выполнена). При этом будут отправлены вебхуки Отмена подписки, Возврат платежа.

Тестирование продления подписки

Чтобы протестировать продление подписки:

1. Получите токен для перехода к тестовому окружению. Для параметра Пробный период (trial_days) передайте значение 0.
2. Оплатите подписку любым способом оплаты.
3. Повторно откройте платежный интерфейс в тестовом окружении.
4. Повторно оплатите подписку любым способом оплаты.
5. Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.

Тестирование отмены подписки

Чтобы протестировать отмену подписки используйте:

• поиск по подпискам;
• поиск последних транзакций по подписке;
• методы API.

Поиск по подписке

1. В Личном кабинете перейдите в раздел Поддержка > Подписчики.
2. Найдите подписку, которую необходимо отменить.
3. Откройте меню статуса подписки и выберите:
   1. Отменить с возвратом платежа для получения вебхуков Отмена подписки, Возврат платежа.
   2. Отменить без возврата платежа для получения вебхука Отмена подписки.

Поиск по транзакциям

1. В Личном кабинете перейдите в раздел Поддержка > Поиск транзакций.
2. Выполните поиск транзакции, которую необходимо отменить.
3. Нажмите на значок Расширенные настройки (•••), чтобы открыть меню. Затем нажмите Возврат для получения вебхуков Отмена подписки, Возврат платежа.

Через методы API

Используйте метод Изменение подписки, чтобы изменить статус подписки на Canceled и получить вебхук Отмена подписки.

Открытие платежного интерфейса в тестовом окружении

Чтобы открыть тестовый платежный интерфейс, необходимо получить токен с активированным режимом sandbox. Ссылку с таким токеном можно получить двумя способами:

• через Личный кабинет;
• через метод API.

Через Личный кабинет

1. Протестируйте вебхуки в Личном кабинете. Для тестирования подписки без пробного периода в поле Пробный период укажите значение 0. После получения сообщения об успешном завершении тестирования под заголовком URL тестового окружения появится ссылка с нужным токеном.

2. Перейдите по ссылке URL тестового окружения.

Через метод API

1. Передайте в метод Создание токена параметр "settings":{"mode":"sandbox"}. Для тестирования подписки без пробного периода передайте параметр "purchase": {"subscription":{"trial_days": 0}}.
2. Используйте ссылку https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.