> ## 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

# Pagamentos e subscrições

Checkout Stripe, gestão de planos e a fronteira de entitlements.

## Escolha e teste seu serviço de pagamento

O faturamento trata dos pagamentos. As permissões de acesso são armazenadas separadamente como autorizações. Conclua a configuração da conta persistente e abra /faturamento no aplicativo Web em execução para ver a interface do plano. Com BILLING_PROVIDER=local, você explora o comportamento local em vez de coletar dinheiro real.

Escolha um provedor de pagamento compatível, siga seu guia de configuração, crie seu próprio produto de teste e preço e copie as configurações do servidor nomeado em apps/web/.env.local. Salve e reinicie o servidor Web. Conclua uma verificação usando as instruções de sandbox desse provedor e, em seguida, inspecione o estado de acesso do workspace após a chegada do webhook do provedor. Um webhook é a mensagem assinada pelo provedor ao seu servidor sobre um evento de pagamento.

Uma página de sucesso por si só não desbloqueia recursos. Se a finalização da compra for concluída, mas o acesso permanecer inativo, verifique a entrega do webhook do provedor e o processamento de eventos do seu servidor antes de repetir o pagamento. Cancelamento de teste e acesso expirado também. As compras por telefone usam a configuração RevenueCat/loja separada, não esta finalização pela Web.

[Escolha um adaptador de faturamento e suas configurações](https://supastack.dev/pt/docs/modules/billing-configuration.md)

[Defina seus próprios produtos e preços](https://supastack.dev/pt/docs/web/project-structure.md)

[Configure o Stripe em um ambiente de teste](https://supastack.dev/pt/docs/web/setup-payments.md)


## Faturação web

O aplicativo da Web oferece suporte ao provedor de cobrança selecionado com BILLING_PROVIDER; Stripe é uma opção. Abertura/faturamento para planos Web e gerenciamento de assinaturas. Siga o guia do provedor selecionado para definir suas credenciais somente de servidor, IDs de produto ou preço e configurações de verificação de webhook no teste correspondente ou no ambiente ativo.


## Autoriza através de permissões

Um redirecionamento de checkout não é prova de acesso ativo. A permissão do servidor decide se um workspace pode usar uma capacidade paga. Verifica essa permissão na fronteira da ação mesmo quando a interface já esconde a ação.


## Verifica o ciclo de vida

Usa eventos sandbox para verificar ativação, atualizações, cancelamento e processamento de webhooks. Mantém eventos repetidos seguros e garante que uma permissão inativa bloqueia operações pagas. Compras nativas mobile continuam a ser uma fronteira de integração RevenueCat separada.


## Instalação e configuração

O catálogo de planos vive em src/product-plans.ts e orienta a superfície /billing e o passo de onboarding /choose-plan. A faturação configura-se no servidor com BILLING_PROVIDER=stripe, STRIPE_SECRET_KEY, os price ids por plano e intervalo, e STRIPE_WEBHOOK_SECRET. O Lemon Squeezy está disponível como adaptador alternativo.

Os planos baseados em assentos usam os seletores editáveis de assentos (src/seat-count.ts); a quantidade segue com a sessão de checkout para que os assentos cobrados correspondam ao workspace. Os planos também podem declarar meteredUsage em src/product-plans.ts para que a tarefa horária billing.usage-report envie os deltas de usage_counter aos medidores de cobrança da Stripe, enquanto os proprietários do workspace definem orçamentos mensais de IA e tetos rígidos por medidor em Configurações → Uso (USAGE_METERS em src/usage-meters.ts).

```
Checkout: POST /api/billing/checkout
Portal:   POST /api/billing/portal
Webhook:  POST /api/billing/webhook  (signature-verified)
```


## Fluxo de implementação

Um redirect de checkout é apenas uma intenção pendente — o acesso muda quando o webhook assinado chega e o entitlement do servidor é atualizado. Controla as ações pagas com a verificação de entitlement na fronteira do servidor (entitlement-gate.tsx / entitlement-check.ts) mesmo quando a interface já as oculta.

O portal do cliente gere alterações de plano, cancelamento e métodos de pagamento. Mantém o estado da subscrição legível pelos membros do workspace e as compras nativas mobile atrás da fronteira separada do RevenueCat.


## Seguinte

[Base de dados e migrações](https://supastack.dev/pt/docs/web/database.md)