Como Adicionar Pagamentos à Sua App: Checkout, Subscrições e Webhooks

A forma mais simples de adicionar pagamentos à sua app é a Stripe: use um Payment Link se precisar apenas de um botão de «Comprar» e puder tratar das encomendas manualmente; o Stripe Checkout se a sua app precisar de saber quem pagou e de reagir automaticamente; e o Checkout em modo de subscrição, mais o portal de cliente da Stripe, para faturação recorrente. Em todos os casos, exceto no mais simples, também precisa de um webhook — um endpoint no servidor que a Stripe chama quando um pagamento é concluído — e deve testar tudo com as chaves de teste e os cartões de teste da Stripe antes de passar para as chaves de produção.

Este guia explica cada opção, a parte do webhook que a maioria dos tutoriais deixa de fora, e o que verificar antes de receber dinheiro real. Os detalhes da Stripe vêm da documentação oficial da própria Stripe, com dados de setembro de 2026.

Porque usar um fornecedor de pagamentos

Nunca recolha números de cartão nos seus próprios formulários. Tratar dados de cartões em bruto coloca-o no âmbito da PCI DSS (a norma de segurança da indústria de cartões) e é uma responsabilidade grave. Um fornecedor de pagamentos como a Stripe aloja o formulário de pagamento, guarda o cartão, trata da autenticação bancária e diz à sua app o resultado. A sua app só vê «o cliente X pagou pelo Y».

Este guia usa a Stripe porque é muito utilizada, bem documentada e suportada pela maioria dos criadores de apps com IA. Existem outros fornecedores, e alguns atuam como «merchant of record» e assumem por si o tratamento do IVA; se a conformidade fiscal o preocupa, esse modelo vale a comparação.

As três formas de receber pagamentos com a Stripe

Payment Links

Um Payment Link é uma página de pagamento alojada pela Stripe que cria no painel da Stripe sem código. Obtém um URL que pode colocar atrás de um botão na sua app, partilhar num email ou mostrar como código QR. A documentação da Stripe indica que os Payment Links podem vender um produto, uma subscrição ou receber um donativo, e pode deixar o cliente escolher o que paga ou limitar o número de compras.

O senão: a sua app não sabe automaticamente que um determinado utilizador com sessão iniciada pagou. Para uma página de donativos ou uma pequena loja em que trata das encomendas à mão a partir das notificações de email da Stripe, isso chega. Para «pague para desbloquear as funcionalidades Pro», não chega.

Stripe Checkout

O Checkout é uma página de pagamento que o seu servidor cria sob pedido para uma compra específica. O seu servidor diz à Stripe o que está a ser comprado (e, opcionalmente, qual o cliente que compra), a Stripe devolve um URL, e envia o cliente para lá. A documentação da Stripe descreve-o como suportando pagamentos únicos e subscrições, como uma página totalmente alojada pela Stripe, uma página incorporada no seu site ou um formulário incorporado.

O fluxo:

1. O cliente clica em Comprar na sua app.
2. O seu servidor cria uma Checkout Session com a sua chave secreta, incluindo um ID que a liga ao seu utilizador ou encomenda.
3. O cliente é redirecionado para a Stripe e paga.
4. A Stripe redireciona-o de volta para a sua página de sucesso.
5. A Stripe envia um evento checkout.session.completed para o seu webhook, e o seu servidor marca a encomenda como paga ou desbloqueia o acesso.

O passo 2 tem de acontecer no servidor, porque usa a sua chave secreta. Essa é a principal razão pela qual o Checkout precisa de um backend.

Subscrições

As subscrições usam o Checkout em modo de subscrição com um preço recorrente que configura na Stripe. O primeiro pagamento funciona como o fluxo acima. Depois disso, as renovações, os cartões recusados, as atualizações a meio do ciclo e os cancelamentos acontecem ao longo do tempo — muitas vezes quando o cliente nem está na sua app — por isso a sua app só fica a saber através de webhooks.

Para deixar o cliente gerir a própria subscrição, a Stripe oferece um portal de cliente alojado. Segundo a documentação da Stripe, os clientes podem atualizar os métodos de pagamento e os dados de faturação, mudar ou cancelar subscrições, e ver e transferir faturas por lá. Configura-o no painel da Stripe e acrescenta um botão «Gerir faturação» que envia o cliente para lá. Assim poupa-se a construir esses ecrãs.

Webhooks: a parte que não pode saltar

Um webhook é um pedido HTTP que a Stripe envia ao seu servidor quando algo acontece. (Veja o que é um webhook para a ideia geral.) O guia de cumprimento da Stripe é explícito: não pode confiar apenas na página de sucesso para cumprir encomendas, porque um cliente pode pagar e perder a ligação antes de essa página carregar. Para subscrições e métodos de pagamento com atraso, os webhooks são obrigatórios.

Eventos que vale a pena tratar

Regras para um tratamento de webhook correto

estas vêm diretamente da documentação de webhooks da Stripe, e os tratadores gerados por IA por vezes falham uma delas:

• Verifique a assinatura. Cada evento inclui um cabeçalho Stripe-Signature. O seu tratador verifica-a com o segredo de assinatura do endpoint (começa por whsec_). Sem isto, qualquer pessoa poderia enviar ao seu servidor um falso «pagamento concluído».
• Use o corpo bruto do pedido. As verificações de assinatura falham se a sua framework interpretar ou alterar o corpo primeiro.
• Devolva uma resposta 2xx rapidamente e só depois faça o trabalho mais lento. Os timeouts contam como falhas.
• Trate os duplicados. A Stripe pode entregar o mesmo evento mais do que uma vez. Registe os IDs de eventos já processados, ou torne o cumprimento seguro para ser executado duas vezes.
• Não assuma a ordem. A Stripe não garante que os eventos cheguem pela ordem em que aconteceram.
• Conte com novas tentativas. Em modo de produção, a Stripe repete as entregas falhadas durante até três dias, por isso uma pequena falha não perde pagamentos — mas o seu tratador tem de lidar com eventos atrasados.

Os webhooks precisam de um endereço HTTPS público, por isso normalmente só funcionam depois de a sua app ser publicada (a CLI da Stripe pode reencaminhar eventos para uma máquina local para os programadores).

Um prompt que cobre o fluxo completo

Adicione uma compra única com o Stripe Checkout para o «Pacote Pro» (ID do preço em STRIPE_PRICE_ID). Crie a Checkout Session no servidor usando STRIPE_SECRET_KEY dos segredos, e inclua o ID do utilizador com sessão iniciada na sessão. Adicione um endpoint POST /api/stripe/webhook que verifica a assinatura da Stripe com STRIPE_WEBHOOK_SECRET usando o corpo bruto do pedido, trata checkout.session.completed e marca esse utilizador como tendo o Pacote Pro. Torne-o seguro se o mesmo evento chegar duas vezes. Páginas de sucesso e de cancelamento. Nunca exponha a chave secreta no navegador.

Para subscrições, acrescente: «Use o modo de subscrição com STRIPE_PRICE_ID. Trate invoice.paid, invoice.payment_failed, customer.subscription.updated e customer.subscription.deleted. Adicione um botão Gerir faturação que abre o portal de cliente da Stripe.»

Modo de teste

A Stripe tem ambientes separados de sandbox (teste) e de produção, com chaves separadas. As chaves de sandbox começam por pk_test_, sk_test_ ou rk_test_; as de produção começam por pk_live_, sk_live_ ou rk_live_. As transações de teste não movimentam dinheiro.

Cartões de teste úteis, da documentação de testes da Stripe (qualquer data de validade futura, qualquer CVC de três dígitos):

Teste pelo menos:

• Um pagamento bem-sucedido desbloqueia a coisa certa para o utilizador certo
• Um cartão recusado mostra uma mensagem clara e não desbloqueia nada
• Fechar o separador do navegador logo após pagar continua a dar acesso (isto prova que o webhook funciona, não apenas a página de sucesso)
• Cancelar na página da Stripe devolve o utilizador à sua app sem qualquer cobrança
• Para subscrições: cancele no portal de cliente e confirme que o acesso termina quando deve

Passagem a produção

1. Ative a sua conta Stripe com os dados da empresa e da conta bancária.
2. Troque para as chaves de produção nos segredos da sua app. A Stripe recomenda chaves restritas, apenas com as permissões que a sua integração precisa, em vez de uma chave secreta sem restrições.
3. Crie um endpoint de webhook de produção apontado para a sua app publicada. Tem um segredo de assinatura próprio, diferente do de teste — atualize-o.
4. Recrie os produtos e os preços em modo de produção; os IDs do modo de teste não existem lá.
5. Faça uma compra real pequena e reembolse-a.

Guarde todas as chaves nos segredos do projeto, nunca no código ou no chat. A nossa lista de verificação de segurança cobre as chaves e a verificação de webhooks com mais detalhe.

Impostos, reembolsos e a papelada

Os pagamentos trazem obrigações que o código não resolve. Isto não é aconselhamento fiscal; confirme com um contabilista.

• IVA e impostos sobre vendas. Consoante o local onde estão você e os seus clientes, poderá ter de se registar, cobrar e declarar impostos. O Stripe Tax consegue calcular e cobrar impostos no checkout, monitorizar onde as suas vendas podem criar uma obrigação, e ajudar com registos e declarações — mas a responsabilidade continua a ser sua. Os fornecedores «merchant of record» são uma alternativa que assume mais desta parte.
• Reembolsos e disputas. Defina a sua política de reembolsos antes do lançamento e publique-a no site. As disputas (chargebacks) acontecem; guarde registos do que foi comprado e entregue.
• Recibos e faturas. A Stripe pode enviar recibos por email; as empresas podem precisar de faturas adequadas.
• Comissões. Todos os fornecedores cobram por transação. Consulte a página de preços atual do fornecedor em vez de confiar em valores de artigos.

Qual a configuração indicada para a sua app

• Donativos ou alguns produtos: Payment Links. Veja como criar um site de donativos para uma associação.
• Uma loja com carrinho: Checkout com linhas de produto e um webhook. Veja como criar uma loja online.
• SaaS ou adesões: Checkout em modo de subscrição, webhooks e o portal de cliente. Veja como criar um MVP de SaaS e como definir o preço de um produto SaaS.
• Um marketplace que paga a vendedores: uma configuração diferente e mais regulada (Stripe Connect ou semelhante). Planeie-a separadamente.

Adicionar pagamentos na Mythex

Os pagamentos nas apps que cria na Mythex usam a sua própria conta Stripe e as suas chaves; não existe uma ligação «Ligar Stripe» de um clique para a sua app. O fluxo habitual:

1. Obtenha as chaves de teste da Stripe.
2. Acrescente STRIPE_SECRET_KEY (e o segredo do webhook mais tarde) aos segredos do projeto — através de /secrets, das definições do projeto ou do cartão de segredos que o agente mostra quando precisa de uma chave.
3. Peça ao agente o Checkout com um prompt como o acima.
4. Teste em Preview com cartões de teste. Publique antes de registar o webhook, porque ele precisa do seu URL público.
5. Depois de trocar para as chaves de produção, publique de novo para que a app em produção as use.

Veja Aceitar pagamentos com a Stripe e Tratar webhooks no seu backend na documentação.

Perguntas