Subscriptions / Как разрешить пользователю сменить план подписки

Как разрешить пользователю сменить план подписки

Примечание
Если вы хотите разрешить пользователю смену плана в проекте, для настройки корректной работы платежного интерфейса обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
Вы можете дать пользователю возможность сменить план подписки в следующем или в текущем периоде, а также разрешить менять план несколько раз в день.

Как это работает

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

Смена плана невозможна, если:
  • у пользователя уже есть активная подписка с планом, на который меняется текущий план;
  • подписка, которую пользователь хочет сменить, не находится в статусе Active;
  • план подписки, который пользователь хочет сменить, имеет тип Бесконечный план — такую подписку можно отменить только в указанный период возврата.
Примечание
Если в проекте настроены группы планов, смена плана может быть выполнена только внутри группы. Чтобы узнать подробнее о работе групп, изучите инструкцию Как настроить продукты подписки и группы планов.

Как настроить

  1. Откройте проект в Личном кабинете.
  2. Нажмите Subscriptions в боковом меню и перейдите в раздел Настройки.
  3. В разделе Изменение плана подписки установите переключатель Возможность выбрать другой план подписки в положение Вкл.
  4. По умолчанию смена плана разрешена со следующего периода. Чтобы разрешить смену плана в текущем периоде, выберите пункт Текущее время. При выборе этой опции план будет меняться сразу после подтверждения оплаты.
  5. Чтобы разрешить смену плана более одного раза в день, установите переключатель Возможность выбрать другой план подписки несколько раз в день в положение Вкл.
  6. При открытии платежного интерфейса используйте:

Открытие платежного интерфейса с помощью серверного метода создания токена

  1. Получите токен для открытия платежного интерфейса. При этом передайте в метод:
    • значение change_plan в параметре purchase.subscription.operation;
    • ID нового плана в параметре purchase.subscription.plan_id;
    • ID продукта подписки в параметре purchase.subscription.product_id, если вы используете продукты подписки. Для его получения обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
  2. Откройте платежный интерфейс одним из способов:

Открытие платежного интерфейса на странице управления подписками с помощью клиентского метода

Если в проекте настроен Xsolla Login, вы можете использовать клиентский метод получения ссылки на открытие платежного интерфейса. Возвращенная в ответе ссылка позволяет открыть платежный интерфейс на странице управления подписками, где пользователь сможет выбрать активную подписку и сменить ее.

Чтобы сделать это, в клиентской части вашего приложения реализуйте получение ссылки на платежный интерфейс с использованием HTTP POST-запроса https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/manage. Запрос к методу должен содержать заголовок Authorization: Bearer <client_user_jwt>, где <client_user_jwt> — JSON Web Token (JWT) пользователя — уникальный токен, закодированный по стандарту Base64. Используйте для его получения:

  • Методы API Register new user и Auth by username, если в вашем приложении используется авторизация по логину и паролю.
  • Метод API Auth via social network, если в вашем приложении используется авторизация через социальные сети.
В качестве path-параметра укажите projectId — ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта. В качестве query-параметра укажите country — страна пользователя в двухбуквенном обозначении согласно стандарту ISO 3166-1 alpha-2. Влияет на выбор локали и валюты. Если параметр не передается, страна определяется по IP-адресу пользователя.

При необходимости передайте дополнительные параметры для кастомизации платежного интерфейса.

Параметры тела запроса:

ПараметрТипОписание
plan_external_id
stringОбязательный. Внешний ID плана подписки. Вы можете найти этот параметр в Личном кабинете в разделе Subscriptions > Планы подписки.
settings
objectОбъект, содержащий настройки проекта.
settings.ui
objectОбъект с настройками интерфейса.
settings.ui.size
stringРазмер платежного интерфейса. В зависимости от требуемых размеров платежного интерфейса параметр может принимать следующие значения:
  • small: Наименьший размер платежного интерфейса. Используется в случаях, когда размеры окна строго ограничены (размер: 620 x 630 px).
  • medium: Рекомендуемый размер платежного интерфейса. Оптимален при открытии в lightbox (размер: 740 x 760 px).
  • large: Желательно открывать в новом окне/вкладке (размер: 820 x 840 px).
settings.ui.theme
stringВнешний вид интерфейса оплаты. Может принимать значения default (по умолчанию), default_dark или значение ID кастомизированной темы.
settings.ui.version
stringТип устройства. Может принимать значения desktop (по умолчанию) или mobile.
settings.ui.desktop
objectОбъект с данными настроек для desktop-версии.
settings.ui.desktop.header
objectОбъект с настройками header.
settings.ui.desktop.header.close_button
booleanПоказывать ли кнопку Закрыть в настольной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре settings.return_url. false по умолчанию.
settings.ui.desktop.header.is_visible
booleanДолжен ли хедер отображаться на странице оплаты.
settings.ui.desktop.header.is_visible.type
stringВнешний вид хедера. Может принимать значения compact (в этом случае название игры и ID пользователя не будут показываться в хедере) или normal.
booleanЕсли значение true, то логотип будет отображаться в header (необходимо сначала прислать файл с логотипом вашему персональному менеджеру).
settings.ui.desktop.header.visible_name
booleanДолжно ли название игры отображаться в хедере.
settings.ui.desktop.header.type
stringВнешний вид хедера. Может принимать значения compact (в этом случае название игры и ID пользователя не будут показываться в хедере) или normal.
settings.ui.mobile.mode
stringПользователь может совершить платеж только через сохраненные способы оплаты. Принимает значение saved_accounts.
booleanСкрывать или нет footer в мобильной версии платежного интерфейса.
settings.ui.mobile.header.close_button
booleanПоказывать ли кнопку Закрыть в мобильной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре settings.return_url. false по умолчанию.
settings.ui.mode
stringПлатежный интерфейс в режиме Личного кабинета. Принимает значение user_account. Хедер содержит только навигационное меню Личного кабинета; исключается возможность выбора предмета и оплата покупки; режим Личного кабинета доступен только в desktop-режиме.
settings.currency
stringПредпочтительная валюта платежа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
settings.external_id
stringID транзакции в игре. Должен быть уникальным для каждого платежа пользователя.
settings.payment_method
integerID способа оплаты. Список ID способов оплаты можно получить в Личном кабинете или с помощью метода API Список способов оплаты.
settings.return_url
stringПользователь будет перенаправлен на данную страницу после совершения платежа. Параметры user_id, foreigninvoice, invoice_id и status будут автоматически добавлены к ссылке.
settings.redirect_policy
objectНастройки политики редиректа (объект).
settings.redirect_policy.redirect_conditions
stringСтатус платежа, при котором пользователь перенаправляется на URL-адрес возврата после совершения платежа. Принимает значение none, successful, successful_or_canceled или any.
settings.redirect_policy.delay
integerЗадержка (в секундах), после которой пользователь автоматически перенаправляется на return URL.
settings.redirect_policy.status_for_manual_redirection
stringСтатус платежа, при котором пользователь перенаправляется на URL-адрес возврата после совершения платежа. Принимает значение none, successful, successful_or_canceled или any.
settings.redirect_policy.redirect_button_caption
stringТекст кнопки для ручного перенаправления.
Пример запроса:
Copy
Full screen
Small screen
curl -X 'POST' \
'https://subscriptions.xsolla.com​/api/user/v1/projects/{project_id}/subscriptions/manage?country=RU  ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'
{
  "settings": {
    "ui": {
      "size": "large",
      "theme": "string",
      "version": "desktop",
      "desktop": {
        "header": {
          "is_visible": true,
          "visible_logo": true,
          "visible_name": true,
          "type": "compact",
          "close_button": true
        }
      },
      "mobile": {
        "mode": "saved_accounts",
        "footer": {
          "is_visible": true
        },
        "header": {
          "close_button": true
        }
      },
      "license_url": "string",
      "mode": "user_account",
      "user_account": {
        "history": {
          "enable": true,
          "order": 1
        },
        "payment_accounts": {
          "enable": true,
          "order": 1
        },
        "info": {
          "enable": true,
          "order": 1
        },
        "subscriptions": {
          "enable": true,
          "order": 1
        }
      }
    },
    "currency": "str",
    "locale": "st",
    "external_id": "string",
    "payment_method": 1,
    "return_url": "string",
    "redirect_policy": {
      "redirect_conditions": "none",
      "delay": 0,
      "status_for_manual_redirection": "none",
      "redirect_button_caption": "string"
    }
  }
}

Пример ответа:

Copy
Full screen
Small screen
{
  "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
}
Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Оценить страницу
Оценить страницу
Что может сделать страницу еще лучше?

В другой раз

Спасибо за обратную связь!
Последнее обновление: 22 января 2024

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

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