Cobrança recorrente é a cobrança automática de um valor em intervalos definidos (mensal, trimestral, anual) enquanto o contrato do cliente estiver ativo, e para um SaaS ela decide se o MRR que você vendeu vira caixa ou vira churn involuntário. O assinante autoriza uma vez, no cartão, no Pix Automático ou no boleto, e o sistema cobra cada ciclo sozinho. O que separa uma operação saudável de uma que sangra em silêncio não é o ato de cobrar: é o que acontece quando a cobrança falha. Este guia mostra os modelos de recorrência que existem no Brasil, a matemática do churn involuntário em reais, o arsenal para reduzir a perda (retentativa, régua de cobrança, troca de cartão, Pix Automático), uma régua de D-3 a D+15 pronta para copiar, as métricas que importam e como medir tudo pela API do HeroPay.
Criar conta sandbox Ler a documentação
O essencial em 60 segundos
- Cobrança recorrente é a empresa cobrando um valor em intervalos fixos a partir de uma autorização única do cliente; pagamento recorrente é o mesmo processo visto pelo lado de quem paga.
- Churn involuntário é o assinante que queria ficar e caiu por falha de pagamento (cartão expirado, sem limite, bloqueado, boleto vencido). Como o problema é o meio de pagamento e não o produto, ele é o churn mais recuperável que existe.
- A perda é composta: numa base de 100 assinantes a R$ 97, 5% de falhas não recuperadas por ciclo levam R$ 27.229,86 de receita em 12 meses e deixam 54 assinantes no fim do ano, sem ninguém ter pedido para sair.
- Nenhuma alavanca resolve sozinha: retentativa recupera a recusa temporária, troca de cartão resolve o cartão que morreu, régua de cobrança avisa antes e depois, e o Pix Automático tira o assinante do cartão.
- Uma régua de cobrança para SaaS cabe em seis degraus: D-3 (lembrete), D0 (cobrança), D+1 (aviso de falha com link de troca), D+3, D+7 (acesso limitado) e D+15 (suspensão e oferta de volta), cada um no canal certo.
- As métricas mínimas são MRR, churn de clientes, churn de receita bruto e líquido, taxa de falha na renovação e taxa de recuperação; no HeroPay você calcula todas com
GET /sales/recurringe os relatórios de assinaturas e de recusadas. - No HeroPay, recorrência é um link de pagamento com
period, cobrada no cartão (3,49%), no boleto (R$ 0) ou no Pix Automático (R$ 0), sem mensalidade e sem taxa extra pela assinatura. Hoje não há trial, pró-rata nem cobrança por uso na API.
Neste guia
- Fundamentos: o que é cobrança recorrente e quais modelos existem
- A anatomia do churn involuntário e a conta composta
- O arsenal anti-churn: retentativa, dunning, troca de cartão e Pix Automático
- A régua de cobrança perfeita, passo a passo, de D-3 a D+15
- Métricas: MRR, churn líquido e recuperação, e como medir via API
- Pix Automático vs cartão vs boleto na recorrência
- Impostos e nota fiscal em linhas gerais
- Coloque em prática · Mitos e verdades · Glossário · FAQ · Fontes
Parte 1. Fundamentos: o que é cobrança recorrente e quais modelos existem
O que é cobrança recorrente, na prática de um SaaS?
É a combinação de três coisas: uma autorização guardada (cartão tokenizado, mandato de Pix Automático ou cadastro para emissão de boleto), um calendário (a data de renovação de cada assinante) e uma política de falha (o que fazer quando o dinheiro não vem). As duas primeiras qualquer gateway entrega. A terceira é onde o SaaS ganha ou perde dinheiro, e é por isso que a maior parte deste guia trata dela.
Qual a diferença entre cobrança recorrente, pagamento recorrente e parcelamento?
Cobrança recorrente e pagamento recorrente são o mesmo processo visto de lados diferentes: a empresa cobra, o cliente paga. Parcelamento é outra coisa: uma compra única dividida em parcelas, em que o valor total já foi aprovado de uma vez e compromete o limite do cartão logo no início. Na assinatura, cada ciclo é uma transação nova, aprovada ou recusada naquele dia. Essa diferença explica por que a assinatura consome pouco limite (só o valor do mês) e também por que ela pode falhar todo mês.
Quais modelos de recorrência existem?
| Modelo | Como cobra | Exemplo de SaaS | O que exige do sistema de cobrança |
|---|---|---|---|
| Assinatura fixa | Mesmo valor a cada ciclo | Plano Pro a R$ 97/mês, anual a R$ 970 | Periodicidade, retentativa, troca de cartão |
| Por uso (metered) | Valor calculado a partir do consumo do ciclo | R$ 0,10 por mensagem enviada, R$ 2 por nota emitida | Medição, fechamento de fatura, cobrança de valor variável |
| Híbrida | Base fixa + excedente por uso | R$ 197/mês com 5 mil mensagens + R$ 0,05 por excedente | As duas coisas, e a regra de quando cobrar o excedente |
| Por assento | Valor fixo × número de usuários | R$ 39 por usuário/mês | Troca de quantidade no meio do ciclo, geralmente com pró-rata |
| Contrato com fim | Valor fixo por N ciclos e encerra | Implantação em 12x, mentoria de 12 meses | Limite de ciclos e encerramento automático |
O que existe no Brasil hoje para cada modelo?
Assinatura fixa é o que todo gateway brasileiro com recorrência entrega, no cartão e, cada vez mais, no boleto e no Pix Automático. Cobrança por uso e pró-rata são mais raras e costumam estar em ferramentas de billing mais completas: a documentação do Stripe Billing e da iugu descreve troca de plano com pró-rata, e a da AbacatePay descreve trial, troca de plano e cobrança por uso (verificado em setembro/2026, fontes no fim do guia).
Honestidade sobre o HeroPay, porque isso muda a sua escolha:
| Modelo | No HeroPay hoje | Como fazer |
|---|---|---|
| Assinatura fixa | Sim | POST /payment_links com period (monthly, quarterly, semiannual, annual) e frequency_type: "unlimited" |
| Contrato com fim | Sim | frequency_type: "limited" + frequency_limit: 12 encerra sozinho na 12ª cobrança |
| Por uso | Não na API v1 | Seu backend mede o consumo e gera um link de pagamento avulso por fatura; o cliente paga cada link (não é débito automático) |
| Híbrida | Parcial | Base fixa como assinatura + excedente como link avulso do ciclo |
| Por assento com pró-rata | Não na API v1 | Um plano por faixa de assentos; para trocar, cancelar e assinar o plano novo, compensando com cupom |
| Trial | Não na API v1 | Libere os dias grátis no seu app, sem pedir pagamento, e envie o link da assinatura no fim do prazo; a primeira cobrança acontece quando o cliente assina |
Se o seu modelo depende de cobrança por consumo automática ou de upgrade com pró-rata, isso é requisito, não detalhe: confira antes de escolher gateway. Para quem vende planos fixos mensais e anuais, assinatura fixa com boa política de falha resolve. Detalhes em /assinaturas.
Mensal ou anual: qual periodicidade cobra melhor?
O anual troca 12 oportunidades de falha por 1, mas essa única cobrança é grande e, no cartão, esbarra mais no limite. Ofereça o anual com desconto real (R$ 970 contra R$ 1.164 do mensal a R$ 97) e aceite o Pix à vista, onde limite não é problema. Para parcelar o anual no cartão, venda-o como pagamento avulso em até 12x, com os juros do parcelamento repassados ao comprador ou absorvidos por você. O mensal segue como porta de entrada, e é nele que a política de falha precisa ser impecável.
Parte 2. A anatomia do churn involuntário e a conta composta
O que é churn involuntário?
Churn involuntário é o cancelamento que ninguém pediu: o assinante queria continuar, mas a cobrança falhou e não foi recuperada. O churn voluntário é o cliente decidindo sair (preço, produto, concorrente). A distinção importa porque os remédios são opostos: churn voluntário se resolve com produto e sucesso do cliente; churn involuntário se resolve com engenharia de cobrança.
Por que a cobrança recorrente falha?
| Causa | O que aconteceu | Recuperável com retentativa? | O que resolve |
|---|---|---|---|
| Limite insuficiente | O cartão existe, mas não tem limite naquele dia | Sim, frequentemente | Retentativa em outro dia (após o fechamento da fatura do cliente), Pix Automático |
| Cartão expirado | A validade venceu entre um ciclo e outro | Não | Troca de cartão, aviso antes da expiração |
| Cartão cancelado, perdido ou roubado | O banco emitiu um cartão novo | Não | Troca de cartão |
| Bloqueio do emissor ou antifraude | O banco recusou por suspeita | Às vezes | Retentativa espaçada, contato do cliente com o banco |
| Instabilidade técnica | Timeout, adquirente fora | Sim | Retentativa curta |
| Boleto não pago | O cliente esqueceu, perdeu o e-mail | Não se aplica | Lembrete antes, recobrança depois |
| Pix Automático sem saldo | Conta sem saldo no dia do débito | Sim, pelas regras do BC | Retentativa do banco pagador, lembrete |
O Stripe separa esses casos em dois grupos: recusas "soft", que podem dar certo mais tarde, e "hard decline codes" (número incorreto, cartão perdido, cartão roubado, autorização revogada, entre outros), em que não adianta retentar sem um meio de pagamento novo (docs do Stripe, verificado em setembro/2026). As bandeiras também punem quem insiste: o blog da Vindi, atualizado em julho de 2026, registra que a Visa permite até 15 retentativas em 30 dias para códigos reversíveis e que a Mastercard exige intervalo mínimo de 24 horas entre tentativas na recorrência (Vindi). Retentar tudo, sem ler o motivo, é jogar dinheiro fora e ainda arriscar multa de bandeira.
Qual o tamanho do problema?
Boa parte dos números que circulam vem de fornecedores de ferramentas de recuperação, sem metodologia aberta. O dado primário que verificamos é o do Stripe: empresas que usam suas ferramentas de recuperação recuperam, em média, 55% dos pagamentos com falha (stripe.com/billing, verificado em 23/09/2026). Ou seja: mais da metade das falhas é recuperável, e quase metade não é, mesmo com a ferramenta mais madura do mercado. O número que importa é o seu, medido na Parte 5.
A conta composta: 100 assinantes × 5% de recusa por mês
A perda parece pequena no primeiro mês e enorme no décimo segundo, porque cada assinante perdido deixa de pagar todos os meses seguintes. Premissas: 100 assinantes a R$ 97 (MRR de R$ 9.700), 12 cobranças no ano, a primeira sai cheia, em cada renovação uma fração das cobranças falha sem recuperação e vira cancelamento, sem novas vendas e sem churn voluntário.
Cenário A: 5% de falhas não recuperadas por ciclo
| Cobrança | Assinantes ativos | Receita do ciclo | Perda acumulada no ano |
|---|---|---|---|
| 1ª | 100,00 | R$ 9.700,00 | R$ 0,00 |
| 3ª | 90,25 | R$ 8.754,25 | R$ 1.430,75 |
| 6ª | 77,38 | R$ 7.505,68 | R$ 6.807,83 |
| 9ª | 66,34 | R$ 6.435,18 | R$ 15.568,39 |
| 12ª | 56,88 | R$ 5.517,36 | R$ 27.229,86 |
Depois da 12ª renovação sobram 54 assinantes, e o MRR que entra no ano seguinte é de R$ 5.241,49: quase metade da base foi embora sem ninguém ter decidido sair.
Sensibilidade: e se você recuperar parte das falhas?
| Cenário (hipóteses, não promessa de recuperação) | Falha líquida por ciclo | Perda no ano | Receita devolvida vs. cenário A |
|---|---|---|---|
| A. Nenhuma recuperação | 5,0% | R$ 27.229,86 | R$ 0 |
| B. Recupera metade das falhas | 2,5% | R$ 14.743,36 | R$ 12.486,50 |
| C. Recupera 70% das falhas | 1,5% | R$ 9.138,67 | R$ 18.091,19 |
Leitura para o founder: numa base de R$ 9.700 de MRR, a diferença entre não tratar a falha e tratar bem vale entre R$ 12 mil e R$ 18 mil por ano. Para comparação, a tarifa do cartão no HeroPay para essa base inteira é de R$ 339 por mês (R$ 3,39 por cobrança de R$ 97). A política de falha pesa várias vezes mais no seu MRR do que meio ponto de taxa. E a conta escala linearmente: com 1.000 assinantes, multiplique tudo por 10.
Quer refazer com os seus números? A fórmula da perda anual é a soma, cobrança a cobrança, de (base inicial − base inicial × (1 − f)^(n−1)) × ticket, com f = falha líquida por ciclo e n de 1 a 12.
Parte 3. O arsenal anti-churn: retentativa, dunning, troca de cartão e Pix Automático
As quatro alavancas atacam causas diferentes. Nenhuma é opcional.
| Alavanca | Ataca | Não resolve | No HeroPay |
|---|---|---|---|
| Retentativa inteligente | Limite momentâneo, instabilidade, bloqueio temporário | Cartão expirado, cancelado, roubado | Reprocessamento automático da cobrança recusada |
| Régua de cobrança (dunning) | Esquecimento, desatenção, boleto perdido, cartão que precisa ser trocado | Cliente que decidiu sair | Gatilhos por evento (recusa, vencimento, chargeback, estorno) em e-mail ou webhook |
| Troca de cartão self-service | Cartão expirado, cancelado, substituído | Cliente sem limite em nenhum cartão | Troca pelo próprio assinante, sem ticket |
| Pix Automático como saída do cartão | Todo o problema de cartão (validade, limite, bloqueio) | Conta sem saldo no dia | Recorrência via Pix Automático a R$ 0 por cobrança |
Como funciona a retentativa inteligente?
Retentativa é cobrar de novo uma transação recusada. "Inteligente" significa não retentar o irrecuperável (hard decline), escolher o momento e respeitar as bandeiras. O Stripe Smart Retries, referência do mercado, usa IA para escolher os momentos e recomenda como padrão 8 tentativas em 2 semanas; ao fim, a assinatura fica canceled, unpaid ou past_due, conforme configuração. A Vindi documenta a Retentativa Simples, por padrão a cada 3 dias por 5 vezes (fontes no fim, verificado em setembro/2026).
No HeroPay, quando a renovação falha, a cobrança é reprocessada automaticamente, sem job de retentativa do seu lado, e as tentativas recusadas não pagam tarifa, porque o cartão só é tarifado em transação aprovada. Você recebe o webhook payment_credit_cart_refused com o motivo da operadora em payment_methods.credit_card.refused_message.
A documentação não detalha o calendário dessas tentativas. Por isso, dirija a sua régua pelo primeiro webhook de recusa e pelo webhook de pagamento confirmado, como na Parte 4, em vez de supor datas.
Boas práticas em qualquer gateway: leia o motivo antes de retentar (cartão roubado vai para a troca de cartão, não para a fila); espace as tentativas em pelo menos 24 horas; mire o começo do mês, quando salário e fechamento de fatura liberam limite; e feche a janela em 2 a 3 semanas.
O que é dunning e como ele se diferencia da régua de cobrança?
Dunning é o termo em inglês para o processo de recuperar pagamentos recorrentes que falharam: a combinação de retentativas e comunicações com o cliente até o pagamento ou o cancelamento. Régua de cobrança é o nome brasileiro para a sequência programada de avisos antes e depois do vencimento. Na prática, régua de cobrança é o dunning com o degrau preventivo (antes do vencimento) incluído. A Parte 4 monta uma, degrau por degrau.
Por que a troca de cartão self-service é obrigatória?
Porque cartão expirado ou substituído não se recupera com retentativa. Se trocar o cartão exigir abrir chamado ou mandar o número por WhatsApp (nunca faça isso: é risco de segurança e de PCI), parte dos assinantes desiste. A troca precisa ser um link de dois toques.
No HeroPay, a troca de cartão é self-service: o assinante cadastra o cartão novo sozinho, o número é tokenizado no ambiente do HeroPay e o seu sistema continua sem tocar em dado de cartão. A troca iniciada pelo seu backend, via API, não existe na v1.
Antes de lançar, faça o caminho completo no sandbox: assine, force uma recusa e veja como o assinante chega à troca de cartão. É esse caminho que entra em todo aviso de falha da régua.
Um complemento que alguns gateways oferecem é o account updater das bandeiras, que atualiza automaticamente o cartão reemitido pelo banco. A documentação do HeroPay não cita esse recurso, então não conte com ele: a sua melhor ferramenta preventiva é avisar o assinante antes de o cartão vencer: você sabe o mês de validade a partir do momento em que ele cadastra.
Pix Automático é a saída do cartão?
Para boa parte da base, sim. O Pix Automático, lançado pelo Banco Central em 16 de junho de 2025, permite que o cliente autorize uma vez no app do banco e que cada cobrança seja debitada da conta dele sem novo pagamento. Ele não expira, não depende de limite de cartão e não tem bandeira nem antifraude de emissor no caminho. Pelas regras do BC, o banco do cliente avisa antes de cada débito (com 2 a 10 dias de antecedência), o cliente pode definir um valor máximo e revogar quando quiser, e, se faltar saldo, o banco tenta de novo entre 18h e 21h do mesmo dia e pode tentar nos 7 dias seguintes quando a autorização prevê (FAQ Pix Automático do BC, itens 2.7, 4.4, 4.11 e 4.13; verificado em setembro/2026).
Ele não zera a falha (conta sem saldo falha), mas elimina as causas que retentativa não resolve. E no HeroPay cada cobrança por Pix Automático custa R$ 0, contra R$ 3,39 de uma cobrança de R$ 97 no cartão. Com 200 assinantes mensais a R$ 97, se metade migrar para o Pix Automático, a tarifa cai de R$ 678 para R$ 339 por mês, R$ 4.068 por ano a mais no caixa com os mesmos clientes.
Para migrar sem forçar ninguém, ofereça o Pix Automático no checkout ao lado do cartão e no aviso de falha do D+1 ("Não quer mais se preocupar com cartão? Autorize o Pix Automático"). Comparação completa na Parte 6.
Parte 4. A régua de cobrança perfeita, passo a passo, de D-3 a D+15
Uma régua de cobrança para SaaS tem dois objetivos que brigam entre si: recuperar o pagamento e não irritar quem está pagando. A régua abaixo resolve isso com uma regra simples: antes do vencimento, informe; depois da falha, facilite; só no fim, restrinja. D0 é a data da renovação.
| Degrau | Quando | Para quem | Canal | Mensagem (resumo) | Ação no sistema | Evento no HeroPay |
|---|---|---|---|---|---|---|
| 1. Lembrete | D-3 | Todos (boleto e cartão com validade vencendo; Pix Automático já recebe aviso do banco) | "Sua assinatura renova em 3 dias, R$ 97. Cartão final 4644 vence este mês? Atualize aqui." | Nenhuma | Seu agendador, a partir da data da renovação · spark_payment_boleto_created para o boleto do ciclo | |
| 2. Cobrança | D0 | Todos | E-mail (recibo) | "Pagamento confirmado. Obrigado." | Estende o acesso | spark_payment_confirmed + subscription_update |
| 3. Aviso de falha | D0/D+1 | Quem teve recusa | E-mail + aviso dentro do app | "Não conseguimos cobrar seu cartão (motivo). Seu acesso continua. Troque o cartão ou autorize o Pix Automático." | Banner no app; retentativa já em curso | payment_credit_cart_refused |
| 4. Reforço | D+3 | Quem ainda não pagou | WhatsApp ou SMS + e-mail | "Lembrete: sua assinatura está pendente. Leva 1 minuto." Link direto para a troca ou para o Pix. | Retentativa em curso | Seu agendador lê o status via webhook |
| 5. Acesso limitado | D+7 | Quem ainda não pagou | E-mail + app + WhatsApp | "Seu acesso vai ficar só-leitura em 48 horas. Seus dados estão salvos." | Modo leitura ou recurso premium bloqueado | Seu sistema, a partir do último pagamento |
| 6. Suspensão e volta | D+15 | Quem não pagou | "Suspendemos sua conta. Reative quando quiser, seus dados ficam guardados por X dias." Oferta de volta. | Suspende o acesso | subscription_cancel se o limite de atrasos for atingido |
Por que cada escolha:
- D-3 por e-mail. Antes do vencimento a mensagem é informativa; WhatsApp para quem está em dia soa como cobrança. Exceção: o boleto, que chega melhor onde o cliente lê.
- O D+1 diz "seu acesso continua". Tratar como inadimplente quem teve o cartão recusado empurra para o cancelamento voluntário.
- Todo degrau pós-falha leva um link de um toque para a troca de cartão ou o Pix Automático.
- O canal escala com a urgência: e-mail, depois app, depois WhatsApp/SMS.
- Restrinja antes de cancelar. Modo leitura no D+7 dá motivo concreto para pagar sem apagar nada.
- D+15 fecha a janela de retentativa, dentro do padrão do mercado (2 semanas no Stripe) e das regras de bandeira.
Como ligar a régua ao HeroPay, por código
A régua é dirigida por eventos: você não pergunta ao gateway se pagou, você ouve. Cadastre um webhook por gatilho:
curl -X POST "$HEROPAY_API_URL/webhook" \
-H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
-H "Accept: application/vnd.herospark.com; version=1" \
-H "Content-Type: application/json" \
-d '{
"webhook": {
"trigger": "payment_credit_cart_refused",
"webhook_url": "https://seuapp.com/webhooks/heropay",
"request_method": "post"
}
}'Repita para spark_payment_confirmed, subscription_update, subscription_cancel, spark_payment_boleto_created e chargeback_request. No seu endpoint:
- Valide o
X-HeroPay-Signature(HMAC SHA-256 do corpo bruto) antes de agir. - Deduplique por pagamento + gatilho, porque a retentativa do webhook pode entregar o mesmo evento duas vezes.
- Grave o estado da assinatura (ativa, pendente desde {data}, suspensa) e deixe seu agendador disparar D+3, D+7 e D+15 a partir da primeira recusa.
- Pare o fluxo no
spark_payment_confirmed. Nada irrita mais do que "sua assinatura está pendente" depois de pagar.
Confie no evento, não no polling. Quem tem CRM pluga os webhooks nele; quem não tem usa as automações por evento do próprio HeroPay. Ver /webhooks.
Antes de ligar a régua em produção, rode no sandbox uma assinatura, uma renovação e um cancelamento e confira os payloads de subscription_update e subscription_cancel na documentação de webhooks.
Parte 5. Métricas: MRR, churn líquido e recuperação, e como medir via API
Quais métricas de cobrança recorrente um SaaS precisa acompanhar?
| Métrica | Fórmula | Pergunta que responde |
|---|---|---|
| MRR | Soma das assinaturas ativas normalizada por mês (anual ÷ 12, semestral ÷ 6, trimestral ÷ 3) | Quanto entra por mês, de forma recorrente? |
| Churn de clientes | Assinantes cancelados no mês ÷ assinantes ativos no início do mês | Quantos estou perdendo? |
| Churn involuntário | Cancelamentos por falha de pagamento ÷ ativos no início do mês | Quanto da perda é cobrança, não produto? |
| Churn de receita bruto | (MRR perdido em cancelamentos + downgrades) ÷ MRR do início do mês | Quanto de receita some? |
| Churn de receita líquido | (MRR perdido − MRR de expansão da base existente) ÷ MRR do início | A base cresce ou encolhe sozinha? Negativo é ótimo. |
| Taxa de falha na renovação | Renovações recusadas na 1ª tentativa ÷ renovações tentadas | O tamanho do problema na entrada |
| Taxa de recuperação | Renovações recusadas que acabaram pagas na janela ÷ renovações recusadas | O quanto a sua política de falha funciona |
| Tempo até recuperar | Mediana de dias entre a 1ª recusa e o pagamento | Em qual degrau da régua o dinheiro volta |
| Mix de métodos | % do MRR em cartão, Pix Automático e boleto | Quanto da base está exposta a falha de cartão |
Separe sempre churn voluntário de involuntário: 6% de churn total pode ser 4% de produto e 2% de cobrança.
Como medir essas métricas pela API do HeroPay?
1. Liste as assinaturas com cada tentativa de cobrança. GET /sales/recurring devolve as assinaturas com status (cart.subscriptionStatus), periodicidade e a lista purchases, com cada tentativa de cobrança daquela assinatura. Pagina de 10 a 1.000 itens com skip e limit e filtra por status do pagamento, método, data de criação, nome e e-mail do comprador.
curl -G "$HEROPAY_API_URL/sales/recurring" \
-H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
-H "Accept: application/vnd.herospark.com; version=1" \
--data-urlencode "paymentMethod[]=credit_card" \
--data-urlencode "limit=1000" \
--data-urlencode "skip=0"{
"data": {
"sales": [
{
"buyer": { "fullName": "Maria Silva", "email": "maria@example.com" },
"cart": { "cartId": 54321, "subscriptionId": "sub-123", "subscriptionStatus": "active" },
"periodicity": "monthly",
"purchases": [
{ "purchaseId": "uuid-456", "unifiedStatus": "paid", "paymentMethod": "credit_card" }
]
}
],
"totalCount": 1
},
"message": "Vendas encontradas com sucesso"
}Com esse dado você calcula, no seu BI:
- MRR: soma das assinaturas com
subscriptionStatus: "active", normalizada pelaperiodicity. - Taxa de falha e de recuperação: para cada ciclo, olhe a sequência de
purchases; uma sequência que começa recusada e terminapaiddentro da janela é uma recuperação. - Mix de métodos: agrupe por
paymentMethod.
2. Use os relatórios prontos. Os endpoints /reports/purchase/subscriptions/* devolvem receita bruta, líquida e após taxas da recorrência, contagem de assinaturas por status, vendas mensais e mais vendidos. /reports/purchase/refused/reasons_count agrupa os motivos de recusa: é o relatório que diz se o seu problema é limite (retentativa e Pix Automático), cartão vencido (troca de cartão) ou antifraude (contato com o banco).
3. Registre o motivo do cancelamento. Ao receber subscription_cancel, grave se foi pedido do cliente, estorno, chargeback ou limite de atrasos. É assim que você separa churn voluntário de involuntário sem adivinhar.
Honestidade: o MRR e a taxa de recuperação não vêm prontos como métrica na API; você calcula com os dados acima.
Antes de montar o BI, confira no sandbox em que campo de purchases vem o valor e o status de cada cobrança, e como você vai ligar a venda recorrente ao cancelamento recebido por webhook.
Por prompt: cole o llms.txt no Claude, ChatGPT, Cursor, Lovable e outros e peça "escreve um script que calcula o MRR das assinaturas ativas e mostra os 5 motivos de recusa mais frequentes do último mês". A ferramenta gera o código que chama esses endpoints da API REST. O MCP server do HeroPay está em desenvolvimento; o caminho atual está em /ai.
Qual é uma boa taxa de churn para SaaS?
Depende de B2B ou B2C e do ticket. Um artigo do Stripe (atualizado em fevereiro/2024) cita software e serviços de TI entre os setores de menor churn mediano anual, 14% e 12% (Stripe). Use como referência distante; o que manda é a sua tendência e a parcela involuntária.
Parte 6. Pix Automático vs cartão vs boleto na recorrência
| Critério | Pix Automático | Cartão de crédito | Boleto |
|---|---|---|---|
| Tarifa no HeroPay por cobrança | R$ 0 | 3,49% por transação aprovada | R$ 0 |
| Tarifa numa assinatura de R$ 97 | R$ 0 | R$ 3,39 | R$ 0 |
| Autorização | Uma vez, no app do banco | Uma vez, cartão tokenizado no checkout | Não há: um boleto por ciclo |
| O cliente precisa agir a cada ciclo? | Não | Não | Sim, pagar o boleto |
| Expira? | Não (vale até o cliente revogar) | Sim, na validade do cartão | Não se aplica |
| Depende de limite? | Não, de saldo em conta | Sim | Não |
| Falha típica | Sem saldo no dia | Limite, validade, bloqueio, cartão novo | Esquecimento |
| Retentativa | Pelo banco pagador: 18h-21h do mesmo dia e até 7 dias depois, se a autorização prever (regra do BC) | Reprocessamento automático do HeroPay | Recobrança de boleto (+4 dias) |
| Aviso antes do débito | Obrigatório, pelo banco do cliente, 2 a 10 dias antes | Você envia (régua D-3) | Você envia o boleto |
| Cancelamento pelo cliente | No app do banco, a qualquer momento | Pede a você ou contesta no banco | Basta não pagar |
| Risco de chargeback | Não há chargeback de cartão | Existe | Não há |
| Melhor para | Base brasileira sem cartão ou com limite apertado; ticket mensal baixo e médio | Conversão no primeiro pagamento, ticket anual parcelado | B2B que paga por boleto, clientes sem cartão nem hábito de Pix Automático |
Tarifas do HeroPay: /precos. Regras do Pix Automático: FAQ Pix Automático do BC. Verificado em setembro/2026.
Qual método escolher para o meu SaaS?
Não escolha: ofereça os três na mesma assinatura e deixe o cliente decidir. No HeroPay, isso é o campo payment_methods: ["credit_card", "pix", "bank_slip"] no POST /payment_links. O cartão continua sendo a forma de maior conversão no primeiro pagamento para muita gente; o Pix Automático é a forma de menor churn involuntário e custo zero; o boleto atende o B2B e quem não tem nenhum dos dois. Três portas de pagamento significam que o assinante com o cartão recusado sempre tem para onde ir. Um detalhe de regra: o Pix Automático exige recebedor com CNPJ, por norma do Banco Central; quem vende com CPF oferece cartão e boleto na assinatura.
Parte 7. Impostos e nota fiscal em linhas gerais
Esta parte é orientação geral, não aconselhamento tributário. Regime, município e enquadramento mudam a conta: confirme tudo com o seu contador.
Que imposto incide sobre assinatura de SaaS?
Em linhas gerais, SaaS é tratado como serviço, sujeito ao ISS municipal. O enquadramento mais citado é o item 1.05 da Lei Complementar 116/2003 (licenciamento de programas de computação), que o STF tratou como serviço em 2021; há quem enquadre em outros itens, como processamento de dados. Somam-se os tributos federais do seu regime; no Simples, software costuma cair no Anexo III ou V conforme o Fator R.
O que muda com a reforma tributária?
A Emenda Constitucional 132/2023 e a Lei Complementar 214/2025 substituem gradualmente ISS, ICMS, PIS e Cofins por IBS e CBS, com os dois sistemas convivendo de 2026 a 2033 e os campos novos exigidos na nota em ondas, por regime e tipo de serviço. Na prática: mantenha o emissor de NFS-e atualizado e revise preço e margem com o contador durante a transição.
Preciso emitir nota fiscal em cada cobrança recorrente?
Em geral, sim: cada ciclo pago é uma prestação de serviço. Automatize: o webhook spark_payment_confirmed dispara a NFS-e no seu emissor com os dados do comprador do payload, e o estorno dispara o cancelamento. Não confunda a sua nota (serviço ao cliente) com a do gateway (sobre a tarifa). A emissão da sua NFS-e fica com o seu emissor e o seu contador.
Coloque em prática
Do zero a uma cobrança recorrente com política de falha, no sandbox, em uma tarde:
- Crie o plano.
POST /payment_linkscomprice_cents: 9700,period: "monthly",frequency_type: "unlimited"e os três métodos. Odata.offer.urlda resposta vai no botão "Assinar" da sua página de preços. Referência em /assinaturas. - Cadastre os seis webhooks da régua (
spark_payment_confirmed,subscription_update,payment_credit_cart_refused,spark_payment_boleto_created,subscription_cancel,chargeback_request) e valide oX-HeroPay-Signature. Ver /webhooks. - Escreva os degraus D+3, D+7 e D+15 no seu agendador, disparados a partir da primeira recusa e cancelados no primeiro pagamento.
- Ofereça Pix Automático no checkout e no aviso de falha. Ver /pix-automatico.
- Monte o painel de métricas com
GET /sales/recurringe os relatórios de assinaturas e de recusadas. - Vá para produção trocando a chave. O sandbox é idêntico à produção, sem homologação.
Custo da recorrência no HeroPay: sem mensalidade, sem ativação, sem taxa extra pela assinatura. Pix R$ 0, boleto R$ 0, cartão 3,49% por transação aprovada. Recusas não pagam tarifa. Tabela em /precos.
Criar conta sandbox Ler a documentação
Mitos e verdades sobre cobrança recorrente
"Churn involuntário é pequeno, só uns cartões que falham." Mito. A perda é composta: 5% de falhas não recuperadas por ciclo levam quase metade de uma base em 12 meses. O que parece R$ 485 no primeiro ciclo vira R$ 27 mil no ano numa base de R$ 9.700 de MRR.
"Retentar muitas vezes resolve." Mito. Retentativa não recupera cartão expirado, cancelado ou roubado, e as bandeiras limitam e penalizam retentativas em excesso (Visa até 15 em 30 dias para códigos reversíveis, Mastercard com 24 horas de intervalo mínimo na recorrência, segundo a Vindi).
"Pix Automático acaba com a falha de pagamento." Mito. Conta sem saldo falha no Pix Automático também. Verdade: ele elimina as falhas de cartão (validade, limite, bloqueio, cartão novo), que retentativa não resolve, e o BC obriga o banco pagador a retentar no mesmo dia.
"Cortar o acesso no primeiro dia de atraso faz o cliente pagar mais rápido." Mito para SaaS. A maior parte de quem teve o cartão recusado quer continuar. Cortar no D+1 transforma falha técnica em irritação e cancelamento voluntário. Restrinja no D+7, suspenda no D+15.
"Plano anual elimina o churn involuntário." Meia-verdade. Reduz 12 eventos de cobrança para 1, mas a renovação anual é grande e esbarra mais no limite. Ofereça parcelamento no cartão ou Pix à vista.
"Taxa baixa é o que mais importa na recorrência." Mito. Na base de 100 assinantes a R$ 97, a tarifa do cartão inteira é R$ 339 por mês; recuperar metade das falhas vale R$ 12.486,50 no ano. Taxa importa (e no HeroPay Pix e boleto são R$ 0), mas a política de falha pesa mais.
"Preciso de uma ferramenta de billing separada do gateway." Depende: para assinatura fixa, gateway com retentativa, troca de cartão e webhooks resolve; para uso, pró-rata e trial, hoje você precisa de algo além do HeroPay v1.
Glossário do tema
- Cobrança recorrente: cobrança automática de um valor em intervalos definidos, a partir de uma autorização única do cliente.
- Churn involuntário: cancelamento causado por falha de pagamento não recuperada, sem decisão do cliente de sair.
- Dunning: processo de recuperar pagamentos recorrentes que falharam, com retentativas e comunicações ao cliente.
- Régua de cobrança: sequência programada de avisos e ações antes e depois do vencimento.
- Retentativa: nova tentativa de cobrar uma transação recusada.
- Hard decline: recusa definitiva do emissor (cartão cancelado, roubado, número inválido) em que retentar não adianta.
- MRR: receita recorrente mensal, a soma das assinaturas ativas normalizada por mês.
- Pró-rata: cobrança ou crédito proporcional aos dias usados quando o plano muda no meio do ciclo.
- Pix Automático: modalidade do Pix em que o cliente autoriza uma vez e o banco dele debita cada cobrança recorrente.
- Tokenização: troca do número do cartão por um token guardado no ambiente do gateway, para cobrar sem armazenar o cartão.
Perguntas frequentes sobre cobrança recorrente para SaaS
O que é cobrança recorrente?
Cobrança recorrente é a cobrança automática de um valor em intervalos definidos, como mensal, trimestral ou anual, enquanto o contrato do cliente estiver ativo. O cliente autoriza uma vez, com cartão tokenizado, Pix Automático ou cadastro para boleto, e o sistema cobra cada ciclo sem ação manual. Para um SaaS, o ponto crítico é tratar a falha: retentar o recuperável, facilitar a troca de cartão e avisar com uma régua de cobrança. No HeroPay, é um link de pagamento com o campo period.
Qual a diferença entre cobrança recorrente e pagamento recorrente?
São o mesmo processo visto de lados opostos: a empresa cobra um valor em intervalos fixos, o cliente autoriza uma vez e paga automaticamente a cada ciclo. Nenhum dos dois é parcelamento: no parcelado a compra única é aprovada inteira de uma vez; na recorrência, cada ciclo é uma transação nova, aprovada ou recusada naquele dia.
O que é churn involuntário?
É o assinante que sai sem ter decidido sair: a renovação falhou por cartão expirado, limite, bloqueio, cartão substituído, boleto não pago ou falta de saldo no Pix Automático, e ninguém recuperou. Por ser um problema do meio de pagamento, é o churn mais recuperável, com retentativa, troca de cartão self-service, régua de cobrança e Pix Automático.
Quanto o churn involuntário custa para um SaaS?
A perda é composta. Numa base de 100 assinantes a R$ 97, com 5% das renovações falhando por ciclo sem recuperação, a perda em 12 meses é de R$ 27.229,86 e a base termina o ano com 54 assinantes. Recuperar metade das falhas devolve R$ 12.486,50 no ano; recuperar 70% devolve R$ 18.091,19. São hipóteses de sensibilidade, não taxas prometidas.
O que é dunning?
Dunning é o processo de recuperar pagamentos recorrentes que falharam, combinando retentativas automáticas com comunicações ao cliente até o pagamento ou o cancelamento. No Brasil, o nome mais comum é régua de cobrança, que inclui o degrau preventivo antes do vencimento. Um bom dunning lê o motivo da recusa, não retenta o irrecuperável, espaça as tentativas e oferece link de um toque para trocar o cartão.
Como montar uma régua de cobrança para SaaS?
Seis degraus: D-3 lembrete por e-mail; D0 cobrança e recibo; D0/D+1 aviso de falha por e-mail e no app, com link de troca de cartão ou Pix Automático; D+3 reforço por WhatsApp ou SMS; D+7 acesso limitado; D+15 suspensão com dados preservados e oferta de volta. O fluxo para no primeiro pagamento confirmado.
Quantas vezes posso retentar uma cobrança recusada no cartão?
Segundo a Vindi, a Visa permite até 15 retentativas em 30 dias para códigos reversíveis e a Mastercard exige 24 horas de intervalo mínimo na recorrência; recusas irreversíveis não devem ser retentadas. O Stripe recomenda 8 tentativas em 2 semanas com Smart Retries. Uma janela de 2 a 3 semanas, com tentativas espaçadas, cobre a maior parte das recuperações.
O Pix Automático serve para cobrar assinatura de SaaS?
Serve. O cliente autoriza uma vez no app do banco e cada ciclo é debitado sem novo pagamento; a autorização não expira nem depende de limite de cartão. O banco avisa de 2 a 10 dias antes de cada débito e, sem saldo, tenta de novo no mesmo dia e pode tentar nos 7 dias seguintes se a autorização prevê. No HeroPay, cada cobrança por Pix Automático custa R$ 0.
Cartão, Pix Automático ou boleto: qual é melhor para recorrência?
Ofereça os três. O cartão converte bem no primeiro pagamento mas falha por validade, limite e bloqueio, e no HeroPay custa 3,49% por cobrança aprovada. O Pix Automático não expira, não usa limite e custa R$ 0. O boleto custa R$ 0 e atende o B2B, mas exige pagamento a cada ciclo.
Como calcular MRR e taxa de recuperação?
MRR é a soma das assinaturas ativas normalizada por mês (anual dividido por 12, semestral por 6, trimestral por 3). Taxa de recuperação é o número de renovações recusadas que acabaram pagas na janela, dividido pelo total de renovações recusadas. No HeroPay, GET /sales/recurring traz status, periodicidade e cada tentativa de cobrança para calcular as duas no seu BI.
O que é churn líquido de receita?
É o MRR perdido no mês em cancelamentos e downgrades, menos o MRR ganho com expansão da própria base, dividido pelo MRR do início do mês. Quando a expansão supera a perda, o churn líquido fica negativo e a base cresce sem clientes novos. Reduzir churn involuntário melhora o churn bruto e o líquido.
O HeroPay tem trial, pró-rata e cobrança por uso?
Não na API v1. A recorrência do HeroPay é assinatura de valor fixo por ciclo, ilimitada ou com número fechado de cobranças. Para trocar de plano, cancela-se e assina-se o plano novo. Cobrança por uso pode ser feita com link avulso por fatura, que o cliente paga, mas não é débito automático. Stripe Billing, iugu e AbacatePay documentam esses recursos.
Quanto custa fazer cobrança recorrente no HeroPay?
Não há mensalidade, ativação nem taxa extra pela recorrência. Cada ciclo paga a tarifa da transação aprovada: Pix Automático R$ 0, boleto R$ 0 e cartão 3,49% (ver preços). Numa assinatura de R$ 97 no cartão, a tarifa é de R$ 3,39 por cobrança. Cobranças recusadas não pagam tarifa.
Preciso emitir nota fiscal a cada cobrança recorrente?
Em geral, sim: cada ciclo pago é uma prestação de serviço e pede NFS-e. O mais seguro é automatizar pelo evento de pagamento confirmado, emitindo só do que foi pago e cancelando em caso de estorno. SaaS costuma recolher ISS, com enquadramento mais citado no item 1.05 da LC 116, e a reforma tributária introduz IBS e CBS de forma gradual. Confirme com o seu contador.
Continue aprendendo
- Assinaturas e cobrança recorrente no HeroPay: campos da API, webhooks, cancelamento e limites.
- Pix Automático: regras do Banco Central e como cobrar assinatura sem cartão.
- Guia de chargeback: o que fazer quando o assinante contesta no banco.
- Webhooks: HMAC, retry e deduplicação.
- Checkout: troca de cartão, recobrança e relatório de recusadas.
- Preços · Stripe vs HeroPay · Desenvolvedores · HeroPay para IA · Glossário
Fontes e verificação
Todas as fontes abaixo foram consultadas em 23 de setembro de 2026. Nenhuma taxa de concorrente foi citada neste guia.
- Stripe, Smart Retries (padrão recomendado de 8 tentativas em 2 semanas, janelas de 1 semana a 2 meses, hard decline codes, estados finais
canceled/unpaid/past_due): docs.stripe.com/billing/revenue-recovery/smart-retries - Stripe Billing (empresas recuperam 55% dos pagamentos com falha, em média): stripe.com/billing
- Stripe, Involuntary churn 101 (atualizado em 17/02/2024; churn mediano anual de software e serviços de TI): stripe.com/resources
- Vindi, regras de retentativa das bandeiras (atualizado em 17/07/2026; Visa até 15 em 30 dias, Mastercard intervalo mínimo de 24 h na recorrência): blog.vindi.com.br
- Vindi, Retentativa Simples (padrão a cada 3 dias por 5 vezes): blog.vindi.com.br · Retentativa com troca de perfil: atendimento.vindi.com.br
- iugu, alterar assinatura (pró-rata em upgrade e downgrade): dev.iugu.com
- AbacatePay, documentação (trial, troca de plano, cobrança por uso): docs.abacatepay.com
- Banco Central, FAQ Pix Automático (itens 2.7, 4.4, 4.11, 4.13; lançamento em 16/06/2025): bcb.gov.br
- Legislação: Lei Complementar 116/2003 (lista de serviços do ISS), Emenda Constitucional 132/2023 e Lei Complementar 214/2025 (IBS e CBS).
- HeroPay: referência OpenAPI v1 (docs.heropay.tech) e tabela de /precos.
- Contas deste guia: cálculo próprio, premissas descritas na Parte 2, reproduzível pela fórmula indicada.