Como Adicionar Pagamentos ao Seu App: Checkout, Assinaturas e Webhooks

A forma mais simples de adicionar pagamentos ao seu app é a Stripe: use um Payment Link se você só precisa de um botão "Comprar" e consegue processar os pedidos manualmente; use o Stripe Checkout se o seu app precisa saber quem pagou e reagir automaticamente; e use o Checkout no modo assinatura, mais o portal do cliente da Stripe, para cobrança recorrente. Em todos os casos, exceto o mais simples, você também precisa de um webhook — um endpoint no seu 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 trocar para as chaves de produção.

Este guia explica cada opção, a parte do webhook que a maioria dos tutoriais deixa de lado e o que verificar antes de cobrar dinheiro de verdade. Os detalhes da Stripe vêm da documentação oficial da empresa em setembro de 2026.

Por que usar um provedor de pagamentos

Nunca colete números de cartão nos seus próprios formulários. Lidar com dados brutos de cartão coloca você no escopo do PCI DSS (o padrão de segurança da indústria de cartões) e é uma responsabilidade séria. Um provedor como a Stripe hospeda o formulário de pagamento, guarda o cartão, cuida da autenticação com o banco e informa o resultado ao seu app. O seu app só vê "o cliente X pagou pelo Y".

Este guia usa a Stripe porque é amplamente utilizada, bem documentada e suportada pela maioria dos construtores de apps com IA. Existem outros provedores, e alguns atuam como "merchant of record", assumindo o tratamento de impostos sobre vendas para você; se a conformidade tributária preocupa você, vale comparar esse modelo.

As três formas de receber pagamentos com a Stripe

Payment Links

Um Payment Link é uma página de pagamento hospedada pela Stripe que você cria no Painel da Stripe, sem código. Você recebe uma URL que pode colocar atrás de um botão no seu app, compartilhar num e-mail ou exibir como QR code. Segundo a documentação da Stripe, os Payment Links podem vender um produto, uma assinatura ou receber uma doação, e você pode deixar o cliente escolher o que pagar ou limitar o número de compras.

O porém: o seu app não sabe automaticamente que um determinado usuário logado pagou. Para uma página de doação ou uma pequena loja em que você processa os pedidos manualmente a partir das notificações por e-mail da Stripe, isso basta. Para "pague para desbloquear os recursos Pro", não basta.

Stripe Checkout

O Checkout é uma página de pagamento que o seu servidor cria sob demanda para uma compra específica. Seu servidor informa à Stripe o que está sendo comprado (e, opcionalmente, qual cliente está comprando), a Stripe devolve uma URL e você envia o cliente para lá. A documentação da Stripe descreve o Checkout como compatível com pagamentos únicos e por assinatura, como uma página totalmente hospedada pela Stripe, uma página incorporada no seu site ou um formulário incorporado.

O fluxo:

1. O cliente clica em Comprar no seu app.
2. Seu servidor cria uma Checkout Session usando sua chave secreta, incluindo um ID que a vincula ao seu usuário ou pedido.
3. O cliente é redirecionado para a Stripe e paga.
4. A Stripe redireciona o cliente 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 o pedido como pago ou libera o acesso.

A etapa 2 precisa acontecer no servidor, porque usa a sua chave secreta. É o principal motivo pelo qual o Checkout precisa de um backend.

Assinaturas

As assinaturas usam o Checkout no modo assinatura com um preço recorrente que você configura na Stripe. O primeiro pagamento funciona como o fluxo acima. Depois disso, renovações, cartões recusados, upgrades no meio do ciclo e cancelamentos acontecem ao longo do tempo — muitas vezes com o cliente fora do seu app —, então o seu app só fica sabendo disso pelos webhooks.

Para que o cliente gerencie a própria assinatura, a Stripe oferece um portal do cliente hospedado. Segundo a documentação da Stripe, o cliente pode atualizar formas de pagamento e dados de cobrança, trocar ou cancelar assinaturas e ver e baixar faturas por lá. Você configura o portal no Painel da Stripe e adiciona um botão "Gerenciar cobrança" que envia o cliente para ele. Isso poupa você de construir essas telas.

Webhooks: a parte que você não pode pular

Um webhook é uma requisição HTTP que a Stripe envia ao seu servidor quando algo acontece. (Veja o que é um webhook para a ideia geral.) O guia de finalização de pedidos da Stripe é explícito: você não pode depender só da página de sucesso para processar pedidos, porque o cliente pode pagar e perder a conexão antes de a página carregar. Para assinaturas e formas de pagamento com atraso, os webhooks são obrigatórios.

Eventos que vale tratar

Regras para um manipulador de webhook correto

Todas vêm diretamente da documentação de webhooks da Stripe, e os manipuladores gerados por IA às vezes deixam alguma de fora:

• Verifique a assinatura. Cada evento inclui um cabeçalho Stripe-Signature. Seu manipulador confere a assinatura usando o segredo de assinatura do endpoint (começa com whsec_). Sem isso, qualquer pessoa poderia enviar um falso "pagamento aprovado" ao seu servidor.
• Use o corpo bruto da requisição. A verificação da assinatura falha se o seu framework interpretar ou modificar o corpo antes.
• Responda rapidamente com 2xx e só depois faça o trabalho mais lento. Timeouts contam como falhas.
• Trate duplicatas. A Stripe pode entregar o mesmo evento mais de uma vez. Registre os IDs dos eventos já processados, ou torne o processamento seguro para rodar duas vezes.
• Não assuma a ordem. A Stripe não garante que os eventos cheguem na ordem em que aconteceram.
• Espere reenvios. No modo de produção, a Stripe tenta de novo entregas com falha por até três dias, então uma queda curta não perde pagamentos — mas o seu manipulador precisa lidar com eventos atrasados.

Os webhooks precisam de um endereço HTTPS público, então normalmente só funcionam depois que o app é publicado (a CLI da Stripe pode encaminhar eventos para uma máquina local, para desenvolvedores).

Um prompt que cobre o fluxo inteiro

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 usuário logado na sessão. Adicione um endpoint POST /api/stripe/webhook que verifique a assinatura da Stripe com STRIPE_WEBHOOK_SECRET usando o corpo bruto da requisição, trate checkout.session.completed e marque esse usuário como tendo o Pacote Pro. Torne seguro caso o mesmo evento chegue duas vezes. Páginas de sucesso e de cancelamento. Nunca exponha a chave secreta ao navegador.

Para assinaturas, acrescente: "Use o modo assinatura com STRIPE_PRICE_ID. Trate invoice.paid, invoice.payment_failed, customer.subscription.updated e customer.subscription.deleted. Adicione um botão Gerenciar cobrança que abre o portal do cliente da Stripe."

Modo de teste

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

Cartões de teste úteis, segundo a 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 libera a coisa certa para o usuário certo
• Um cartão recusado mostra uma mensagem clara e não libera nada
• Fechar a aba do navegador logo depois de pagar ainda resulta em acesso (isso prova que o webhook funciona, não só a página de sucesso)
• Cancelar na página da Stripe devolve o usuário ao seu app sem nenhuma cobrança
• Para assinaturas: cancele no portal do cliente e confirme que o acesso termina quando deveria

Entrando em produção

1. Ative sua conta Stripe com os dados da empresa e da conta bancária.
2. Troque para as chaves de produção nos segredos do app. A Stripe recomenda chaves restritas, com apenas 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 apontando para o seu app publicado. Ele tem seu próprio segredo de assinatura, diferente do de teste — atualize-o.
4. Recrie produtos e preços no modo de produção; os IDs do modo de teste não existem lá.
5. Faça uma compra real pequena e estorne-a.

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

Impostos, reembolsos e a papelada

Pagamentos trazem obrigações que o código não resolve. Isto não é aconselhamento tributário; consulte um contador.

• Imposto sobre vendas, IVA e GST. Dependendo de onde você e seus clientes estão, pode ser preciso se registrar, cobrar e declarar impostos. O Stripe Tax pode calcular e cobrar impostos no checkout, monitorar onde suas vendas podem gerar uma obrigação e ajudar com registros e declarações — mas a responsabilidade continua com você. Os provedores merchant of record são uma alternativa que assume mais dessa parte.
• Reembolsos e contestações. Defina sua política de reembolso antes do lançamento e publique-a no seu site. Contestações (chargebacks) acontecem; guarde registros do que foi comprado e entregue.
• Recibos e notas fiscais. A Stripe pode enviar recibos por e-mail; empresas podem precisar de notas fiscais formais.
• Taxas. Todo provedor cobra por transação. Consulte a página de preços atual do provedor em vez de confiar em números de artigos.

Qual configuração serve para o seu app

• Doações ou alguns produtos: Payment Links. Veja como criar um site de doações para ONGs.
• Uma loja com carrinho: Checkout com itens e um webhook. Veja como criar uma loja online.
• SaaS ou assinaturas: Checkout no modo assinatura, webhooks e o portal do cliente. Veja como criar um MVP de SaaS e como precificar um produto SaaS.
• Um marketplace que paga vendedores: uma configuração diferente, mais regulada (Stripe Connect ou similar). Planeje isso separadamente.

Adicionando pagamentos no Mythex

Os pagamentos em apps que você cria no Mythex usam a sua própria conta e as suas chaves da Stripe; não existe uma conexão com a Stripe de um clique para o seu app. O fluxo normal:

1. Obtenha as chaves de teste da Stripe.
2. Adicione STRIPE_SECRET_KEY (e o segredo do webhook depois) aos segredos do projeto — por /secrets, nas configurações do projeto ou no cartão de segredos que o agente mostra quando precisa de uma chave.
3. Peça ao agente o Checkout usando um prompt como o acima.
4. Teste no Preview com cartões de teste. Publique antes de registrar o webhook, já que ele precisa da sua URL pública.
5. Depois de trocar para as chaves de produção, publique novamente para que o app em produção as utilize.

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

Perguntas