For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ru/docs/web/stripe-payments.md (or send Accept: text/markdown).

Добавьте платежи Stripe

Создайте бесплатный аккаунт Stripe, продукт с периодической ценой, секретный ключ и подписанный webhook, выдающий entitlement после оформления заказа.

Задать вопрос об этом руководстве

Прохождение для начинающих

Предварительные условия: приложение работает локально (Запуск за 5 минут) и мигрированная база данных для реальных аккаунтов (Настройка базы данных). Нужен адрес электронной почты для аккаунта Stripe — ни карты, ни списаний. Всё в этом руководстве происходит в тестовом режиме: фиктивные деньги, номера тестовых карт, неограниченные повторы перед выходом в онлайн.

Кратко о терминах: тестовый режим — это песочница Stripe — переключатель Test mode на дашборде держит каждый ключ, продукт и платёж фиктивными, пока вы его не выключите. Секретный ключ (sk_test_…) — пароль вашего сервера к Stripe. Продукт с ценой — то, что покупают клиенты; price id (price_…) называет его в коде. Webhook — это вызов Stripe к вашему серверу, когда платёж успешен или подписка меняется, а секрет подписи (whsec_…) доказывает, что вызов действительно идёт от Stripe.

Что вы создаёте: аккаунт Stripe, один продукт с периодической ценой, секретный API-ключ и endpoint webhook — около двадцати минут. Stripe сам хостит страницу оформления заказа; комплект создаёт сессию на стороне сервера и перенаправляет, поэтому публичный браузерный ключ не нужен.

Держите в уме рамки: это руководство продаёт только веб-подписки. Покупки внутри iOS/Android-приложения должны идти через биллинг Apple и Google — никогда через Stripe Checkout — вот почему мобильные используют RevenueCat.

Создание аккаунта Stripe

1. Откройте stripe.com → Start now и зарегистрируйтесь со своей почтой.

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

Ожидается: вы попадаете на дашборд с видимым переключателем Test mode в шапке. Держите его включённым для всего ниже — живые ключи позже попадут в ваше продакшен-хранилище секретов, никогда в env-файл ноутбука.

Копирование API-ключей

1. На дашборде откройте Developers → API keys.

2. Вы видите два тестовых ключа: Publishable key pk_test_… и замаскированный Secret key. Нажмите Reveal test key рядом с секретным и скопируйте значение sk_test_….

Комплекту нужен только секретный ключ: сессии оформления заказа создаются на сервере, а пользователь перенаправляется на хостинг-страницу Stripe, поэтому публичный ключ не попадает в env-переменные. Если продукт, который вы построите позже, добавит Stripe.js, вы использовали бы публичный ключ на клиенте; биллинг-поток комплекта этого не делает.

Ключ sk_test_… — полный креденшел для песочного аккаунта: он живёт в apps/web/.env.local или хранилище секретов, никогда в переменных NEXT_PUBLIC_/EXPO_PUBLIC_ и никогда в Git.

Создание продукта и цены

1. Откройте Product catalog → Add product.

2. Назовите его в честь вашего плана — Pro совпадает с поставляемым планом комплекта — дайте ему цену и выберите Recurring (например, ежемесячно): оформление заказа комплекта создаёт сессии в режиме подписки, которым нужна периодическая цена, а не разовая.

3. Сохраните, откройте продукт и скопируйте price id — он начинается с price_… (не prod_…, это id продукта).

Поставляемый план pro уже показывает переключатель Monthly/Yearly: месячный оформляется с STRIPE_PRICE_ID, а годовой опции нужна вторая периодическая цена в STRIPE_PRICE_ID_PRO_YEARLY — без неё годовое оформление падает с price-unconfigured. Меняйте названия планов, суммы и то, что даёт покупка, в apps/web/src/product-plans.ts — Stripe хранит денежную сторону, файл планов хранит сторону entitlement.

Добавление endpoint webhook

Webhook — это то, что реально выдаёт доступ: комплект переворачивает entitlement только после прибытия подписанного события Stripe, поэтому одно перенаправление оформления ничего не доказывает.

1. Откройте Developers → Webhooks → Add endpoint.

2. Endpoint URL: ваш публичный URL плюс /api/billing/webhook — например, https://yourdomain.com/api/billing/webhook. Другие биллинг-провайдеры получают собственный путь внутри этой директории; приёмник Stripe живёт в корне.

3. В Select events выберите события, которые обрабатывает комплект: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated и customer.subscription.deleted.

4. Создайте endpoint, откройте его страницу, нажмите Reveal под Signing secret и скопируйте значение whsec_… — у каждого endpoint свой секрет.

Локальная разработка не может принимать серверы Stripe, поэтому используйте вместо этого Stripe CLI: один раз stripe login, затем stripe listen --forward-to localhost:3000/api/billing/webhook во втором терминале. Он печатает временный whsec_… — именно это значение, а не дашбордовское, попадает в .env.local, пока работает stripe listen.

Добавьте значения в приложение

Установите строки ниже в apps/web/.env.local. BILLING_PROVIDER=stripe выбирает адаптер; остальные три — ключ, цена и секрет подписи. Включение провайдера с любым из них отсутствующим роняет запуск и называет переменную.

Все три значения STRIPE_* — только для сервера — никогда NEXT_PUBLIC_/EXPO_PUBLIC_, никогда в коммитах; продакшен получает их через менеджер секретов хоста (руководство по развёртыванию описывает Secret Manager). Перезапустите dev-сервер после редактирования.

# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_…   # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_…   # required for the shipped Yearly toggle

Проверка и устранение неполадок

Запустите stripe listen --forward-to localhost:3000/api/billing/webhook и оставьте работать, перезапустите dev-сервер, затем откройте /billing, выберите план Pro и завершите хостинг-оформление Stripe тестовой картой 4242 4242 4242 4242, любой будущей датой и любым CVC.

Ожидается: приложение возвращается на /billing?checkout=success, и entitlement воркспейса переворачивается в активный — терминал listen логирует доставленные события, а Developers → Webhooks → ваш endpoint на дашборде показывает зелёные доставки.

Чтобы проверить приёмник без кликов по оформлению, stripe trigger checkout.session.completed отправляет синтетическое событие через форвардер listen.

Частые сбои: 400 на каждую доставку означает, что секрет подписи не соответствует этому endpoint — перекопируйте whsec_… для правильного endpoint и обновите env; тихие пустышки означают, что BILLING_PROVIDER всё ещё local; а ключи sk_live_, затесавшиеся в тестовую установку, означают, что вы скопировали ключи не того режима — держите тест и продакшен строго раздельными.

Комплект поставляет тот же одноконтрактный адаптер для Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo и PayPal — тот же поток, другая консоль и имена env — а мобильные покупки остаются на RevenueCat, не Stripe.