O HeroPay é um gateway de pagamento para SaaS que cobra a assinatura do seu cliente no cartão, no boleto ou por Pix Automático, refaz sozinho a cobrança que falhou e avisa o seu backend de cada mudança por webhook assinado. Você cria um plano com uma chamada POST /payment_links com period, coloca a URL no botão "Assinar" e libera ou suspende o acesso pelos eventos subscription_activate e subscription_cancel. Não há mensalidade nem taxa extra de billing: cada cobrança paga Pix R$ 0, boleto R$ 0 ou cartão 3,49% por transação aprovada (ver preços). Serve para SaaS B2B e B2C com plano mensal, trimestral, semestral ou anual e preço fixo por ciclo.
Criar conta sandbox Ler a documentação
O essencial em 60 segundos
- No HeroPay, o plano do seu SaaS é um link de pagamento com
period(monthly,quarterly,semiannualouannual); o checkout hospedado cobra o primeiro ciclo e o HeroPay cobra os seguintes sozinho. - A recorrência aceita cartão, boleto e Pix Automático na mesma assinatura, o que dá ao cliente B2B uma saída quando o cartão corporativo estoura o limite ou expira.
- Churn involuntário é o cliente que queria continuar e caiu por falha de pagamento; o HeroPay reprocessa a cobrança, oferece troca de cartão self-service e dispara
payment_credit_cart_refusedcom o motivo da operadora. - Numa base de 300 clientes a R$ 297, 3% de falha por mês sem recuperação custa R$ 187 mil de receita em 12 meses (conta com premissas abaixo).
- Billing sem custo fixo: não há mensalidade, ativação, mínimo nem taxa por usar recorrência; cobrança recusada não paga tarifa.
- O ciclo de vida inteiro chega por webhook assinado com
X-HeroPay-Signature(HMAC SHA-256 do corpo bruto), eGET /sales/recurringalimenta o seu BI de MRR. - O que não existe na v1, dito antes: troca de plano com pró-rata, período de teste (trial) e cobrança por uso. Se o seu pricing depende disso, leia a seção de limites.
Dor 1: o churn involuntário come a base sem ninguém pedir para sair
A dor em uma frase: o cliente gosta do produto, mas o cartão da empresa expirou, bateu no limite ou foi trocado, a renovação falhou e a conta foi suspensa sem que ninguém decidisse cancelar.
O que resolve no HeroPay: reprocessamento automático da renovação, troca de cartão feita pelo próprio assinante, três métodos na mesma assinatura e o webhook payment_credit_cart_refused com o motivo em payment_methods.credit_card.refused_message, para o seu app mostrar o aviso certo na hora. A mecânica completa está em /assinaturas.
A conta em reais:
| Cenário (12 meses) | Sem recuperação | Recuperando metade das falhas (hipótese) |
|---|---|---|
| Base inicial | 300 clientes × R$ 297 = R$ 89.100 de MRR | 300 clientes × R$ 297 = R$ 89.100 de MRR |
| Falha de pagamento que vira cancelamento | 3% ao mês | 1,5% ao mês |
| Perda só no primeiro mês | R$ 2.673 | R$ 1.336,50 |
| Clientes ativos no mês 12 | 208 | 250 |
| MRR no mês 12 | R$ 61.821,35 | R$ 74.321,16 |
| Receita que deixou de entrar no ano | R$ 187.190,46 | R$ 98.722,73 |
Premissas: sem vendas novas, sem churn voluntário, perda composta mês a mês, toda falha não recuperada vira cancelamento no mesmo mês. A coluna da direita é hipótese de sensibilidade, não taxa de recuperação prometida pelo HeroPay.
Leitura: recuperar metade das falhas devolve R$ 88.467,72 no ano para a mesma base, sem uma venda nova. Nenhum desconto de taxa chega perto disso, e é por isso que a primeira pergunta ao escolher billing para SaaS é "o que acontece quando o cartão falha?", não "quanto custa a transação?".
Dor 2: a taxa do gateway come o MRR todo mês
A dor em uma frase: em SaaS a taxa não é cobrada uma vez, ela se repete em cada renovação de cada cliente para sempre, e um ponto de diferença vira uma linha fixa no DRE.
O que resolve no HeroPay: Pix Automático e boleto a R$ 0 por cobrança, cartão a 3,49% só na transação aprovada, sem taxa extra de billing. Oferecer Pix Automático na página de preços empurra parte da base para o método de custo zero sem mudar o preço do plano.
A conta em reais (300 clientes a R$ 297 por mês):
| Mix de pagamento | Tarifa por cobrança | Tarifa por mês | Tarifa por ano |
|---|---|---|---|
| 100% cartão no HeroPay | R$ 10,37 | R$ 3.109,59 | R$ 37.315,08 |
| 60% cartão + 40% Pix Automático ou boleto no HeroPay | R$ 10,37 no cartão, R$ 0 no Pix/boleto | R$ 1.865,75 | R$ 22.389,05 |
| 100% cartão no Stripe Brasil (3,99% + R$ 0,39) | R$ 12,24 | R$ 3.672,09 | R$ 44.065,08 |
Tarifas do HeroPay conforme /precos. Stripe Brasil conforme stripe.com/br/pricing, verificado em setembro de 2026, sem somar o Stripe Billing, que é cobrado à parte; no Stripe o Pix custa 1,19% e só está disponível por convite.
Leitura: tirar 40% da base do cartão economiza R$ 14.926,03 por ano com os mesmos clientes. Contra o Stripe, a diferença no cartão puro é de R$ 6.750 por ano nesta base, a favor do HeroPay. Honestidade: contra o Asaas, que publica cartão à vista a 2,99% + R$ 0,49, o nosso cartão sai mais caro em cobranças acima de R$ 98 (num plano de R$ 297, R$ 9,37 no Asaas contra R$ 10,37 no HeroPay); a vantagem do HeroPay aparece no Pix e no boleto a R$ 0 e na recuperação. Comparação completa em Asaas vs HeroPay.
Dor 3: o billing trava o roadmap
A dor em uma frase: todo SaaS começa achando que cobrança recorrente é um cron job, e seis meses depois o time está mantendo retentativa, tela de troca de cartão, régua de e-mail, conciliação e emissão de boleto em vez de construir o produto.
O que resolve no HeroPay: o checkout hospedado (o cartão é tokenizado fora do seu servidor, então seu escopo de PCI DSS fica mínimo), a cobrança de cada ciclo, a retentativa, a troca de cartão self-service e os gatilhos de régua por evento vêm prontos. O seu código faz três coisas: cria o plano, escuta o webhook e cancela por API. O sandbox é gratuito, idêntico à produção e sem homologação: você vai ao ar trocando a chave. E se o time usa Claude, ChatGPT, Cursor, Lovable e outros, a integração sai por prompt: cole o heropay.tech/llms.txt na ferramenta e ela passa a conhecer a API e as docs abertas (veja /ai).
A conta em reais (hipótese, troque pelo seu número): se um dev custa R$ 15.000 por mês para a empresa e construir retentativa, troca de cartão, régua e conciliação toma dois meses, são R$ 30.000 antes da primeira manutenção, e o mesmo dev deixou de entregar dois meses de roadmap. Integrar o fluxo de três chamadas do HeroPay cabe em um dia de trabalho no sandbox.
Como um SaaS pluga o HeroPay (arquitetura típica)
Página de preços ──► data.offer.url?src=<id-da-conta> (checkout hospedado HeroPay)
│
▼ primeiro pagamento
HeroPay ──webhook──► POST /webhooks/heropay (seu backend)
subscription_activate → cria/ativa a conta do tenant
spark_payment_confirmed → estende o acesso, registra a fatura
payment_credit_cart_refused→ banner "atualize o pagamento" no app
subscription_cancel → suspende o acesso
Seu backend ──► POST /recurring_payment/cancel (cliente cancelou no seu app)
Seu BI ──► GET /sales/recurring + /reports/purchase/subscriptions/*1. Um link por plano, criado uma vez
curl -X POST "$HEROPAY_API_URL/payment_links" \
-H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
-H "Accept: application/vnd.herospark.com; version=1" \
-H "Content-Type: application/json" \
-d '{
"payment_link": {
"name": "Plano Business mensal",
"description": "Plano Business, cobrado todo mês",
"price_cents": 29700,
"absorbs_fees": true,
"period": "monthly",
"frequency_type": "unlimited",
"payment_methods": ["credit_card", "pix", "bank_slip"]
}
}'A resposta 201 Created traz o checkout em data.offer.url. Grave o id do link no seu banco (a v1 não tem Idempotency-Key, então repetir a chamada cria um segundo plano). Para o plano anual, crie outro link com "period": "annual".
2. Amarre a assinatura ao tenant com src
O HeroPay captura o query param src da URL do link e devolve em cart.src em todo webhook daquele comprador. Em vez de criar um link por cliente, anexe o ID da conta do seu SaaS na URL do plano:
https://<data.offer.url>?src=acct-8841src aceita letras, números e . _ - ~, até 255 caracteres. Quando subscription_activate chegar com cart.src = "acct-8841", você sabe exatamente qual tenant ativar, sem depender de o e-mail do pagador ser o mesmo do usuário admin (em B2B quase nunca é).
3. Escute os eventos e valide a assinatura
Cadastre um webhook por gatilho com POST /webhook (subscription_activate, spark_payment_confirmed, payment_credit_cart_refused, subscription_update, subscription_cancel). Valide o header X-HeroPay-Signature (HMAC SHA-256 do corpo bruto com o segredo do seu webhook), deduplique por pagamento + gatilho e só então mude o estado da conta. Confie no evento, não no polling. Código de validação em /webhooks.
4. Cancele e meça pela API
POST /recurring_payment/cancel com recurring_payment_id encerra a assinatura na hora (não existe "cancelar no fim do período": controle isso do seu lado com a data do último pagamento). GET /sales/recurring lista assinaturas com status, periodicidade e cada tentativa de cobrança; os relatórios /reports/purchase/subscriptions/* dão receita bruta, líquida e contagem por status, e /reports/purchase/refused/reasons_count mostra por que os cartões falham. O MRR você calcula no seu BI, normalizando pela periodicidade.
Mini-case ilustrativo: do "Assinar" ao cartão que venceu
Fluxo narrado para mostrar a mecânica. Não é um cliente real e não traz números de resultado.
Um SaaS de gestão para clínicas tem dois planos, mensal e anual, cada um com um link criado uma vez pela API. A página de preços monta o botão com ?src= e o ID da clínica que acabou de fazer o cadastro.
A recepcionista da clínica assina com o cartão da empresa. O subscription_activate chega com cart.src da clínica, o backend valida o HMAC, marca a conta como ativa e o time de onboarding recebe o aviso no Slack interno.
Onze meses depois, o cartão da clínica vence. A renovação é recusada, o HeroPay começa o reprocessamento e o backend recebe payment_credit_cart_refused com o motivo da operadora. O app mostra um banner para o admin: "o pagamento falhou, troque o cartão ou mude para Pix Automático". A dona da clínica troca o cartão pelo fluxo self-service do HeroPay; o pagamento confirma, chegam spark_payment_confirmed e subscription_update, e o banner some. Ninguém do suporte foi acionado e ninguém do time escreveu job de retentativa.
Se a clínica não tivesse feito nada até o limite de atrasos, chegaria subscription_cancel, o acesso seria suspenso e o CRM dispararia a oferta de volta.
O que um SaaS usa do HeroPay
| Necessidade do SaaS | Recurso do HeroPay | Onde está |
|---|---|---|
| Plano mensal, trimestral, semestral ou anual | Link de pagamento com period | /assinaturas · POST /payment_links |
| Contrato com duração fechada (ex.: 12 meses) | frequency_type: "limited" + frequency_limit | /assinaturas |
| Cobrar sem cartão | Pix Automático e boleto recorrente, R$ 0 por cobrança | /pix-automatico |
| Checkout sem PCI no seu front | Checkout hospedado, Apple Pay e Google Pay, 2 cartões | /checkout |
| Saber qual tenant pagou | src na URL, devolvido em cart.src | /link-de-pagamento |
| Liberar e suspender acesso | Webhooks assinados com HMAC e retry | /webhooks |
| Recuperar falha de pagamento | Reprocessamento automático e troca de cartão self-service | /assinaturas |
| Régua de cobrança | Gatilhos por evento (recusa, vencimento, chargeback, estorno) | /guias/cobranca-recorrente-saas |
| Cancelamento dentro do app | POST /recurring_payment/cancel | docs |
| MRR, churn e motivos de recusa | GET /sales/recurring, /reports/purchase/subscriptions/, /reports/purchase/refused/ | docs: relatórios |
| Integrar por IA | llms.txt público, docs abertas e API REST (MCP server em desenvolvimento) | /ai |
Limites honestos para SaaS
- Sem troca de plano com pró-rata na v1. Upgrade ou downgrade é cancelar a assinatura atual e assinar o plano novo; compense dias não usados com cupom.
- Sem trial nativo e sem cobrança por uso (metered billing). O valor é fixo por ciclo. Trial você controla no seu app antes de mandar o cliente ao checkout.
- Preço por assento (per seat) não existe como campo. Para cobrar por usuário, crie um link por faixa de assentos.
- Cancelamento imediato e irreversível pela API; não há "cancelar no fim do período".
- Troca de cartão só pelo assinante, no fluxo self-service; seu backend não troca cartão por endpoint. Nos avisos do seu app, oriente o assinante a atualizar o pagamento por esse fluxo.
- Pix Automático exige recebedor com CNPJ (regra do Banco Central). Conta aberta com CPF cobra a recorrência no cartão e no boleto.
- Pagamento internacional não vale para link recorrente; se você vende assinatura para fora do Brasil, isso hoje não está coberto.
- Nota fiscal de serviço: o relatório
/reports/transaction/paid/fiscal_receiptajuda a conciliar o que foi pago, mas a emissão da NFS-e do seu SaaS fica com o seu emissor fiscal: use o relatório para conferir o que emitir.
Onde os outros são melhores: o Stripe Billing e a iugu documentam troca de plano com pró-rata; o Stripe e a AbacatePay têm trial e cobrança por uso. Se o seu pricing é baseado em consumo, compare antes em Stripe vs HeroPay.
Perguntas frequentes de SaaS
Qual o melhor gateway de pagamento para SaaS no Brasil?
Depende do seu pricing. Para SaaS com plano de preço fixo por ciclo vendido no Brasil, os critérios que mais pesam são: aceitar cartão, boleto e Pix Automático na mesma assinatura, recuperar falha de pagamento sem código seu, avisar por webhook assinado e não cobrar mensalidade de billing. O HeroPay entrega isso com Pix e boleto a R$ 0 e cartão a 3,49%. Se você precisa de pró-rata, trial nativo ou cobrança por uso, Stripe Billing e iugu cobrem melhor esse caso hoje. A comparação de taxas está em /precos e o ranking em /melhores-gateways-de-pagamento.
O que é billing de SaaS?
Billing de SaaS é o conjunto de processos que transforma um plano em dinheiro recorrente: guardar a autorização de pagamento do cliente, cobrar cada ciclo na data certa, tratar falhas, controlar o acesso conforme o status do pagamento e medir MRR e churn. Pode ser construído dentro de casa ou delegado a um gateway com recorrência. No HeroPay, a cobrança, a retentativa, a troca de cartão e a régua por evento ficam do lado do gateway; o seu sistema recebe webhooks e decide o que fazer com o acesso.
Como evitar churn involuntário em SaaS?
Com quatro frentes: retentar automaticamente as falhas recuperáveis, facilitar a troca de cartão quando retentar não resolve, oferecer método que não depende de cartão e avisar o cliente antes e depois do vencimento. No HeroPay, o reprocessamento e a troca de cartão self-service vêm prontos, o Pix Automático e o boleto entram na mesma assinatura e o webhook payment_credit_cart_refused traz o motivo da recusa para o seu app avisar o admin da conta. Numa base de 300 clientes a R$ 297, 3% de falha por mês sem tratamento custa cerca de R$ 187 mil em um ano.
Cliente B2B pode pagar a assinatura por boleto?
Pode. A recorrência do HeroPay aceita boleto além de cartão e Pix Automático, e o boleto custa R$ 0 por cobrança. Isso importa em SaaS B2B, em que o financeiro do cliente muitas vezes não quer deixar cartão cadastrado. Cadastre o webhook spark_payment_boleto_created para enviar o boleto de cada ciclo pelo seu canal (e-mail do financeiro, WhatsApp, área de faturas do app) e spark_payment_confirmed para registrar o pagamento. O lembrete de vencimento reduz o atraso antes de ele virar cancelamento.
Como faço upgrade e downgrade de plano?
Na v1 da API não existe endpoint de troca de plano nem cálculo de pró-rata. O caminho hoje é cancelar a assinatura atual com POST /recurring_payment/cancel e o cliente assinar o novo plano pelo link correspondente, com o mesmo src do tenant para o seu backend reconhecer a conta. Para compensar dias não usados, aplique cupom no plano novo. Se upgrade no meio do ciclo é parte central do seu pricing, Stripe Billing e iugu documentam pró-rata, e vale comparar antes de decidir.
Dá para oferecer período de teste grátis (trial)?
Não como recurso nativo da v1. O padrão que funciona é controlar o trial dentro do seu SaaS: o usuário cria a conta, usa por 7 ou 14 dias e, perto do fim, o app mostra o botão "Assinar" com o link do plano e o src da conta. O primeiro pagamento confirmado dispara subscription_activate e o acesso segue sem interrupção. Você perde a captura do cartão no início do trial, mas também evita a cobrança surpresa, que gera chargeback.
Como ligar o pagamento à conta certa do meu SaaS?
Use o parâmetro src. O HeroPay captura o src da URL do link de pagamento e devolve em cart.src em todos os webhooks daquele comprador. Crie um link por plano e anexe ?src=<id-da-conta> quando renderizar o botão para cada tenant. Assim o subscription_activate diz qual conta ativar, mesmo quando quem paga é o financeiro e não o usuário admin. O src aceita letras, números e . _ - ~, até 255 caracteres; não coloque dado pessoal nele.
Quanto custa usar o HeroPay como billing do meu SaaS?
Não há mensalidade, ativação, mínimo nem taxa por usar recorrência. Cada ciclo paga a tarifa da transação aprovada: Pix Automático R$ 0, boleto R$ 0 e cartão 3,49%. Num plano de R$ 297 no cartão, são R$ 10,37 por cobrança; no Pix ou no boleto, R$ 0. Cobranças recusadas não pagam tarifa, então a retentativa não custa nada nas tentativas que falham. Tabela completa em /precos.
Preciso de homologação para ir para produção?
Não. O sandbox é gratuito, roda o mesmo contrato da produção e não tem fila de homologação. Você cria os planos, paga pelo checkout de teste, recebe os webhooks no seu endpoint (com um túnel como ngrok ou cloudflared, se estiver local) e, quando estiver pronto, troca a URL base e o token para produção. Não há reunião comercial no caminho. O passo a passo técnico está em /desenvolvedores.
Consigo calcular MRR e churn pela API?
Sim, com os dados brutos. GET /sales/recurring lista as assinaturas com status, periodicidade e cada tentativa de cobrança, até 1.000 itens por chamada. Os relatórios /reports/purchase/subscriptions/* devolvem receita bruta, líquida e após taxas, contagem por status e vendas mensais, e /reports/purchase/refused/reasons_count agrupa os motivos de recusa. O MRR não vem pronto como métrica: some as assinaturas ativas normalizando pela periodicidade (anual dividido por 12, semestral por 6, trimestral por 3).
Comece agora
Crie o plano no sandbox, assine pelo checkout de teste com ?src= da sua conta de teste e veja subscription_activate chegar no seu endpoint.