> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Добавьте платежи 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.

[Настройте базу данных](https://supastack.dev/ru/docs/web/setup-database.md)

[Настройте RevenueCat для мобильных покупок](https://supastack.dev/ru/docs/mobile/revenuecat.md)


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

1. Откройте [stripe.com](https://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.

[Сравните биллинг-провайдеров](https://supastack.dev/ru/docs/web/setup-payments.md)

[Далее добавьте почту Resend](https://supastack.dev/ru/docs/web/resend-email.md)

[Мобильные покупки используют RevenueCat](https://supastack.dev/ru/docs/mobile/revenuecat.md)


Чтобы продолжить настройку, прочитайте [Добавьте почту Resend](https://supastack.dev/ru/docs/web/resend-email.md).


## Вперёд

[Добавьте почту Resend](https://supastack.dev/ru/docs/web/resend-email.md)