> ## 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 # Adicionar os pagamentos com Stripe Crie uma conta Stripe gratuita, um produto com um preço recorrente, uma chave secreta e o webhook assinado que concede entitlements após o checkout. ## Passo a passo para iniciantes Pré-requisitos: a app a correr em local (Online em 5 minutos) e uma base de dados migrada para contas reais (Configurar a base de dados). Precisa de um endereço de email para a conta Stripe — sem cartão e sem cobranças. Tudo neste guia acontece em modo de teste: dinheiro falso, números de cartão de teste, tentativas ilimitadas antes de entrar em produção. Terminologia rápida: o modo de teste é o sandbox da Stripe — o interruptor Test mode do painel mantém cada chave, produto e pagamento falsos até o desligar. Uma secret key (`sk_test_…`) é a palavra-passe do seu servidor junto da Stripe. Um produto com um preço é o que os clientes compram; um price id (`price_…`) nomeia-o no código. Um webhook é a Stripe a chamar o seu servidor quando um pagamento tem êxito ou uma assinatura muda, e o signing secret (`whsec_…`) prova que a chamada vem mesmo da Stripe. O que cria: uma conta Stripe, um produto com um preço recorrente, uma chave de API secreta e um endpoint de webhook — cerca de vinte minutos. A Stripe aloja a própria página de checkout; o kit cria a sessão no servidor e redireciona, por isso não é precisa nenhuma publishable key de browser. Tenha o âmbito em mente: este guia vende apenas assinaturas web. As compras dentro da app iOS/Android têm de passar pela faturação da Apple e da Google — nunca pelo Stripe Checkout — e é por isso que o mobile usa RevenueCat. [Configurar a base de dados](https://supastack.dev/pt/docs/web/setup-database.md) [Configurar o RevenueCat para as compras mobile](https://supastack.dev/pt/docs/mobile/revenuecat.md) ## Criar a conta Stripe 1. Abra [stripe.com](https://stripe.com) → Start now e registe-se com o seu email. 2. A integração pergunta pelo seu negócio — em modo de teste pode saltar todas as perguntas e mesmo assim usar o sandbox completo; conclua a ativação só antes de aceitar pagamentos reais. Esperado: chega ao painel com o interruptor Test mode visível no cabeçalho. Mantenha-o ligado para tudo o que segue — as chaves live vão mais tarde para o seu secret store de produção, nunca para um ficheiro env do portátil. ## Copiar as chaves de API 1. No painel abra Developers → API keys. 2. Vê duas chaves de teste: uma Publishable key `pk_test_…` e uma Secret key mascarada. Clique em Reveal test key junto ao segredo e copie o valor `sk_test_…`. O kit só precisa da secret key: as sessões de checkout são criadas no servidor e o utilizador é redirecionado para a página alojada da Stripe, por isso nenhuma publishable key chega às variáveis env. Se um produto que construir mais tarde adicionar Stripe.js, usaria a publishable key no cliente; o fluxo de faturação do kit não o faz. A chave `sk_test_…` é uma credencial completa para a conta sandbox: vive em `apps/web/.env.local` ou num secret store, nunca em variáveis `NEXT_PUBLIC_`/`EXPO_PUBLIC_` e nunca no Git. ## Criar o produto e o preço 1. Abra Product catalog → Add product. 2. Dê-lhe o nome do seu plano — `Pro` corresponde ao plano incluído do kit — dê-lhe um preço e escolha Recurring (mensal, por exemplo): o checkout do kit cria sessões em modo de assinatura, que exigem um preço recorrente, não um pagamento único. 3. Guarde, abra o produto e copie o price id — começa com `price_…` (não `prod_…`, que é o id do produto). O plano `pro` incluído já mostra um alternador Monthly/Yearly: o mensal paga com `STRIPE_PRICE_ID`, e a opção anual precisa de um segundo preço recorrente em `STRIPE_PRICE_ID_PRO_YEARLY` — sem ele, um checkout anual falha com `price-unconfigured`. Mude os nomes de planos, os montantes e o que uma compra concede em `apps/web/src/product-plans.ts` — a Stripe guarda o lado do dinheiro, o ficheiro de planos guarda o lado do entitlement. ## Adicionar o endpoint de webhook O webhook é o que realmente concede o acesso: o kit só ativa o entitlement depois de chegar um evento assinado da Stripe, por isso um redirecionamento de checkout sozinho não prova nada. 1. Abra Developers → Webhooks → Add endpoint. 2. Endpoint URL: o seu URL público mais `/api/billing/webhook` — por exemplo `https://yourdomain.com/api/billing/webhook`. Os outros provedores de faturação têm o seu próprio caminho debaixo desse diretório; o recetor da Stripe vive na raiz. 3. Em Select events escolha os eventos que o kit trata: `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed`, `invoice.paid`, `invoice.payment_failed`, `customer.subscription.created`, `customer.subscription.updated` e `customer.subscription.deleted`. 4. Crie o endpoint, abra a sua página, clique em Reveal em Signing secret e copie o valor `whsec_…` — cada endpoint tem o seu próprio segredo. O desenvolvimento local não consegue receber os servidores da Stripe, por isso use a Stripe CLI: `stripe login` uma vez, depois `stripe listen --forward-to localhost:3000/api/billing/webhook` num segundo terminal. Ela imprime um `whsec_…` temporário — esse valor, não o do painel, vai para `.env.local` enquanto `stripe listen` corre. ## Adicionar os valores à app Preencha as linhas abaixo em `apps/web/.env.local`. `BILLING_PROVIDER=stripe` seleciona o adaptador; as outras três são a chave, o preço e o signing secret. Ativar o provedor com alguma delas em falta faz o arranque falhar e nomeia a variável. Os três valores `STRIPE_*` são apenas do servidor — nunca `NEXT_PUBLIC_`/`EXPO_PUBLIC_`, nunca commitados; a produção recebe-os através do gestor de segredos do hosting (o guia de implementação cobre o Secret Manager). Reinicie o servidor de desenvolvimento depois de editar. ``` # 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 ``` ## Verificar e resolver problemas Arranque `stripe listen --forward-to localhost:3000/api/billing/webhook` e deixe-o a correr, reinicie o servidor de desenvolvimento, depois abra `/billing`, escolha o plano Pro e conclua o checkout alojado da Stripe com o cartão de teste `4242 4242 4242 4242`, qualquer validade futura e qualquer CVC. Esperado: a app regressa a `/billing?checkout=success` e o entitlement do workspace passa a ativo — o terminal de listen regista os eventos entregues, e Developers → Webhooks → o seu endpoint no painel mostra entregas verdes. Para exercitar o recetor sem clicar pelo checkout, `stripe trigger checkout.session.completed` envia um evento sintético através do reencaminhador de listen. Falhas comuns: um 400 em cada entrega significa que o signing secret não corresponde a esse endpoint — copie novamente o `whsec_…` do endpoint certo e atualize o env; não-operações silenciosas significam que `BILLING_PROVIDER` ainda é `local`; e chaves `sk_live_` misturadas numa montagem de teste significam que copiou as chaves do modo errado — mantenha test e live estritamente separados. O kit inclui o mesmo adaptador de contrato único para Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo e PayPal — mesmo fluxo, consola e nomes env diferentes — e as compras mobile ficam na RevenueCat, não na Stripe. [Comparar os provedores de faturação](https://supastack.dev/pt/docs/web/setup-payments.md) [Adicionar a seguir o email com Resend](https://supastack.dev/pt/docs/web/resend-email.md) [As compras mobile usam RevenueCat](https://supastack.dev/pt/docs/mobile/revenuecat.md) Para continuar a configuração, leia [Adicionar o email com Resend](https://supastack.dev/pt/docs/web/resend-email.md). ## Seguinte [Adicionar o email com Resend](https://supastack.dev/pt/docs/web/resend-email.md)