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

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

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

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

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

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

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

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'

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

• Оплата подписки:
  • Проверка существования пользователя
  • Успешный платеж
  • Создание подписки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. Откройте платежный интерфейс. Для этого используйте ссылку https://secure.xsolla.com/paystation4/?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

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

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

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

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

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

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

Через метод API

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