Интеграция Stripe подключить SaaS: пошаговая инструкция

Ключевые цифры

Почему фиксированная подписка не работает

Традиционная модель SaaS (Free, Pro, Enterprise) со статичной подпиской была удобна в начало 2010-х годов, но не решает проблему переменных издержек, особенно для AI-сервисов и облачных приложений.

Ключевые проблемы:

• Пользователи потребляют ресурсы неравномерно: один генерирует 10 изображений в месяц, другой — 1000. При одной цене за подписку первый переплачивает, второй недоплачивает.
• Владелец несёт переменные издержки на вызовы внешних API (OpenAI, Image Generation, Video Processing), которые может не покрыть фиксированная стоимость подписки активного пользователя.
• Невозможно справедливо масштабировать цену: повышение тарифа оталкивает одних пользователей, снижение — недополучение выручки от других.
• Нет гибкости для пользователей, которые иногда нуждаются в дополнительных ресурсах, а иногда — в минимуме.

Решение — перейти на гибридную модель, где базовая подписка сочетается с кредитной системой. Это даёт справедливую цену для пользователя и предсказуемую выручку для владельца.

Гибридная модель: подписка + кредиты

Современный стандарт монетизации SaaS — сочетание двух источников дохода:

1. Подписка (основной доход)

• Даёт базовый доступ к сервису и включает ежемесячный пул кредитов. Например, Pro-план за $29/месяц включает 1000 кредитов.
• Кредиты списываются за действия: генерация изображения — 5 кредитов, запрос к языковой модели — 2 кредита, создание видео — 50 кредитов.
• Предсказуемая месячная выручка, покрывает базовые серверные расходы.

2. Дополнительные покупки (переменный доход)

• Кредитные пакеты — разовые покупки для пополнения баланса, если кредиты закончились раньше срока. Чем крупнее пакет, тем ниже цена за кредит: 500 кредитов за $9 (1.8¢/шт), 2000 кредитов за $29 (1.45¢/шт).
• Промоакции — скидки на первый месяц, годовая подписка дешевле на 2 месяца (годовая $290 вместо $348), промокоды для новых пользователей (WELCOME20 — скидка 20% на 3 месяца).

Эта модель работает не только для AI: кредитами могут быть любые действия — обработка документа, отправка сообщения, создание проекта, обращение в API третьей стороны.

Как технически работают платежи

Ключевой принцип: приложение никогда не работает с деньгами и данными карт напрямую. Это ответственность платёжного провайдера (Stripe).

Схема потока:

1. Пользователь инициирует платёж. В личном кабинете выбирает тариф, вводит промокод и нажимает «Перейти к оплате».
2. Stripe принимает данные карты. Приложение перенаправляет на защищённую страницу Stripe Checkout. Пользователь видит форму с указанным тарифом, скидкой, итоговой суммой.
3. Stripe обрабатывает платёж. Карта авторизуется, деньги резервируются (для подписок) или списываются (для одноразовых платежей).
4. Вебхук уведомляет приложение. После успешной оплаты Stripe сам отправляет HTTP POST-запрос в приложение с информацией о событии (тип: checkout.session.completed, ID сессии, ID покупателя, статус).
5. Приложение обновляет статус пользователя. Получив вебхук, приложение активирует подписку, начисляет кредиты, отправляет письмо подтверждения.

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

Приложение работает со следующими событиями:

• checkout.session.completed — платёж прошёл, активировать подписку или начислить пакет кредитов.
• customer.subscription.updated — пользователь изменил тариф, обновить доступ и пул кредитов.
• customer.subscription.deleted — пользователь отменил подписку, заблокировать доступ к платным функциям.
• invoice.payment_failed — платёж по подписке не прошёл (истекла карта, недостаточно средств), отправить уведомление пользователю.

Ready-to-use модуль OneShot Billing

Вместо того чтобы писать биллинг с нуля, используйте готовый модуль OneShot Billing. Он реализует полный цикл: создание тарифов, управление подписками, кредитные пакеты, промоакции, история платежей.

Основные сущности:

• Plans (Тарифы) — определяют доступ и пул кредитов. Каждый план содержит несколько ценовых периодов (месяц, квартал, год). Пример: Free (100 кредитов, $0/мес), Starter (1000 кредитов, $29/мес), Pro (5000 кредитов, $79/мес), Business (10000 кредитов, $199/мес).
• Promotions (Промоакции) — промокоды со скидкой в % или конкретной сумме. Можно привязать к плану (скидка только на Pro) или сделать глобальной. Настраивается срок действия (до какой даты промокод работает).
• Packages (Пакеты кредитов) — разовые покупки за пределами подписки. Набор вариантов: 100 кредитов ($2), 500 кредитов ($9), 2000 кредитов ($29). Чем больше пакет, тем ниже цена за кредит.
• Cost (Стоимость действий) — сколько кредитов стоит каждое действие. Настраивается в админке: генерация изображения = 5 кредитов, запрос GPT = 2 кредита, видео = 50 кредитов. Приложение проверяет баланс перед выполнением действия и списывает кредиты.
• Transactions и Invoices (Транзакции и счета) — автоматическая история: когда активирована подписка, когда куплен пакет, когда истекла подписка, скачиваемые счета в PDF.

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

Пошаговое подключение Stripe за 3 шага

Шаг 1. Создание тарифов в админке OneShot

1. Переходим в раздел Plans (Тарифы).
2. Создаём планы:
   • Free — 100 кредитов, $0.
   • Starter — 1000 кредитов, $29/месяц (или $290/год с скидкой 2 месяца).
   • Pro — 5000 кредитов, $79/месяц (или $790/год).
   • Business — 10000 кредитов, $199/месяц (по запросу).
3. Переходим в Promotions (Промоакции) и создаём код: WELCOME20 — скидка 20%, действует 3 месяца.
4. Переходим в Packages (Кредитные пакеты) и добавляем варианты: 500 кредитов за $9, 2000 кредитов за $29, 5000 кредитов за $69.

Шаг 2. Подключение Stripe

1. Регистрируемся на stripe.com, создаём аккаунт разработчика.
2. Включаем Test Mode (левый верхний угол).
3. Переходим в Developers → API keys и копируем:
   • Publishable key (начинается с pk_test_) — вставляем в фронтенд-конфиг для инициализации Stripe.js.
   • Secret key (начинается с sk_test_) — вставляем в серверную переменную окружения, никогда не публикуем в коде.
4. Переходим в Developers → Webhooks и нажимаем «Add endpoint».
5. Указываем URL вебхука из настроек OneShot (обычно вида https://yourdomain.com/api/webhooks/stripe).
6. Выбираем события: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.payment_failed.
7. Копируем Webhook Secret (начинается с whsec_) — используется для верификации подписи вебхука.
8. В панели OneShot вставляем все три ключа: Publishable, Secret, Webhook Secret.

Шаг 3. Тестовый платёж

1. Открываем приложение как обычный пользователь.
2. Переходим в Billing, выбираем тариф Pro (например), вводим промокод WELCOME20 (если нужно скидка).
3. Нажимаем «Upgrade» — перенаправляемся на Stripe Checkout.
4. Используем тестовую карту: 4242 4242 4242 4242, любую дату в будущем, любой CVC (например, 123).
5. После успешного платежа вебхук срабатывает, OneShot активирует подписку и начисляет 5000 кредитов в аккаунт пользователя.
6. Проверяем в админке: пользователь перешёл на тариф Pro, баланс кредитов обновился, в истории платежей видна транзакция.
7. Аналогично тестируем покупку кредитного пакета (используем ту же тестовую карту).

Переход на Live Mode: когда всё работает, в аккаунте Stripe просто переключаемся с Test Mode на Live Mode (правый верхний угол). В OneShot меняем тестовые ключи на живые (Publishable, Secret, Webhook Secret с префиксом pk_live_, sk_live_, whsec_live_). Биллинг сразу начнёт принимать настоящие платежи.

Гибкость и расширяемость архитектуры

OneShot Billing разработан с расчётом на расширение. Архитектура унифицирована: для каждого платёжного провайдера реализуется провайдер-адаптер с единым интерфейсом.

Текущие встроенные провайдеры:

• Stripe — самый популярный в SaaS и e-commerce (поддерживает карты, Apple Pay, Google Pay, локальные способы платежа в 150+ странах).
• PayPal — для тех, кто хочет предоставить альтернативу Stripe.
• Другие провайдеры добавляются по мере спроса.

Если нужен другой провайдер: вы даёте команду AI (например, Claude Code через CLI):

«По образцу провайдера Stripe в OneShot напиши провайдер для Paddle» или «Интегрируй Wise для платежей между странами»

AI читает код Stripe-провайдера, понимает интерфейс (какие методы нужны: init_session, handle_webhook, update_subscription, refund), и пишет аналогичный адаптер для нового провайдера. Остаток кода (Plans, Packages, Transactions) переиспользуется как есть.

Преимущества такой архитектуры:

• Добавление нового способа платежа занимает несколько часов, а не недель.
• Логика биллинга отделена от логики провайдера — не переписываем тариф и кредиты при смене платёжной системы.
• Легко AB-тестировать: одновременно предложить Stripe и PayPal, собрать статистику, выбрать лучший.

Вопросы и ответы

Главное