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

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

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

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

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

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

Примечание
Для работы с Xsolla API вы можете использовать готовые методы SDK для игровых движков и платформ:

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

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

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

Copy
Full screen
Small screen
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'
Copy
Full screen
Small screen
{
  "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 доступны вебхуки при следующих событиях:

Примечание
Для отмены подписки необходимо отменить последний платеж. Если подписка продлевалась вручную и оплачены несколько периодов, необходимо отменить все платежи.
  • Отмена платежа:
    • Отмена платежа (Платеж отменен через Личный кабинет);
    • Изменение подписки (Платеж отменен, но подписка продолжает действовать. Ситуация возможна, если пользователь случайно дважды оплатил подписку и отменил последний платеж);
    • Отмена подписки (Подписка отменена через Личный кабинет или отменены все платежи за все действующие периоды).
Примечание
Подробнее о вебхуках вы можете узнать в справочнике API.
Чтобы настроить вебхуки:
  1. В Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
  2. Установите переключатель в блоке Вебхуки в положение Вкл.

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

  1. Протестируйте вебхуки в Личном кабинете.
  2. Протестируйте покупку подписки.
  3. Протестируйте продление подписки.
  4. Протестируйте отмену подписки.

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

  1. В Личном кабинете в разделе Настройки проекта > Вебхуки перейдите на вкладку Subscriptions.
  1. Чтобы проверить работу системы вебхуков, укажите значения из проекта (User ID, Invoice ID), которые будут отправлены в запросе на указанный URL. При отсутствии реальных значений допускается ввод произвольных значений. Заполните поля:
Примечание
В Личном кабинете вы можете протестировать только базовые вебхуки Проверка существования пользователя и Успешный платеж. Для тестирования остальных вебхуков перейдите к разделам:
  1. Нажмите Тестировать.
  2. Убедитесь, что получено сообщение об успешном завершении тестирования. При успешной обработке запроса необходимо возвращать 204 HTTP код. В случае возникновения ошибки — 400-е или 500-е HTTP коды вместе с описанием ошибки.

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

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

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

  1. Получите токен для перехода к тестовому окружению. Для параметра Пробный период (trial_days) передайте значение 0.
  2. Выберите группу способов оплаты Банковские карты.
  3. Введите реквизиты тестовой банковской карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.
Примечание
Оплатить покупку в тестовом окружении возможно только тестовой банковской картой. Платежи могут проводиться в следующих валютах: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.
  1. Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.

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

Чтобы протестировать оплату подписки с пробным периодом, используйте реальный платеж. Для этого:
  1. Выполните тестирование вебхуков в Личном кабинете и активируйте модуль Subscriptions.
  2. Подпишите Лицензионный договор.
Примечание
Подписание Лицензионного договора активирует продажу реальных подписок.
  1. Получите токен для проведения реальных платежей.
Внимание
Удалите из запроса на получение токена параметр “mode”:“sandbox” перед тем, как начать принимать реальные платежи.
  1. Откройте платежный интерфейс. Для этого используйте ссылку https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.
  2. Выберите группу способов оплаты Банковские карты.
  3. Введите реквизиты действующей карты.
Примечание
Тестовые банковские карты подходят только для тестового окружения. Для реальных платежей рекомендуется использовать карты Visa и MasterCard.
  1. Получите вебхуки Проверка существования пользователя, Успешный платеж, Изменение подписки на URL, указанный при настройке вебхуков.
  2. Выполните возврат платежа. Для этого перейдите в Личный кабинет в раздел Поддержка > Поиск транзакций.
  3. Выберите тестовую транзакцию, нажмите значок Расширенные настройки (•••), чтобы открыть меню. Затем нажмите Возврат (транзакция должна находиться в статусе Выполнена). При этом будут отправлены вебхуки Отмена подписки, Возврат платежа.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Через метод API

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

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!