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 /pt/docs/web/stripe-payments.md (or send Accept: text/markdown).
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.
Criar a conta Stripe
1. Abra 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 toggleVerificar 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.