Assinaturas e cobrança recorrente sem churn involuntário

Pagamento recorrente no HeroPay é um link de pagamento com periodicidade: você envia period no POST /payment_links e o link vira uma assinatura mensal, trimestral, semestral ou anual, cobrada no cartão, no boleto ou por Pix Automático, com renovação ilimitada ou por número de ciclos. A cobrança recorrente de cada ciclo, a retentativa de falhas, a troca de cartão pelo próprio assinante e os avisos por evento já vêm prontos; você libera e suspende acesso pelos webhooks e cancela por API. Serve para SaaS, micro-SaaS, clubes, comunidades e mentorias. Não há preço à parte para assinatura: cada cobrança paga a tarifa normal, Pix R$ 0, boleto R$ 0 e cartão 3,49% por transação aprovada (ver preços).

Criar conta sandbox · Ler a documentação

O que é pagamento recorrente e como funciona no HeroPay?

Pagamento recorrente é a cobrança automática de um valor fixo em intervalos definidos, enquanto o contrato estiver ativo: o cliente autoriza uma vez e não precisa pagar manualmente a cada mês. No HeroPay, o fluxo do dinheiro tem cinco passos:

1. Você cria o plano. Um POST /payment_links com price_cents, period e a regra de renovação devolve a URL do checkout da assinatura.
2. O assinante paga o primeiro ciclo no checkout. No cartão, o número é tokenizado no checkout hospedado (você não toca no cartão); no Pix Automático, ele autoriza a recorrência no app do banco; no boleto, recebe o documento do ciclo. O primeiro pagamento confirmado ativa a assinatura e dispara subscription_activate.
3. O HeroPay cobra cada ciclo sozinho. Na data da renovação, o cartão tokenizado é cobrado, o Pix Automático é debitado ou o boleto do ciclo é emitido. Cada pagamento confirmado dispara spark_payment_confirmed e subscription_update, e o valor entra no seu saldo.
4. Se a cobrança falha, a recuperação começa. O HeroPay reprocessa a cobrança automaticamente, avisa você por payment_credit_cart_refused (com o motivo da operadora) e o assinante pode trocar o cartão sem falar com o seu suporte.
5. A assinatura termina por uma de quatro portas: cancelamento por você (API ou painel), pelo assinante, por estorno ou chargeback, ou ao atingir o limite de atrasos configurado. Em qualquer caso chega subscription_cancel e o histórico de cobranças fica preservado.

Cada tentativa de cobrança de uma assinatura fica registrada e aparece na listagem GET /sales/recurring, para você acompanhar a recuperação sem depender de planilha.

Quais ciclos e regras de renovação posso configurar?

Fonte: referência OpenAPI v1 do HeroPay, Criar link de pagamento. Verificado em setembro de 2026.

Exemplos de configuração: plano mensal de SaaS = monthly + unlimited; mentoria de 12 meses = monthly + limited + frequency_limit: 12; anuidade de comunidade = annual + unlimited.

Trocar de plano no meio do ciclo, com pró-rata, não faz parte da API v1: para mudar de plano, cancele a assinatura atual e o cliente assina o plano novo pelo link correspondente. Os detalhes estão em limites.

Na prática, por código

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 Pro mensal",
      "description": "Acesso ao Plano Pro, cobrado todo mês",
      "price_cents": 9700,
      "absorbs_fees": true,
      "period": "monthly",
      "frequency_type": "unlimited",
      "payment_methods": ["credit_card", "pix", "bank_slip"],
      "src": "pricing-page"
    }
  }'

{
  "message": "Payment link created successfully",
  "data": {
    "id": 137,
    "name": "Plano Pro mensal",
    "description": "Acesso ao Plano Pro, cobrado todo mês",
    "price_cents": 9700,
    "absorbs_fees": true,
    "max_installments": 1,
    "period": "monthly",
    "frequency_type": "unlimited",
    "frequency_limit": null,
    "overdue_type": "none",
    "overdue_limit": null,
    "public_id": "fc280e25-7cbd-446f-b34f-5b8824bb5124",
    "offer": {
      "id": 6095,
      "kind": "payment_link",
      "url": "https://pay.beta.herospark.com/fc280e25-7cbd-446f-b34f-5b8824bb5124-6095?src=pricing-page",
      "accepted_payment_methods": ["credit_card", "pix", "bank_slip"]
    },
    "created_at": "2026-09-23T10:07:01.929-03:00",
    "updated_at": "2026-09-23T10:07:01.929-03:00"
  }
}

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": "subscription_cancel",
      "webhook_url": "https://seuapp.com/webhooks/heropay",
      "request_method": "post"
    }
  }'

curl -X POST "$HEROPAY_API_URL/recurring_payment/cancel" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{ "recurring_payment": { "recurring_payment_id": 3020 } }'

{
  "message": "Recurring payment cancelled successfully",
  "data": {
    "id": 3020,
    "status": "cancelled",
    "period": "monthly",
    "payment_method": "credit_card",
    "credit_card_masked_number": "**** **** **** 4644",
    "amount": 30000,
    "total_collected": 30000,
    "next_invoice_at": "2025-09-18",
    "canceled_by": "buyer",
    "subscription_type": "recurrency"
  }
}

curl -G "$HEROPAY_API_URL/sales/recurring" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  --data-urlencode "paymentStatus[]=paid" \
  --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" },
        "coupon": { "couponCode": "RECORRENTE20", "couponValue": 30.0 },
        "periodicity": "monthly",
        "purchases": [
          { "purchaseId": "uuid-456", "unifiedStatus": "paid", "paymentMethod": "credit_card" }
        ]
      }
    ],
    "totalCount": 1
  },
  "message": "Vendas encontradas com sucesso"
}

Por prompt: a assinatura criada com a sua ferramenta de IA

Cole https://heropay.tech/llms.txt na conversa com Claude, ChatGPT, Cursor, Lovable e outros, e o plano sai de uma frase em português:

Com base em https://heropay.tech/llms.txt, escreva o código que cria no
HeroPay um plano "Pro mensal" de R$ 97 com renovação ilimitada, aceitando
cartão, Pix Automático e boleto, com src "pricing-page". Depois cadastra
webhooks de subscription_activate e subscription_cancel apontando para
https://seuapp.com/webhooks/heropay e imprime a URL do checkout.

O código gerado chama POST /payment_links com period: "monthly" e frequency_type: "unlimited", cadastra os dois webhooks e devolve o link, com a sua chave lida do ambiente, nunca colada no chat. Um MCP server oficial está em desenvolvimento; hoje o caminho é llms.txt, docs abertas e API REST. Veja /ai.

O que é churn involuntário e quanto ele custa em reais?

Churn involuntário é o cancelamento que ninguém pediu: o assinante queria continuar, mas o cartão expirou, estourou o limite, foi bloqueado ou o boleto passou do vencimento. Diferente do churn voluntário (o cliente decidiu sair), ele é quase todo recuperável, porque o problema é o meio de pagamento, não o produto.

A conta, com números redondos:

Premissas: sem novas vendas, sem churn voluntário, toda falha não recuperada vira cancelamento no mesmo mês, perda composta mês a mês. A coluna da direita é uma hipótese para mostrar a sensibilidade, não uma taxa de recuperação prometida pelo HeroPay.

Leitura: 5 recusas por mês parecem pouco (R$ 485), mas em um ano elas levam quase metade da base e R$ 27 mil de receita, sem nenhum cliente ter decidido sair. Recuperar metade das falhas devolve R$ 12.486,50 no ano para a mesma base. É por isso que retentativa e troca de cartão pesam mais no MRR do que meio ponto de taxa.

Como o HeroPay reduz o churn involuntário?

Reprocessamento automático da cobrança. Quando a renovação falha, o HeroPay tenta de novo sozinho, sem você escrever job de retentativa. As tentativas que falham não pagam tarifa: a taxa do cartão incide só sobre transação aprovada. As bandeiras limitam quantas vezes o mesmo cartão pode ser retentado (a Vindi documenta, por exemplo, até 15 retentativas em 30 dias na Visa e intervalo mínimo de 24 horas na Mastercard para recorrência), e recusas irreversíveis, como cartão cancelado, não devem ser retentadas. Por isso a retentativa sozinha não basta.

Plano anual sem estourar o limite. Em ticket alto, o problema costuma ser limite, não cartão inválido. Para o plano anual, dá para oferecer também uma venda avulsa parcelada no checkout, onde o Parcelamento Inteligente recupera a recusa por limite com até 3 retentativas por parcela.

Troca de cartão self-service. Para cartão expirado, bloqueado ou substituído, retentar não resolve: é preciso um cartão novo. O assinante troca o cartão sozinho, pela recuperação de vendas do checkout, sem abrir ticket e sem você construir tela de "atualizar forma de pagamento".

Três métodos na mesma assinatura. Quem não quer (ou não pode) deixar cartão assina por Pix Automático, que não expira, não tem limite de cartão e custa R$ 0 por cobrança; ou por boleto, também R$ 0.

Motivo da recusa em mãos. O webhook payment_credit_cart_refused traz o motivo da operadora e o relatório de recusadas agrupa os motivos, para você saber se o problema é limite, cartão vencido ou antifraude.

Como montar uma régua de cobrança com o HeroPay?

Régua de cobrança é a sequência programada de avisos e ações antes e depois do vencimento: lembrar antes, avisar no dia, recuperar depois. No HeroPay, a régua é montada por gatilhos por evento: recusa, vencimento, chargeback e estorno disparam automações de e-mail ou webhook, e você decide o que acontece em cada degrau.

Quem já tem CRM ou ferramenta de e-mail pluga a régua pelos webhooks; quem não tem usa as automações do próprio HeroPay. O guia de cobrança recorrente para SaaS aprofunda o passo a passo.

Casos de uso

Micro-SaaS com plano mensal e anual. Dois links: monthly a R$ 97 e annual a R$ 970. Com 200 assinantes mensais no cartão, cada cobrança paga R$ 3,39 de tarifa (3,49% de R$ 97), R$ 678 por mês no total. Se metade migrar para o Pix Automático, essa metade passa a pagar R$ 0 e a conta cai para R$ 339 por mês, ou R$ 4.068 por ano a mais no seu caixa, com os mesmos clientes.

Mentoria de 12 meses. Um link monthly + limited + frequency_limit: 12 a R$ 497. A assinatura encerra sozinha na 12ª cobrança, sem você lembrar de cancelar ninguém. Pagando por Pix Automático, os R$ 5.964 do contrato entram inteiros, sem tarifa por cobrança; no cartão, a tarifa é de R$ 17,35 por mês.

Clube ou comunidade com base que paga por boleto. Parte do público não tem cartão com limite sobrando. Com boleto a R$ 0 e spark_payment_boleto_created alimentando o WhatsApp do clube, o boleto chega onde o assinante lê, e o lembrete de vencimento reduz o atraso antes de ele virar cancelamento.

Como o HeroPay se compara em recorrência?

Verificado em setembro de 2026. Fontes: Stripe Smart Retries · iugu, alterar assinatura · iugu, cobranças recorrentes · Vindi, plataforma de recorrência · Vindi, Retentativa Simples · Vindi, retentativa com troca de perfil · AbacatePay docs. "Não verificado" = não conferimos na fonte oficial nesta data.

Onde os outros são melhores, sem rodeio: o Stripe Billing e a iugu têm troca de plano com pró-rata documentada, e o Stripe e a AbacatePay têm período de teste e cobrança por uso. Se o seu modelo depende de upgrade no meio do ciclo ou de cobrança por consumo, confira isso antes de migrar. Veja também Stripe vs HeroPay e AbacatePay vs HeroPay.

Limites e regras honestas

• Valor mínimo de R$ 5,00 por ciclo (price_cents a partir de 500).
• Pagamento internacional não vale para link recorrente: enable_international_sales só funciona em link avulso.
• Sem troca de plano pela API na v1: para mudar de plano, cancele e crie uma nova assinatura no plano novo. Pró-rata não existe hoje.
• Sem período de teste (trial) e sem cobrança por uso na v1: o valor é fixo por ciclo.
• Cancelamento é imediato e irreversível. Não existe "cancelar no fim do período" pela API; se quiser manter o acesso até o fim do ciclo pago, controle isso do seu lado com a data do último pagamento.
• Sem header Idempotency-Key: duas chamadas iguais de POST /payment_links criam dois planos. Grave o id antes de repetir.
• Sem troca de cartão pela API: a troca é feita pelo assinante no fluxo self-service, não por endpoint seu.

Comece agora

Crie o primeiro plano no sandbox em 5 minutos, pague com o checkout de teste e veja subscription_activate chegar no seu endpoint.

Criar conta sandbox · Ler a documentação

Continue por aqui: Preços · Pix Automático · Link de pagamento · Checkout · Webhooks · Desenvolvedores · Guia de cobrança recorrente para SaaS · Glossário