O Stripe processa mais de $1 trilhão em pagamentos anualmente. Mais de 80% das startups SaaS usam Stripe para faturamento. Há uma razão: a API do Stripe é a API de pagamentos mais bem projetada do mundo, e sua infraestrutura de assinaturas lida com a complexidade de cobrança que levaria meses para construir por conta própria.
Mas "integrar o Stripe" é um conselho enganosamente simples. A diferença entre uma integração Stripe que funciona e uma que lida com casos extremos — pagamentos falhados, mudanças de plano, proration, dunning, conformidade fiscal — são centenas de horas de desenvolvimento.
Integramos o Stripe em múltiplos produtos SaaS, incluindo o AeroCopilot (assinaturas de aviação com requisitos de conformidade regulatória). Aqui está o guia completo.
Escolhendo Seu Modelo de Cobrança
Antes de escrever código, decida como vai cobrar. O Stripe suporta vários modelos, e sua escolha afeta toda a arquitetura de integração.
Assinaturas de Valor Fixo
O modelo mais simples. Usuários pagam um preço fixo mensal ou anual para acesso a um nível de plano. A maioria dos produtos SaaS B2B começa aqui.
- Plano gratuito → funcionalidades limitadas, limites de uso
- Plano Pro → $29/mês, funcionalidades completas, limites maiores
- Plano Enterprise → $99/mês, funcionalidades de equipe, suporte prioritário
Este modelo funciona quando seu custo para atender cada cliente é aproximadamente igual. Plataformas de conteúdo, ferramentas de gerenciamento de projetos e produtos CRM tipicamente usam preço fixo.
Cobrança Baseada em Uso (Medida)
Usuários pagam baseado no consumo — chamadas de API, armazenamento usado, mensagens enviadas, minutos de computação. A cobrança medida do Stripe rastreia uso e fatura automaticamente.
Este modelo funciona quando seu custo para atender varia significativamente por cliente. Produtos de IA, ferramentas de infraestrutura e plataformas de comunicação (como Twilio) usam cobrança baseada em uso porque um cliente fazendo 100 chamadas de API custa dramaticamente menos para atender do que um fazendo 1.000.000.
Híbrido (Fixo + Uso)
Uma taxa de assinatura base mais cobranças de uso acima dos limites inclusos. Isso é cada vez mais comum em 2026 — fornece receita previsível enquanto alinha custo com valor.
Exemplo: $49/mês inclui 10.000 chamadas de API. Chamadas adicionais a $0,005 cada. Isso dá aos clientes custos previsíveis no uso normal enquanto garante que usuários pesados paguem proporcionalmente.
Preço por Assento
O preço escala com o número de usuários na conta. Comum em SaaS B2B onde o valor do produto aumenta com a adoção pela equipe. O Stripe lida com cobrança por assento através de assinaturas baseadas em quantidade.
Configurando Sua Integração Stripe
Configuração de Produto e Preço
O Stripe separa Products (o que você vende) de Prices (como você cobra). Um único produto pode ter múltiplos preços — mensal, anual, medido, único.
// Criar produtos e preços no seu script de seed ou Stripe Dashboard
const product = await stripe.products.create({
name: 'Plano Pro',
description: 'Acesso completo a todas as funcionalidades',
metadata: { plan_tier: 'pro' }
})
const monthlyPrice = await stripe.prices.create({
product: product.id,
unit_amount: 2900, // $29.00 em centavos
currency: 'usd',
recurring: { interval: 'month' },
metadata: { billing_cycle: 'monthly' }
})
const annualPrice = await stripe.prices.create({
product: product.id,
unit_amount: 29000, // $290.00 — dois meses grátis
currency: 'usd',
recurring: { interval: 'year' },
metadata: { billing_cycle: 'annual' }
})
Boa prática: Defina produtos e preços no Stripe Dashboard para seu ambiente de produção, depois referencie-os por ID na sua aplicação. Hardcodar criação de preços no código da aplicação leva a produtos duplicados.
Criação e Sincronização de Clientes
Todo usuário no seu sistema deve mapear para um Stripe Customer. Crie o customer quando o usuário se cadastra e armazene o stripe_customer_id no seu banco de dados.
const customer = await stripe.customers.create({
email: user.email,
name: user.name,
metadata: {
user_id: user.id,
tenant_id: user.tenantId // para SaaS multi-tenant
}
})
// Armazene no seu banco de dados
await prisma.user.update({
where: { id: user.id },
data: { stripeCustomerId: customer.id }
})
Crítico: Sempre armazene o mapeamento entre seu usuário e o customer do Stripe. Perder esse mapeamento significa perder a capacidade de gerenciar a assinatura.
Checkout Sessions
O Stripe Checkout é uma página de pagamento hospedada que lida com entrada de cartão, validação, 3D Secure e conformidade PCI. Use-o em vez de construir formulários de pagamento customizados.
const session = await stripe.checkout.sessions.create({
customer: user.stripeCustomerId,
mode: 'subscription',
line_items: [{
price: priceId,
quantity: 1,
}],
success_url: `${baseUrl}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: `${baseUrl}/pricing`,
subscription_data: {
trial_period_days: 14,
metadata: { tenant_id: tenantId }
},
allow_promotion_codes: true,
})
O Stripe Checkout lida com conformidade PCI por você. Construir um formulário de pagamento customizado significa que você é responsável pela conformidade PCI SAQ A-EP no mínimo — um fardo significativo de segurança e auditoria para um MVP.
Tratamento de Webhooks: A Infraestrutura Crítica
Webhooks são como o Stripe informa sua aplicação sobre o que aconteceu. Um cliente pagou. Um pagamento falhou. Uma assinatura foi cancelada. Um trial está expirando. Se seu handler de webhook está quebrado, seu faturamento está quebrado.
Webhooks Essenciais para SaaS
No mínimo, trate estes eventos:
switch (event.type) {
case 'checkout.session.completed':
// Ativar assinatura, provisionar acesso
break
case 'customer.subscription.updated':
// Tratar mudanças de plano, mudanças de status
break
case 'customer.subscription.deleted':
// Revogar acesso, limpar recursos
break
case 'invoice.payment_succeeded':
// Registrar pagamento, estender acesso
break
case 'invoice.payment_failed':
// Notificar usuário, iniciar período de carência
break
case 'customer.subscription.trial_will_end':
// Enviar email de conversão 3 dias antes do trial acabar
break
}
Idempotência: Trate Duplicatas com Elegância
O Stripe pode enviar o mesmo evento de webhook múltiplas vezes. Seu handler deve ser idempotente — processar o mesmo evento duas vezes deve produzir o mesmo resultado que processá-lo uma vez.
async function handleWebhook(event: Stripe.Event) {
// Verifique se já processamos este evento
const existing = await prisma.stripeEvent.findUnique({
where: { stripeEventId: event.id }
})
if (existing) return // Já processado
// Processe o evento
await processEvent(event)
// Registre que processamos
await prisma.stripeEvent.create({
data: {
stripeEventId: event.id,
type: event.type,
processedAt: new Date()
}
})
}
Segurança de Webhooks
Sempre verifique assinaturas de webhook. O Stripe assina cada webhook com seu endpoint secret. Nunca confie em webhooks não verificados.
const event = stripe.webhooks.constructEvent( body, signature, process.env.STRIPE_WEBHOOK_SECRET! )
Lógica de Retry
O Stripe retenta entregas de webhook falhadas por até 3 dias com backoff exponencial. Seu endpoint deve:
- Retornar status
200em até 20 segundos - Processar trabalho pesado assincronamente (enfileire o evento, retorne 200, processe depois)
- Registrar falhas com contexto suficiente para debugar
Gerenciamento de Trials
Trials são o principal mecanismo de conversão para SaaS. Acerte-os.
- Trials de 14 dias são padrão. Longos o suficiente para avaliar, curtos o suficiente para criar urgência.
- Trials sem cartão de crédito conseguem mais cadastros mas menor conversão. Trials com cartão conseguem menos cadastros mas maior conversão. Teste ambos.
- Envie emails em pontos-chave: início do trial (boas-vindas + quick wins), dia 7 (check-in + funcionalidades avançadas), dia 11 (trial acabando em breve), dia 14 (trial encerrado + oferta especial)
- Use o webhook
customer.subscription.trial_will_endpara disparar a sequência final de conversão
Portal do Cliente
O Customer Portal do Stripe permite que usuários gerenciem seu próprio faturamento — atualizar métodos de pagamento, mudar planos, visualizar faturas, cancelar assinaturas. Incorpore-o com uma única chamada de API.
const portalSession = await stripe.billingPortal.sessions.create({
customer: user.stripeCustomerId,
return_url: `${baseUrl}/dashboard/settings`,
})
// Redirecione o usuário para portalSession.url
Isso te poupa de construir UI de gerenciamento de faturamento — que é surpreendentemente complexa quando você considera previews de proration, atualização de métodos de pagamento, histórico de faturas e fluxos de cancelamento.
Tratando Mudanças de Plano e Proration
Quando usuários fazem upgrade ou downgrade no meio do ciclo, proration determina quanto eles devem.
- Upgrade: O Stripe cobra a diferença proporcional imediatamente (ou na próxima fatura)
- Downgrade: O Stripe credita a porção não utilizada do plano atual e aplica ao novo plano
- Configure o comportamento de proration baseado no seu modelo de negócio:
await stripe.subscriptions.update(subscriptionId, {
items: [{
id: subscriptionItemId,
price: newPriceId,
}],
proration_behavior: 'create_prorations', // ou 'none', 'always_invoice'
})
Conformidade Fiscal com Stripe Tax
Stripe Tax calcula e coleta automaticamente impostos sobre vendas, IVA e GST baseado na localização do cliente. Em 2026, com requisitos de impostos sobre serviços digitais se expandindo globalmente, isso não é mais opcional.
const session = await stripe.checkout.sessions.create({
// ... outros parâmetros
automatic_tax: { enabled: true },
})
Habilite o Stripe Tax desde o lançamento. Calcular e remeter retroativamente impostos não coletados é doloroso, caro e potencialmente ilegal.
Implementação de Cobrança Baseada em Uso
Para cobrança medida, reporte uso ao Stripe e deixe-os lidar com o faturamento.
// Reporte eventos de uso ao longo do período de cobrança
await stripe.subscriptionItems.createUsageRecord(
subscriptionItemId,
{
quantity: apiCallCount,
timestamp: Math.floor(Date.now() / 1000),
action: 'increment', // ou 'set' para valores absolutos
}
)
Boa prática: Agrupe reportes de uso. Não chame a API do Stripe em cada ação individual do usuário — agregue uso no seu banco de dados e reporte ao Stripe por hora ou diariamente.
Para o AeroCopilot, implementamos rastreamento de uso para gerações de planos de voo e decodificações de METAR — ações core do produto que mapeiam diretamente para o valor entregue. Usuários no plano gratuito têm um número limitado de decodificações por mês; planos pagos incluem uso maior ou ilimitado.
Gerenciamento de Faturas
O Stripe gera faturas automaticamente para assinaturas. Customize-as para profissionalismo:
- Adicione seu logo e branding no Stripe Dashboard → Settings → Branding
- Inclua endereço comercial e CNPJ/CPF
- Customize templates de email de faturas
- Defina termos de pagamento (net 15, net 30) para clientes enterprise
- Habilite finalização automática de faturas
Armadilhas Comuns
1. Não tratar pagamentos falhados. 10-15% das renovações de assinatura falham por cartões expirados, fundos insuficientes ou recusas bancárias. Implemente Smart Retries do Stripe e envie emails de dunning.
2. Ignorar ordenação de webhooks. Eventos podem chegar fora de ordem. Não assuma que invoice.payment_succeeded chega antes de customer.subscription.updated. Projete handlers para funcionar independente da ordem.
3. Testar apenas o caminho feliz. Teste pagamentos falhados, cobranças contestadas, cancelamentos de assinatura e mudanças de plano. Use test clocks do Stripe para simular cenários baseados em tempo.
4. Hardcodar preços. Armazene IDs de Stripe Price em variáveis de ambiente ou no seu banco de dados, não no código da aplicação. Preços mudam. Planos evoluem. Seu código não deveria precisar de deploy para atualizar preços.
5. Esquecer dos reembolsos. Construa um fluxo de reembolso antes de precisar. Trate webhooks charge.refunded para revogar acesso ou ajustar créditos de uso.
Conclusão
Integração Stripe não é um projeto de fim de semana. Um sistema de faturamento pronto para produção — com trials, upgrades, downgrades, cobrança por uso, conformidade fiscal, dunning e portal do cliente — leva 2-4 semanas de desenvolvimento focado. Mas é um desenvolvimento que se paga imediatamente.
Acerte o faturamento desde o lançamento. Adaptar lógica de faturamento em um produto em funcionamento — com clientes reais, assinaturas reais e dinheiro real — é exponencialmente mais difícil do que construir corretamente desde o início.
A psicologia de precificação SaaS determina o que você cobra. O Stripe determina como você coleta. Acerte ambos e a receita vem.