> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Recuperação inteligente de receita
> Retentativas automáticas, avisos ao assinante e métricas para reverter falhas de cobrança.
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
Uma agenda de novas tentativas concentrada nos primeiros dias após a falha,
dentro de uma janela que você controla.
E-mails automáticos com o motivo da recusa e um link para trocar o cartão —
que já recobra a fatura na hora.
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.
```json theme={"theme":"css-variables"}
{
"id": "inv_qySUtMa9wu3chFKs",
"object": "invoice",
"attempt_count": 3,
"next_payment_attempt": "2026-08-06T12:00:00+00:00",
"status": "open",
"...": "..."
}
```
## Avisos ao assinante
Dois e-mails cuidam da metade da recuperação que depende do cliente:
| E-mail | Quando é enviado | O que contém |
| ---------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Falha de pagamento | A cada tentativa de cobrança que falhou | Valor, motivo da recusa em linguagem simples, data da próxima tentativa e o link para atualizar a forma de pagamento |
| Cartão perto de vencer | Cerca de um mês antes de o cartão padrão expirar | Identificação do cartão e o link para substituí-lo antes da próxima renovação |
O link leva ao [portal do cliente](/payments/customer-portal) 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](/payments/smart-retries).
## Configuração
Tudo fica em **Configurações → Recuperação** no painel:
| Escolha | Opções |
| ---------------------- | ------------------------------------------------------------------------ |
| Agenda de retentativas | Automática (recomendada) ou personalizada com até 3 passos |
| Janela e quantidade | 1 semana a 2 meses, com até 8 retentativas |
| Ação ao esgotar | Marcar como não paga · manter em atraso · cancelar a assinatura |
| E-mails ao assinante | Falha de pagamento e cartão perto de vencer, cada um com seu interruptor |
| Destino do link | Portal do cliente ou página hospedada da fatura |
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](/payments/smart-retries).
## 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](/api-reference/charges/failure-codes) 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`.
```json theme={"theme":"css-variables"}
{
"id": "evt_4wSx6GbZVLxGc7AQ",
"object": "event",
"data": {
"object": {
"id": "inv_BWeQG1spgYJXQjgq",
"object": "invoice",
"attempt_count": 1,
"next_payment_attempt": "2026-08-04T12:00:00+00:00",
"status": "open",
"...": "..."
}
},
"type": "invoice.payment.failed",
"...": "..."
}
```
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
Como a agenda é calculada, o que conta como tentativa e o que acontece
quando a janela termina.
Os indicadores do painel, como cada número é definido e como usá-los para
calibrar a política.