Как добавить подписки через Stripe: тарифы, пробный период, вебхуки и неудачные платежи

Чтобы добавить подписки через Stripe, создайте продукт с регулярной ценой в панели Stripe, отправляйте клиентов с сервера в Stripe Checkout в режиме подписки, а вебхук пусть сообщает приложению, когда каждый платёж проходит, не проходит, меняется или завершается. Храните статус подписки у пользователя и открывайте доступ по нему, а не по странице успеха. Добавьте кнопку «Управление оплатой», которая открывает размещённый клиентский портал Stripe: там люди смогут сменить карту, тариф и отменить подписку, и вам не придётся строить эти экраны.

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

Почему подписки сложнее разовых платежей

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

Ваши варианты

Для большинства приложений оптимальный выбор — Checkout плюс портал. Сравните провайдеров в гайде Stripe vs Paddle vs Lemon Squeezy, если вас беспокоит обработка налогов.

Сначала спланируйте цены в Stripe

В Stripe продукт — это то, что вы продаёте («Pro-тариф»), а цена — это то, как вы берёте плату за него («$20 в месяц», «$200 в год»). У одного продукта может быть несколько цен. Решите:

• Какие тарифы вы предлагаете и что каждый открывает в приложении
• Ежемесячно, ежегодно или оба варианта
• Будет ли пробный период и нужна ли карта заранее

Создайте продукты и цены в тестовом режиме и сохраните их ID — на них ссылается ваше приложение. Если цены ещё не определены, прочитайте как назначить цену SaaS-продукту и freemium или пробный период.

Жизненный цикл подписки, который нужно обрабатывать

В обзоре подписок Stripe перечислены возможные статусы. Для доступа важнее всего следующие:

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

События вебхуков, которые нужно обрабатывать

Правила обработчика из документации Stripe по вебхукам по-прежнему действуют: проверяйте подпись по сырому телу, быстро возвращайте 2xx, обрабатывайте дубликаты и события не по порядку, готовьтесь к повторам. Идею вебхука объясняет гайд что такое вебхук, а все правила подробно перечислены в гайде про оплату.

Пошагово

1. Создайте продукты и цены в тестовом режиме Stripe.
2. Добавьте секреты: секретный ключ, ID цен и позже секрет подписи вебхука. Никогда не кладите их во фронтенд-код.
3. Страница тарифов: кнопка каждого тарифа вызывает ваш сервер, который создаёт Checkout Session в режиме подписки для залогиненного пользователя. Передавайте ID пользователя, чтобы вебхук мог сопоставить платёж с аккаунтом.
4. Эндпоинт вебхука: проверяйте подписи и обрабатывайте события выше, обновляя одну запись подписки на пользователя.
5. Ограничивайте функции по сохранённому статусу и тарифу, проверяя это на сервере для каждого защищённого действия, а не только по скрытым кнопкам.
6. Клиентский портал: настройте его в панели Stripe (на какие тарифы можно переходить, можно ли отменять), затем добавьте кнопку «Управление оплатой», которая создаёт сессию портала на сервере и перенаправляет туда.
7. Неудачные платежи: в настройках биллинга Stripe выберите поведение повторов и то, что происходит после последней попытки. Показывайте баннер в приложении, пока статус past_due.
8. Протестируйте весь жизненный цикл, затем опубликуйте приложение и зарегистрируйте боевой вебхук.

Промпты для ИИ-конструктора

Добавь подписочный биллинг через Stripe. Тарифы: Starter (ID цены в STRIPE_PRICE_STARTER) и Pro (STRIPE_PRICE_PRO). Страница тарифов создаёт Checkout Session в режиме подписки на сервере с помощью STRIPE_SECRET_KEY, с ID залогиненного пользователя. Сохраняй у пользователя ID клиента Stripe, ID подписки, тариф и статус. Никогда не отдавай секретный ключ в браузер.

Добавь POST /api/stripe/webhook. Проверяй подпись через STRIPE_WEBHOOK_SECRET по сырому телу запроса. Обрабатывай checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted и customer.subscription.trial_will_end. Сохраняй ID обработанных событий, чтобы игнорировать дубликаты. Обновляй статус пользователя из объекта подписки, а не из порядка, в котором пришли события.

Открывай функции Pro на сервере: только когда статус active или trialing и тариф Pro. Когда статус past_due, показывай баннер «Платёж не прошёл, обновите карту». Добавь кнопку «Управление оплатой», которая открывает клиентский портал Stripe для этого пользователя.

Апгрейды, даунгрейды и пропорции

Когда клиент меняет тариф, Stripe в документации описывает пропорциональный перерасчёт (proration): новая цена применяется к оставшейся части текущего периода. Можно посмотреть такой перерасчёт заранее или отключить его. Если тарифы с одинаковым интервалом, даты списаний не меняются; при переходе с месячного на годовой дата списания переносится на день смены. Если позволить клиентам менять тариф в портале, логику писать не придётся, но в настройках портала решите, какие переходы разрешены.

Чек-лист тестирования

Используйте тестовый режим Stripe и тестовые карты и пройдите каждое состояние:

• Новая подписка открывает нужный тариф нужному пользователю
• Закрытие вкладки сразу после оплаты всё равно открывает доступ (доказывает, что вебхук работает)
• Отклонённая карта при регистрации ничего не открывает
• Неудачное продление переводит аккаунт в past_due и показывает баннер
• Обновление карты в портале возвращает статус active
• Апгрейд и даунгрейд правильно меняют функции
• Отмена в конце периода сохраняет доступ до даты окончания, затем убирает его
• Пользователи пробного периода получают доступ, напоминание и корректно переходят на платный тариф или теряют доступ
• Повторная отправка того же события вебхука ничего не меняет

Тестовые часы Stripe (test clocks) позволяют имитировать ход времени, чтобы проверить продления без ожидания месяц. Актуальные инструкции по их использованию смотрите в документации Stripe по тестированию.

Частые ошибки

• Открытие доступа на странице успеха. Клиент может заплатить и не дойти до неё. Используйте вебхук.
• Обработка только первого платежа. Продления, неудачи и отмены приходят позже, как события.
• Проверка статуса тарифа только на фронтенде. Любой может вызвать ваш API напрямую.
• Случайно несколько подписок у одного пользователя. Проверяйте, нет ли уже подписки, перед созданием новой Checkout Session, или отправляйте существующих клиентов в портал.
• Отзыв доступа при первом неудачном продлении. Карты отказывают по скучным причинам. Короткий льготный период с понятным баннером сохраняет клиентов.
• Забытый боевой вебхук. У тестового и боевого эндпоинтов разные секреты подписи.
• Игнорирование налогов и возвратов. Определите политику возвратов и проверьте налоговые обязательства с бухгалтером до запуска.

Подписки в Mythex

Приложения, созданные на Mythex, используют ваш собственный аккаунт Stripe и ключи; кнопки подключения Stripe в одно нажатие для вашего приложения нет. Добавьте тестовые ключи и ID цен как секреты проекта, используйте промпты, похожие на приведённые выше, и проверяйте тестовыми картами Stripe в Preview. Вебхукам нужен публичный URL приложения, поэтому публикуйте приложение до регистрации эндпоинта в Stripe и опубликуйте снова после перехода на боевые ключи, чтобы живое приложение их подхватило. См. принимать оплату через Stripe и обработка вебхуков в бэкенде. Для всего продукта вокруг биллинга смотрите как создать MVP SaaS.

Вопросы