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/modules/billing-configuration.md (or send Accept: text/markdown).
Configuração Stripe e webhooks
Liga subscrições web às permissões do lado do servidor.
Instalação e configuração
Antes de qualquer etapa, leia Antes de começar e Noções básicas sobre terminal. Estas instruções presumem que você abriu o monorepo supastack completo no VS Code; sua raiz package.json marca a raiz do repositório. Nos comandos pnpm, um pacote de espaço de trabalho é um aplicativo ou uma pasta de código compartilhado; no produto, um espaço de trabalho é o contêiner de dados e o limite de segurança de uma equipe. corepack pnpm --filter ... seleciona um pacote do monorepo enquanto os comandos são executados a partir de sua raiz. Se você abriu apenas uma pasta móvel ou desktop sincronizada, ela não contém o back-end da Web, a configuração do Docker ou os scripts raiz: execute o back-end deste monorepo ou de um servidor hospedado acessível e use os próprios scripts da pasta da plataforma. Uma variável de ambiente é uma configuração nomeada armazenada em um arquivo .env local ou no painel de hospedagem; reinicie o aplicativo relevante após alterá-lo e mantenha os segredos do servidor fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.
1. Abra apps/web/.env.local e mantenha BILLING_PROVIDER=local enquanto aprende a tela de checkout.
2. Para uma integração real, crie produtos em modo de teste em um provedor e, em seguida, adicione as chaves do servidor e o segredo do webhook às configurações do ambiente privado do host da Web. Um webhook é uma mensagem assinada que o serviço de cobrança envia ao seu aplicativo após a finalização da compra, renovação ou cancelamento; o caminho do endpoint está listado no exemplo de código deste guia.
3. Inicie a Web com corepack pnpm --filter @supastack/web dev e teste apenas o sandbox. Esperado: um webhook verificado atualiza o direito do espaço de trabalho conectado; abrir uma página de checkout por si só não concede acesso.
Use credenciais de sandbox/teste durante a integração. Configure BILLING_PROVIDER mais os segredos somente do servidor do provedor: stripe → STRIPE_SECRET_KEY, STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET; espremedor de limão → LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_VARIANT_ID, LEMONSQUEEZY_WEBHOOK_SECRET; creem → CREEM_API_KEY, CREEM_PRODUCT_ID, CREEM_WEBHOOK_SECRET (CREEM_TEST_MODE=true para a caixa de areia); polar → POLAR_ACCESS_TOKEN, POLAR_PRODUCT_ID, POLAR_WEBHOOK_SECRET (POLAR_SERVER); uau → WHOP_API_KEY, WHOP_PLAN_ID, WHOP_WEBHOOK_SECRET; remo → PADDLE_API_KEY, PADDLE_PRICE_ID, PADDLE_WEBHOOK_SECRET (PADDLE_ENVIRONMENT); dodô → DODO_PAYMENTS_API_KEY, DODO_PRODUCT_ID, DODO_PAYMENTS_WEBHOOK_KEY (DODO_PAYMENTS_ENVIRONMENT); PayPal → PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_PLAN_ID, PAYPAL_WEBHOOK_ID (PAYPAL_ENVIRONMENT). O preço/produto deve representar a assinatura recorrente pretendida.
Webhook endpoint: /api/billing/webhook (stripe), /api/billing/webhook/lemonsqueezy, /api/billing/webhook/creem, /api/billing/webhook/polar, /api/billing/webhook/whop, /api/billing/webhook/paddle, /api/billing/webhook/dodo, /api/billing/webhook/paypal
Checkout endpoint: /api/billing/checkout
Portal endpoint: /api/billing/portalComandos para copiar
Siga os comentários para ver em qual pasta um comando é executado. Se dois terminais estiverem rotulados, abra duas janelas de terminal e mantenha o primeiro comando em execução enquanto usa o segundo.
corepack pnpm --filter @supastack/web devFluxo de implementação
Segue a lista de eventos de ciclo de vida em docs/real-provider-smoke.md para configurar o endpoint de webhook. A verificação de assinatura exige o segredo de webhook correspondente ao endpoint. Um redirecionamento de checkout sozinho nunca deve conceder acesso.
A permissão na fronteira da ação de servidor decide se trabalho pago é permitido. Trata eventos repetidos com segurança e delimita registos de cliente/subscrição ao workspace correto. O checkout web permanece separado de compras nativas.
A chave que um plano concede é o vocabulário do produto compartilhado entre superfícies: ProductPlan.entitlement em src/product-plans.ts declara a chave de máquina minúscula escrita no livro-razão enquanto um plano é pago (o kit é enviado 'ai.reference-task' no pro e vitalício; src/billing-runtime.ts passa para o BFF). A mesma chave é a comparação entre o campo require_entitlement de uma entrada CMS e o entitlementKey prop equality do componente EntitlementGate - uma entrada bloqueada em 'ai.reference-task' desbloqueia qualquer espaço de trabalho que possua essa concessão, enquanto uma chave sem concessão de plano permanece bloqueada para todos.
Verificação e resolução de problemas
Se um webhook for rejeitado, compare o sandbox exato URL e o segredo de assinatura no painel do provedor com as configurações do servidor e verifique se esse provedor exige o encaminhamento de solicitações para localhost. Se a finalização da compra funcionar, mas o acesso permanecer bloqueado, inspecione o resultado do webhook e a chave de direito no plano. Nunca teste com credenciais de pagamento em tempo real enquanto segue este guia local.
Testa ativação, atualizações, cancelamento, assinaturas inválidas e eventos repetidos no sandbox. Inspeciona o estado de acesso persistido após o processamento. Criar uma sessão de checkout não consumida prova apenas conetividade, não fulfillment do ciclo de vida.