Подписки

Подписки подходят для сервисов, где клиент регулярно платит за доступ: каждый месяц, раз в квартал или раз в год.

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

Как работают подписки

Вы создаёте тариф и назначаете его приложению.
Клиент выбирает тариф и принимает условия регулярных списаний.
Gigma создаёт checkout и возвращает ссылку на оплату.
После успешного платежа появляется подписка и сохраняется способ оплаты.
Перед окончанием оплаченного периода Gigma запускает следующее списание. Новый период начинается от конца предыдущего, поэтому оплаченные дни не теряются.
Клиент может сменить тариф или способ оплаты, отменить подписку и возобновить её.

Клиент ──> каталог тарифов ──> checkout ──> платёжная страница
                                                │
                                                ▼
                                       подписка в Gigma
                                                │
                           ┌────────────────────┴────────────────────┐
                           ▼                                         ▼
                    успешное списание                       списание не прошло
                    новый период                            повторные попытки

Подготовка

До первого запроса настройте пять вещей:

Что нужно	Для чего	Где настроить
`Application` и App Token	определить сайт или приложение, которому принадлежат тарифы и подписки	приложения
Вход клиента	получить Bearer-токен клиента для оформления и управления подпиской	вход клиента
Платёжный склад	подключить платёжную интеграцию и принимать оплату	склады
Тариф-подписка	задать цену и период списания	настройка подписок
Согласие на автосписание	подтвердить регулярный платёж перед оформлением, сменой условий и возобновлением	передавайте `autopay_consent: true` после явного согласия клиента

У новых приложений subscription_catalog_configured включён сразу. Пока вы не назначили приложению хотя бы один активный тариф, его каталог будет пустым.

Авторизация

У подписок есть клиентская и административная стороны. Не смешивайте их токены.

Задача	Авторизация	Префикс API
Показать публичный каталог тарифов	App Token	`/api/counterparty/subscription-catalog`
Оформить или изменить подписку от имени клиента	App Token + Bearer клиента	`/api/counterparty/subscriptions`
Посмотреть подписки в платформе	Bearer сотрудника	`/api/tables/subscriptions`, `/api/subscriptions/{id}`

Административные методы только читают данные. Создание, смена тарифа, отмена, возобновление и работа со способом оплаты выполняются в клиентском контуре.

Статусы подписки

Статус	Что означает	Что показать клиенту
`active`	подписка оплачена и действует до `current_period_end`	доступ активен, покажите дату следующего продления
`charging`	Gigma выполняет списание	«Оплата обрабатывается», не запускайте второй платёж и не открывайте доступ по этому статусу
`past_due`	оплаченный период закончился, списание не прошло	доступ закрыт, попросите проверить способ оплаты или повторить платёж
`canceled`	подписка отменена и автоматические списания отключены	доступ закрыт; покажите кнопку возобновления, если оно доступно

При добровольной отмене статус меняется на canceled сразу. Поле current_period_end может оставаться в будущем как дата ранее оплаченного периода, но само по себе оно не делает отменённую подписку действующей.

Как проверять доступ

Возврат клиента с платёжной страницы не подтверждает оплату. После checkout получите подписки методом GET /api/counterparty/subscriptions и проверьте состояние на своём backend.

Считайте подписку действующей, только если одновременно выполняются два условия:

const accessAllowed =
	subscription.status === 'active' &&
	new Date(subscription.current_period_end).getTime() > Date.now();

При charging, past_due или canceled доступ не выдавайте. latest_payment.status = "succeeded" тоже не заменяет эту проверку: последний платёж мог пройти, а оплаченный период — уже закончиться.

Повторяйте проверку на backend перед каждым защищённым действием. Проверка во frontend нужна только для правильного состояния интерфейса и не защищает данные.

Если списание не прошло

Gigma начинает продление за два дня до конца периода и проверяет подписки каждый час.

Пока оплаченный период не закончился, подписка остаётся active, а следующая попытка назначается через пять часов.
После окончания периода подписка переходит в past_due. Повторные попытки продолжаются ещё три дня.
Если оплату так и не удалось получить, подписка переходит в canceled.

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

С чего начать

Создайте тариф и назначьте его приложению.
Получите каталог тарифов и покажите его клиенту.
Оформите первую подписку через checkout.
Добавьте в личный кабинет изменение и отмену, историю платежей и смену способа оплаты.

Разделы

Задача	Раздел
Показать доступные тарифы	Каталог тарифов
Принять первый платёж или списать с сохранённого способа оплаты	Оформление подписки
Сменить тариф, отменить или возобновить подписку	Изменение и отмена
Показать историю списаний и повторить неуспешный платёж	Платежи подписки
Показать, отвязать или заменить способ оплаты	Карты клиента
Создать тарифы и наблюдать за подписками из платформы	Настройка подписок

Что делает Gigma

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

Что остаётся на вашей стороне

тексты оферты и согласия на регулярные списания;
интерфейс выбора тарифа и личный кабинет;
серверная проверка подписки перед выдачей платных функций;
сообщения клиенту при отказе оплаты.