Как добавить оплату в приложение: Checkout, подписки и вебхуки

Самый простой способ добавить оплату в приложение — Stripe: используйте Payment Link (платёжную ссылку), если нужна только кнопка «Купить» и заказы вы можете обрабатывать вручную; Stripe Checkout, если приложению нужно знать, кто заплатил, и реагировать автоматически; а для регулярных списаний — Checkout в режиме подписки плюс клиентский портал Stripe. Во всех случаях, кроме самого простого, вам также понадобится вебхук — серверный эндпоинт, который Stripe вызывает при успешном платеже. И всё нужно проверить тестовыми ключами и тестовыми картами, прежде чем переходить на боевые ключи.

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

Зачем вообще нужен платёжный провайдер

Никогда не собирайте номера карт в собственных формах. Работа с сырыми данными карт подпадает под требования PCI DSS (стандарта безопасности индустрии платёжных карт) и создаёт серьёзную ответственность. Платёжный провайдер вроде Stripe сам размещает платёжную форму, хранит карту, проводит аутентификацию в банке и сообщает вашему приложению результат. Приложение видит только «клиент X оплатил Y».

Этот гайд использует Stripe, потому что он широко распространён, хорошо документирован и поддерживается большинством ИИ-конструкторов приложений. Есть и другие провайдеры; некоторые работают как «merchant of record» и берут на себя обработку налога с продаж. Если налоговое соответствие вас беспокоит, эту модель стоит сравнить.

Три способа принимать оплату через Stripe

Payment Links

Payment Link — это страница оплаты, размещённая на стороне Stripe, которую вы создаёте в панели Stripe без кода. Вы получаете URL, который можно поставить за кнопку в приложении, отправить в письме или показать как QR-код. По документации Stripe, Payment Links могут продавать товар, подписку или принимать пожертвования, а вы можете позволить клиентам выбирать сумму или ограничить число покупок.

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

Stripe Checkout

Checkout — это страница оплаты, которую ваш сервер создаёт по запросу для конкретной покупки. Сервер сообщает Stripe, что покупается (и, при желании, какой клиент покупает), Stripe возвращает URL, и вы отправляете клиента туда. По документации Stripe, Checkout поддерживает как разовые платежи, так и подписки, и может работать как полная страница Stripe, как страница, встроенная в ваш сайт, или как встроенная форма.

Поток выглядит так:

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

Шаг 2 должен выполняться на сервере, потому что он использует ваш секретный ключ. Это главная причина, почему Checkout требует бэкенда.

Подписки

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

Для того, чтобы клиенты сами управляли подпиской, Stripe предлагает размещённый клиентский портал. По документации Stripe, клиенты могут там обновить способ оплаты и платёжные данные, изменить или отменить подписку, посмотреть и скачать счета. Вы настраиваете портал в панели Stripe и добавляете кнопку «Управление оплатой», которая отправляет клиента туда. Так не нужно самостоятельно строить эти экраны.

Вебхуки: то, что нельзя пропустить

Вебхук — это HTTP-запрос, который Stripe отправляет на ваш сервер, когда что-то происходит. (Общее понимание см. в гайде что такое вебхук.) В руководстве Stripe по выполнению заказов прямо сказано: нельзя полагаться только на страницу успеха, потому что клиент может заплатить и потерять соединение до её загрузки. Для подписок и отложенных способов оплаты вебхуки обязательны.

События, которые стоит обрабатывать

Правила для корректного обработчика вебхуков

Эти правила взяты прямо из документации Stripe по вебхукам, и сгенерированные ИИ обработчики иногда их пропускают:

• Проверяйте подпись. Каждое событие содержит заголовок Stripe-Signature. Обработчик проверяет его по секрету подписи эндпоинта (он начинается с whsec_). Без этого кто угодно мог бы отправить вашему серверу фальшивое «платёж прошёл».
• Используйте сырое тело запроса. Проверка подписи не сработает, если фреймворк сначала разберёт или изменит тело.
• Быстро возвращайте ответ 2xx, а медленную работу делайте потом. Таймауты считаются ошибками.
• Обрабатывайте дубликаты. Stripe может доставить одно и то же событие больше одного раза. Записывайте ID обработанных событий или делайте выполнение безопасным при повторе.
• Не полагайтесь на порядок. Stripe не гарантирует, что события придут в том порядке, в котором произошли.
• Готовьтесь к повторам. В боевом режиме Stripe повторяет неудачные доставки до трёх дней, поэтому короткий сбой не потеряет платежи, но обработчик должен справляться с опоздавшими событиями.

Вебхукам нужен публичный HTTPS-адрес, поэтому они обычно работают только после публикации приложения (CLI Stripe может пересылать события на локальную машину разработчика).

Промпт, который покрывает весь поток

Добавь разовую покупку через Stripe Checkout для «Pro-пакета» (ID цены в STRIPE_PRICE_ID). Создавай Checkout Session на сервере, используя STRIPE_SECRET_KEY из секретов, и включай в сессию ID залогиненного пользователя. Добавь эндпоинт POST /api/stripe/webhook, который проверяет подпись Stripe с помощью STRIPE_WEBHOOK_SECRET по сырому телу запроса, обрабатывает checkout.session.completed и отмечает этого пользователя как имеющего Pro-пакет. Сделай так, чтобы повторное получение того же события было безопасным. Страницы успеха и отмены. Никогда не отдавай секретный ключ в браузер.

Для подписок добавьте: «Используй режим подписки с STRIPE_PRICE_ID. Обрабатывай invoice.paid, invoice.payment_failed, customer.subscription.updated и customer.subscription.deleted. Добавь кнопку „Управление оплатой“, которая открывает клиентский портал Stripe.»

Тестовый режим

У Stripe есть отдельные тестовые (sandbox) и боевые среды с отдельными ключами. Тестовые ключи начинаются с pk_test_, sk_test_ или rk_test_; боевые — с pk_live_, sk_live_ или rk_live_. Тестовые транзакции не переводят деньги.

Полезные тестовые карты из документации Stripe по тестированию (любая будущая дата, любой трёхзначный CVC):

Проверьте как минимум:

• Успешный платёж открывает нужное для нужного пользователя
• Отклонённая карта показывает понятное сообщение и ничего не открывает
• Закрытие вкладки сразу после оплаты всё равно даёт доступ (это доказывает, что работает вебхук, а не только страница успеха)
• Отмена на странице Stripe возвращает пользователя в приложение без списания
• Для подписок: отмена в клиентском портале, и доступ прекращается тогда, когда должен

Запуск в боевом режиме

1. Активируйте аккаунт Stripe с данными о бизнесе и банковском счёте.
2. Подставьте боевые ключи в секреты приложения. Stripe рекомендует ограниченные ключи только с теми правами, которые нужны интеграции, а не неограниченный секретный ключ.
3. Создайте боевой эндпоинт вебхука, указывающий на опубликованное приложение. У него свой секрет подписи, отличный от тестового, — обновите его.
4. Пересоздайте продукты и цены в боевом режиме: ID из тестового режима там не существуют.
5. Сделайте одну реальную небольшую покупку и оформите возврат.

Храните все ключи в секретах проекта, никогда в коде или в чате. Наш чек-лист безопасности подробнее разбирает ключи и проверку вебхуков.

Налоги, возвраты и бумаги

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

• Налог с продаж, НДС и GST. В зависимости от того, где находитесь вы и ваши клиенты, может понадобиться регистрация, начисление и подача отчётности. Stripe Tax может рассчитывать и собирать налог на оплате, отслеживать, где ваши продажи могут создать обязательство, и помогать с регистрацией и отчётностью, но ответственность остаётся за вами. Альтернативой являются merchant-of-record провайдеры, которые берут на себя больше этих задач.
• Возвраты и споры. Определите политику возвратов до запуска и разместите её на сайте. Споры (чарджбэки) случаются; храните записи о том, что было куплено и выдано.
• Чеки и счета. Stripe может отправлять чеки по email; бизнесу могут понадобиться полноценные счета.
• Комиссии. Любой провайдер берёт плату за транзакцию. Смотрите актуальные тарифы на странице провайдера, а не полагайтесь на цифры из статей.

Какая схема подходит вашему приложению

• Пожертвования или несколько товаров: Payment Links. См. как создать сайт для пожертвований некоммерческой организации.
• Магазин с корзиной: Checkout с позициями заказа и вебхуком. См. как создать интернет-магазин.
• SaaS или членство: Checkout в режиме подписки, вебхуки и клиентский портал. См. как создать MVP SaaS и как назначить цену SaaS-продукту.
• Маркетплейс, выплачивающий продавцам: другая, более регулируемая схема (Stripe Connect или аналоги). Планируйте её отдельно.

Оплата в Mythex

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

1. Получите тестовые ключи Stripe.
2. Добавьте STRIPE_SECRET_KEY (а позже секрет вебхука) в секреты проекта — через /secrets, настройки проекта или карточку секретов, которую агент показывает, когда нужен ключ.
3. Попросите агента сделать Checkout по промпту, похожему на приведённый выше.
4. Проверьте в Preview тестовыми картами. Опубликуйте приложение до регистрации вебхука, так как ему нужен публичный URL.
5. После перехода на боевые ключи опубликуйте приложение снова, чтобы оно подхватило их.

См. принимать оплату через Stripe и обработка вебхуков в бэкенде в документации.

Вопросы