Como Adicionar Subscrições com a Stripe: Planos, Períodos de Teste, Webhooks e Pagamentos Falhados
Para adicionar subscrições com a Stripe, crie um produto com um preço recorrente no painel da Stripe, envie os clientes para o Stripe Checkout em modo de subscrição a partir do seu servidor, e deixe um webhook dizer à sua app quando cada pagamento é concluído, falha, muda ou termina. Guarde o estado da subscrição associado ao utilizador e conceda o acesso com base nisso, e não na página de sucesso. Acrescente um botão Gerir faturação que abre o portal de cliente alojado pela Stripe, para que as pessoas possam mudar de cartão, trocar de plano e cancelar sem que tenha de construir esses ecrãs.
Este guia assenta em como adicionar pagamentos à sua app, que cobre o Checkout de pagamento único, o modo de teste e a passagem a produção. Aqui focamo-nos no que é diferente na faturação recorrente. Os detalhes da Stripe vêm da documentação da própria Stripe, com dados de setembro de 2026.
Porque é que as subscrições são mais difíceis do que os pagamentos únicos
Um pagamento único acontece enquanto o cliente está na sua app. Uma subscrição continua a acontecer depois de ele sair: renovações todos os meses, cartões que expiram, upgrades a meio do ciclo, cancelamentos que só fazem efeito no fim do período. A sua app só fica a saber disto através de webhooks. A maioria dos erros em subscrições vem de tratar o primeiro pagamento como a história completa.
As suas opções
| Abordagem | O que construir | Indicada para |
|---|---|---|
| Payment Link com preço recorrente | Apenas um link | Testar a procura; gerir o acesso manualmente |
| Checkout (modo de subscrição) + portal de cliente | Uma rota no servidor, um webhook, um botão de faturação | A maioria das apps SaaS e adesões |
| API de subscrições com o seu próprio formulário de pagamento | Muito mais: interface de pagamento, autenticação, novas tentativas | Apps com fluxos de faturação pouco comuns |
| Fornecedor «merchant of record» | Semelhante ao Checkout | Vendedores que querem que o fornecedor trate do IVA |
Para a maioria das apps, o Checkout mais o portal é o compromisso certo. Compare fornecedores em Stripe vs. Paddle vs. Lemon Squeezy se o tratamento fiscal o preocupar.
Planeie primeiro os preços na Stripe
Na Stripe, um produto é o que vende («Plano Pro») e um preço é a forma como o cobra («15 € por mês», «150 € por ano»). Um produto pode ter vários preços. Decida:
- Que escalões oferece e o que cada um desbloqueia na sua app
- Mensal, anual, ou ambos
- Se oferece um período de teste, e se exige cartão logo no início
Crie os produtos e os preços em modo de teste e guarde os IDs de preço; a sua app refere-se a eles. Se ainda não definiu os preços, leia como definir o preço de um produto SaaS e freemium vs. período de teste gratuito.
O ciclo de vida da subscrição que tem de tratar
A visão geral das subscrições da Stripe lista os estados que uma subscrição pode ter. Os que mais importam para o acesso:
| Estado | O que significa | Dar acesso? |
|---|---|---|
trialing | Em período de teste | Sim |
active | Em dia | Sim |
incomplete | O primeiro pagamento ainda não foi concluído; a Stripe dá ao cliente 23 horas | Não |
incomplete_expired | O primeiro pagamento nunca foi bem-sucedido | Não |
past_due | O último pagamento falhou ou não foi tentado; podem seguir-se novas tentativas | A seu critério; muitas apps permitem um curto período de tolerância |
unpaid | As tentativas terminaram, as faturas ficam em aberto, sem novas tentativas | Não; a documentação da Stripe indica que deve revogar o acesso |
canceled | Terminou; não pode ser reativada | Não |
paused | Um período de teste terminou sem método de pagamento e foi configurado para pausar | Não |
Guarde o estado no registo do seu utilizador ou conta e baseie o acesso nele. Atualize-o sempre que chegue um webhook relevante.
Os eventos de webhook a tratar
| Evento | O que a sua app faz |
|---|---|
checkout.session.completed | Liga os IDs do novo cliente e da subscrição na Stripe ao seu utilizador |
invoice.paid | Marca a subscrição como ativa e regista a nova data de fim do período |
invoice.payment_failed | Informa o utilizador de que o cartão falhou e ligue ao portal |
invoice.payment_action_required | Pede ao utilizador que conclua a autenticação do cartão |
customer.subscription.updated | Atualiza o plano, o estado e qualquer cancelamento agendado |
customer.subscription.deleted | Remove o acesso pago |
customer.subscription.trial_will_end | Lembra o utilizador antes de o período de teste acabar; a Stripe envia-o três dias antes |
As regras de tratamento dos documentos de webhook da Stripe continuam a aplicar-se: verifique a assinatura com o corpo bruto, devolva um 2xx rapidamente, trate duplicados e eventos fora de ordem, e conte com novas tentativas. O guia o que é um webhook explica a ideia, e o guia de pagamentos enumera as regras em detalhe.
Passo a passo
- Crie os produtos e os preços em modo de teste na Stripe.
- Acrescente os segredos: a chave secreta, os IDs de preço e, mais tarde, o segredo de assinatura do webhook. Nunca os coloque no código do frontend.
- Página de preços: o botão de cada plano chama o seu servidor, que cria uma Checkout Session em modo de subscrição para o utilizador com sessão iniciada. Envie o ID do seu utilizador para que o webhook associe o pagamento à conta.
- Endpoint de webhook: verifique as assinaturas e trate os eventos acima, atualizando um registo de subscrição por utilizador.
- Controle as funcionalidades com base no estado e plano guardados, verificados no servidor em cada ação protegida, e não apenas em botões escondidos.
- Portal de cliente: configure-o no painel da Stripe (que planos as pessoas podem escolher, se podem cancelar), depois acrescente um botão Gerir faturação que cria uma sessão do portal no servidor e redireciona para lá.
- Pagamentos falhados: nas definições de faturação da Stripe, escolha o comportamento de novas tentativas e o que acontece após a última. Mostre um aviso na app enquanto estiver em
past_due. - Teste o ciclo de vida completo, depois publique e registe o webhook de produção.
Prompts para dar ao seu criador com IA
Adicione faturação por subscrição com a Stripe. Planos: Starter (ID do preço em STRIPE_PRICE_STARTER) e Pro (STRIPE_PRICE_PRO). A página de preços cria uma Checkout Session em modo de subscrição no servidor usando STRIPE_SECRET_KEY, com o ID do utilizador com sessão iniciada anexado. Guarde no utilizador o ID do cliente Stripe, o ID da subscrição, o plano e o estado. Nunca exponha a chave secreta no navegador.
Adicione POST /api/stripe/webhook. Verifique a assinatura com STRIPE_WEBHOOK_SECRET usando o corpo bruto do pedido. Trate checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted e customer.subscription.trial_will_end. Registe os IDs de eventos já processados para ignorar duplicados. Atualize o estado do utilizador a partir do objeto da subscrição, e não da ordem de chegada dos eventos.
Controle as funcionalidades Pro no servidor: permita-as apenas quando o estado for active ou trialing e o plano for Pro. Mostre o aviso «pagamento falhado, atualize o seu cartão» quando o estado for past_due. Acrescente um botão Gerir faturação que abre o portal de cliente da Stripe para este utilizador.
Upgrades, downgrades e proporcionalidade
Quando um cliente muda de plano, a documentação da Stripe indica que a mudança muitas vezes cria uma proporcionalidade (proration): o novo preço é aplicado ao resto do período de faturação atual. Pode pré-visualizar as proporcionalidades ou desligá-las. Se os planos tiverem o mesmo intervalo, as datas de faturação mantêm-se; passar de mensal para anual muda a data de faturação para o dia da troca. Deixar os clientes mudarem de plano no portal poupa-lhe a escrita desta lógica, mas decida nas definições do portal que trocas são permitidas.
Lista de verificação de testes
Use o modo de teste da Stripe e os cartões de teste, e percorra todos os estados:
- Uma nova subscrição concede o plano certo ao utilizador certo
- Fechar o separador logo após pagar continua a conceder acesso (prova que o webhook funciona)
- Um cartão recusado no registo não concede nada
- Uma renovação que falha coloca a conta em past_due e mostra o aviso
- Atualizar o cartão no portal restaura o estado active
- Fazer upgrade e downgrade muda as funcionalidades corretamente
- Cancelar no fim do período mantém o acesso até à data de fim e depois remove-o
- Os utilizadores em período de teste têm acesso, recebem o lembrete e convertem ou perdem o acesso corretamente
- Enviar o mesmo evento de webhook duas vezes não altera nada
Os relógios de teste da Stripe deixam-no simular a passagem do tempo, para testar renovações sem esperar um mês. Consulte a documentação de testes atual da Stripe para saber como os usar.
Erros comuns
- Conceder acesso na página de sucesso. Os clientes podem pagar e nunca lá chegar. Use o webhook.
- Tratar apenas o primeiro pagamento. As renovações, falhas e cancelamentos chegam mais tarde, como eventos.
- Verificar o estado do plano apenas no frontend. Qualquer pessoa pode chamar a sua API diretamente.
- Um utilizador, muitas subscrições por acidente. Verifique se já existe uma subscrição antes de criar uma nova Checkout Session, ou envie os clientes existentes para o portal.
- Revogar o acesso à primeira renovação falhada. Os cartões falham por motivos banais. Um curto período de tolerância com um aviso claro mantém os clientes.
- Esquecer o webhook de produção. Os endpoints de teste e de produção têm segredos de assinatura diferentes.
- Ignorar impostos e reembolsos. Defina a sua política de reembolsos e confirme as suas obrigações fiscais com um contabilista antes do lançamento.
Subscrições na Mythex
As apps que cria na Mythex usam a sua própria conta e chaves da Stripe; não existe uma ligação à Stripe de um clique para a sua app. Acrescente as suas chaves de teste e IDs de preço como segredos do projeto, use prompts como os acima e teste com os cartões de teste da Stripe em Preview. Os webhooks precisam do URL público da sua app, por isso publique antes de registar o endpoint na Stripe, e volte a publicar depois de passar para as chaves de produção, para que a app em produção as use. Veja Aceitar pagamentos com a Stripe e Tratar webhooks no seu backend. Para o produto em geral, como criar um MVP de SaaS cobre o que construir em torno da faturação.
Perguntas
Qual é a forma mais simples de adicionar subscrições com a Stripe?
Crie um produto com um preço recorrente no painel da Stripe, envie os clientes para o Stripe Checkout em modo de subscrição, trate os eventos de subscrição com um webhook e ligue um botão de Gerir faturação ao portal de cliente alojado pela Stripe. Assim não precisa de construir formulários de cartão nem ecrãs de mudança de plano.
Que eventos de webhook da Stripe preciso para as subscrições?
No mínimo, checkout.session.completed para ligar a nova subscrição ao seu utilizador, invoice.paid para confirmar cada pagamento bem-sucedido, invoice.payment_failed para avisar sobre renovações falhadas, e customer.subscription.updated e customer.subscription.deleted para acompanhar mudanças de plano e cancelamentos.
O que acontece quando falha um pagamento de subscrição?
Segundo a documentação da Stripe a partir de setembro de 2026, a subscrição normalmente passa a past_due e a Stripe pode repetir a cobrança conforme as suas definições. Após a última tentativa, as definições do painel decidem se fica cancelada, marcada como não paga ou simplesmente em past_due.
Posso oferecer um período de teste gratuito sem pedir cartão?
Sim. A Stripe suporta períodos de teste gratuitos, e a documentação descreve um estado paused para os testes que terminam sem método de pagamento, quando configurado assim. Pedir o cartão logo no início costuma significar menos inscrições mas mais clientes pagantes; teste o que se adequa ao seu produto.