Skip to main content
Uma parcela das renovações de assinatura falha — cartão sem saldo no dia, limite estourado, cartão trocado. Quase nada disso é um cliente decidindo sair: é uma cobrança que chegou na hora errada. A recuperação de receita existe para tratar essa diferença. Em vez de encerrar a assinatura na primeira recusa, a Chargefy abre uma janela de recuperação: reagenda a cobrança nos dias certos, avisa o assinante com um link para resolver sozinho e mede, em reais, quanto voltou.
Falha de cobrança não encerra a assinatura — abre uma recuperação.Quando a renovação é recusada, a assinatura vai para past_due e a fatura continua aberta. A partir daí três frentes trabalham juntas: as retentativas automáticas, os e-mails ao assinante e o seu próprio time, com as métricas para acompanhar tudo.

​
As três frentes

Retentativas inteligentes

Uma agenda de novas tentativas concentrada nos primeiros dias após a falha, dentro de uma janela que você controla.

Avisos ao assinante

E-mails automáticos com o motivo da recusa e um link para trocar o cartão — que já recobra a fatura na hora.

Métricas de recuperação

Quanto falhou, quanto voltou, por qual caminho e por qual motivo — tudo em reais.

​
Como uma recuperação acontece

Com a política padrão — até 8 retentativas em 2 semanas — uma renovação recusada percorre este caminho:
  1. A renovação falha. A assinatura vai para past_due, a fatura segue open e a Chargefy registra o motivo da recusa. O assinante recebe o primeiro e-mail, com um link para atualizar a forma de pagamento.
  2. A agenda entra em ação. As retentativas acontecem em D+1, D+2, D+4, D+5, D+7, D+9, D+12 e D+14, contadas a partir da primeira falha. Cada nova falha gera um novo aviso ao assinante; a primeira cobrança que aprovar encerra a recuperação e reativa a assinatura.
  3. O assinante pode resolver antes. A qualquer momento ele troca o cartão pelo link do e-mail — a fatura é recobrada imediatamente, sem esperar a próxima tentativa da agenda.
  4. A janela termina. Se nada aprovou, vale a ação final que você escolheu: marcar a assinatura como não paga, mantê-la em atraso ou cancelá-la.
A fatura publica o estado da recuperação o tempo todo: attempt_count conta as tentativas e next_payment_attempt diz quando será a próxima.

​
Avisos ao assinante

Dois e-mails cuidam da metade da recuperação que depende do cliente: O link leva ao portal do cliente ou à página hospedada da fatura — você escolhe o destino na configuração. Ao salvar o cartão novo, a fatura em aberto é recobrada na hora, sem intervenção do seu time. O link enviado vale até o fim da janela de recuperação, então um e-mail lido dias depois continua funcionando. Alguns cuidados que a Chargefy aplica sozinha:
  • O e-mail só é enviado quando uma cobrança de fato aconteceu — tentativas puladas (por exemplo, à espera de um cartão novo) não geram aviso.
  • Assinaturas canceladas ou marcadas como não pagas não recebem link de atualização; assinaturas cobradas por fatura manual não entram nesta régua de avisos, que pertence à cobrança automática.
  • Todo envio fica registrado no histórico de notificações da organização.

​
Seu time continua no controle

A recuperação automática não tranca a cobrança manual — os dois caminhos convivem:
  • POST /v1/invoices/{id}/pay recobra a fatura aberta com o cartão que você indicar, pela API ou pelo botão no painel.
  • A página hospedada da fatura aceita pagamento a qualquer momento.
  • O assinante pode trocar o cartão pelo portal do cliente por conta própria.
Cobranças manuais não consomem as tentativas automáticas: a agenda continua de onde estava, e a primeira aprovação — de qualquer origem — encerra a recuperação. Vale também o inverso — uma cobrança manual que falha não mexe na agenda: não adianta tentativas, não estica a janela e não religa uma recuperação já encerrada. A única recusa da cobrança manual é proteção do próprio cartão: depois de uma recusa definitiva (“não repita com o mesmo cartão”), recobrar com o mesmo cartão é bloqueado, e o erro devolve o motivo original da recusa — na API, com o mesmo code do catálogo de recusas; no painel, com a explicação e a saída (trocar o cartão). Um método diferente segue normalmente. Os detalhes estão em Retentativas inteligentes.

​
Configuração

Tudo fica em Configurações → Recuperação no painel: A tela mostra a lista de datas resultante antes de salvar, para a agenda nunca ser abstrata. Mudanças valem para recuperações futuras: as que já estão em andamento seguem a política com que começaram. Os detalhes de cada opção — e o que exatamente conta como tentativa — estão em Retentativas inteligentes.

​
O que a sua integração observa

A recuperação inteira é observável pela API e pelos webhooks, sem endpoint novo:
  • O objeto invoice carrega attempt_count e next_payment_attempt.
  • O evento invoice.payment.failed chega a cada falha de cobrança da fatura, com o objeto completo — incluindo a data da próxima tentativa quando houver.
  • Cada tentativa individual é uma cobrança: charge.failed traz o motivo normalizado da recusa e charge.succeeded fecha a conta.
  • O Payment Intent da fatura é o mesmo do início ao fim — as retentativas reutilizam o objeto em vez de criar um novo, então o campo payment_intent da fatura é um identificador estável para conciliação.
  • A transição da assinatura (past_due, unpaid, active de volta) chega em subscription.updated com previous_attributes.
Em contas com o Chargefy for Platforms, os eventos de recuperação das organizações filhas chegam também aos webhooks da plataforma, com o envelope indicando a organização de origem. A política de recuperação é sempre a da organização filha dona da assinatura.

​
Para continuar

Retentativas inteligentes

Como a agenda é calculada, o que conta como tentativa e o que acontece quando a janela termina.

Métricas de recuperação

Os indicadores do painel, como cada número é definido e como usá-los para calibrar a política.