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

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

запрашивать информацию с помощью 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.

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

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

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

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

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

Copy

Full screen

Small screen

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

Copy

Full screen

Small screen

 1{
 2  "items": [
 3    {
 4      "id": 11111111,
 5      "plan_id": 11111,
 6      "plan_external_id": "TestChangePlanBase",
 7      "plan_name": "package_recurrent_name_66053",
 8      "plan_description": "package_recurrent_description_66053",
 9      "product_id": null,
10      "product_external_id": null,
11      "product_name": null,
12      "product_description": null,
13      "status": "active",
14      "date_create": "2021-03-11T13:50:11+03:00",
15      "date_next_charge": "2031-04-11T13:51:02+03:00",
16      "date_last_charge": "2021-03-11T13:51:02+03:00",
17      "charge": {
18        "amount": "0.2500",
19        "currency": "USD"
20      },
21      "period": {
22        "value": 1,
23        "unit": "day"
24      }
25    }
26  ],
27  "has_more": true
28}

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

Для продукта Subscriptions доступны вебхуки при следующих событиях:

Оплата подписки:

Продление подписки:
Отмена подписки: Отмена подписки (подписка отменена через Личный кабинет или отменены платежи за все действующие периоды).

Продление подписки:
Отмена подписки: Отмена подписки (подписка отменена через ваш бизнес-аккаунт или отменены платежи за все действующие периоды).

Для отмены подписки необходимо отменить последний платеж. Если подписка продлевалась вручную и оплачены несколько периодов, необходимо отменить все платежи.

Отмена платежа:
- Отмена платежа (платеж отменен через ваш бизнес-аккаунт);
- Изменение подписки (платеж отменен, но подписка продолжает действовать. Ситуация возможна, если пользователь случайно дважды оплатил подписку и отменил последний платеж);
- Отмена подписки (подписка отменена через ваш бизнесс-аккаунт или отменены все платежи за все действующие периоды).

Отмена платежа:
- Отмена платежа (платеж отменен через Личный кабинет);
- Изменение подписки (платеж отменен, но подписка продолжает действовать. Ситуация возможна, если пользователь случайно дважды оплатил подписку и отменил последний платеж);
- Отмена подписки (подписка отменена через ваш бизнес-аккаунт или отменены все платежи за все действующие периоды).

Подробнее о вебхуках вы можете узнать в справочнике API.

Чтобы включить получение вебхуков:

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

В проекте вашего аккаунта перейдите в раздел Настройки > Вебхуки.

В проекте вашего аккаунта перейдите в раздел Настройки > Вебхуки.

В проекте вашего аккаунта перейдите в раздел Настройки > Вебхуки.

В проекте вашего аккаунта перейдите в раздел Настройки > Вебхуки.

В поле Сервер для вебхуков укажите URL-адрес вашего сервера для получения вебхуков в формате https://example.com. Вы также можете ввести URL-адрес из инструмента для тестирования вебхуков.

Для передачи данных используется протокол HTTPS, протокол HTTP не поддерживается.

Для тестирования вебхуков вы можете выбрать любой специализированный сайт, например webhook.site, или платформу, например ngrok.

Создайте секретный ключ:

В разделе Secret keys нажмите Add key.
В открывшемся модальном окне введите название ключа, которое позволит идентифицировать его в общем списке.
Нажмите Create key.
Нажмите Copy secret и сохраните созданный ключ на вашей стороне.
Нажмите Done.
Подтвердите, что вы сохранили ключ, и нажмите Ok, close.

Основные рекомендации:

Сохраните созданный секретный ключ на вашей стороне. Ключ отображается в Личном кабинете только один раз — сразу после создания.
Никому не сообщайте ваш секретный ключ.
Секретный ключ должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.

Основные рекомендации:

Сохраните созданный секретный ключ на вашей стороне. Ключ отображается в аккаунте только один раз — сразу после создания.
Никому не сообщайте ваш секретный ключ.
Секретный ключ должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.

Нажмите Получать вебхуки.

Ротация секретных ключей

В одном проекте вы можете создать до 5 секретных ключей, чтобы обеспечить их ротацию.

В проекте может быть только один активный секретный ключ. Если вы хотите его изменить, нажмите Set as active у другого ключа и подтвердите действие. После успешной миграции на новый ключ мы рекомендуем удалять деактивированные ключи.

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

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

Для тестирования вебхуков у вас должен быть создан хотя бы один план подписки в Личном кабинете в разделе Каталог товаров > Подписки.

Для тестирования вебхуков у вас должен быть создан хотя бы один план подписки в аккаунте в разделе Каталог товаров > Подписки.

Для тестирования вебхуков у вас должен быть создан хотя бы один план подписки в аккаунте в разделе Каталог товаров > Подписки section.

Для тестирования вебхуков у вас должен быть создан хотя бы один план подписки в аккаунте для мобильных игр в разделе Монетизация > Подписки section.

На вкладке Subscriptions вы можете протестировать работу следующих вебхуков:

Проверка пользователей (user_validation)
Успешный платеж (payment)

Чтобы протестировать вебхуки:

В блоке тестирования перейдите на вкладку Subscriptions.
Заполните необходимые поля:
- ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
- ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
- Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если в вашем проекте в разделе Настройки проекта > Настройки интеграции установлен флажок Использовать public user ID.
- Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
- Валюта — выберите валюту из раскрывающегося списка.
- ID плана — план подписки. Выберите план из раскрывающегося списка.
- Продукт подписки — выберите продукт из раскрывающегося списка (необязательно). Список отображается, если в вашем проекте есть настроенные продукты.
- Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
- Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки, укажите значение 0.
Нажмите Протестировать.

В блоке тестирования перейдите на вкладку Subscriptions.
Заполните необходимые поля:
- ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
- ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
- Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если в вашем проекте в разделе Настройки проекта > Настройки интеграции установлен флажок Использовать public user ID.
- Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
- Валюта — выберите валюту из раскрывающегося списка.
- ID плана — план подписки. Выберите план из раскрывающегося списка.
- Продукт подписки — выберите продукт из раскрывающегося списка (необязательно). Список отображается, если в вашем проекте есть настроенные продукты.
- Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
- Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки, укажите значение 0.
Нажмите Протестировать.

В блоке тестирования перейдите на вкладку Subscriptions.
Заполните необходимые поля:
- ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
- ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
- Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если в вашем проекте в разделе Настройки проекта > Настройки интеграции установлен флажок Использовать public user ID.
- Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
- Валюта — выберите валюту из раскрывающегося списка.
- ID плана — план подписки. Выберите план из раскрывающегося списка.
- Продукт подписки — выберите продукт из раскрывающегося списка (необязательно). Список отображается, если в вашем проекте есть настроенные продукты.
- Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
- Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки, укажите значение 0.
Нажмите Протестировать.

В блоке тестирования перейдите на вкладку Subscriptions.
Заполните необходимые поля:
- ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
- ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
- Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если в вашем проекте в разделе Настройки проекта > Настройки интеграции установлен флажок Использовать public user ID.
- Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
- Валюта — выберите валюту из раскрывающегося списка.
- ID плана — план подписки. Выберите план из раскрывающегося списка.
- Продукт подписки — выберите продукт из раскрывающегося списка (необязательно). Список отображается, если в вашем проекте есть настроенные продукты.
- Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
- Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки, укажите значение 0.
Нажмите Протестировать.

В блоке тестирования перейдите на вкладку Subscriptions.
Заполните необходимые поля:
- ID пользователя — при тестировании вы можете указать любую комбинацию букв и цифр.
- ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.
- Public user ID — ID, который известен пользователю, например, email или никнейм. Это поле отображается, если в вашем проекте в разделе Настройки проекта > Настройки интеграции установлен флажок Использовать public user ID.
- Сумма — сумма платежа. При тестировании вы можете указать любое числовое значение.
- Валюта — выберите валюту из раскрывающегося списка.
- ID плана — план подписки. Выберите план из раскрывающегося списка.
- Продукт подписки — выберите продукт из раскрывающегося списка (необязательно). Список отображается, если в вашем проекте есть настроенные продукты.
- Invoice ID — ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр. Для успешной оплаты это не обязательный параметр, но вы можете передать его, чтобы связать ID транзакции на вашей стороне с ID транзакции на стороне Xsolla.
- Пробный период. Для тестирования покупки подписки без пробного периода или тестирования продления подписки, укажите значение 0.
Нажмите Протестировать.

На указанный URL-адрес придут вебхуки с введенными данными. Ниже кнопки Протестировать отобразятся результаты тестирования каждого вебхука как для успешного сценария, так и для случая возникновения ошибки.

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

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

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

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

Тестирование подписок с пробным периодом возможно только на реальных платежах, так как в тестовом окружении к подписке нельзя привязать платежный аккаунт.

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

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

Оплатить покупку в тестовом окружении возможно только тестовой банковской картой. Платежи могут проводиться в следующих валютах: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, 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.

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

Список тестовых карт.

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

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

Выполните тестирование вебхуков в аккаунте.
Подпишите Лицензионный договор.

Подписание Лицензионного договора активирует продажу реальных подписок.

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

Удалите из запроса на получение токена параметр “mode”:“sandbox” перед тем, как начать принимать реальные платежи.

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

Тестовые банковские карты подходят только для тестового окружения. Для реальных платежей рекомендуется использовать карты Visa и MasterCard.

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

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

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

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

Получите вебхуки Проверка существования пользователя, Успешный платеж и Изменение подписки на URL, который вы указали на этапе настройки вебхуков.
Выполните возврат платежа. Для этого в вашем аккаунте для мобильных игр перейдите в раздел Управление > Поддержка игроков > Поиск транзакций.
Выберите тестовую транзакцию и нажмите кнопку More (•••) в меню. Нажмите Refund в всплывающем меню (транзакция должна иметь статус Complete). Это отправит вебхуки Отмена подписки и Возврат платежа.

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

Доступно только для подписок без пробного периода.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Откройте ваш аккаунт для мобильных игр и перейдите в раздел Управление > Поддержка игроков > Поиск транзакций.
Найдите последние транзакции, которые нужно отменить.
Нажмите иконку More (•••). Нажмите Refund в всплывающем меню для получения вебхуков Отмена подписки и Возврат платежа.

Если подписка была оплачена несколько раз, необходимо отменить все платежи.

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

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

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

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

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

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

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

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

используйте аккаунт
используйте метод API

Через аккаунт

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

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

Через метод API

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

Спасибо за обратную связь!

Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.

Последнее обновление: 7 октября 2026

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

Содержание

Настройка через методы API
Настройка вебхуков
Тестирование вебхуков в Личном кабинете
Тестирование вебхуков в аккаунте
Тестирование покупки подписки
Тестирование продления подписки
Тестирование отмены подписки
Открытие платежного интерфейса в тестовом окружении