Retentativa de cobrança negada

Quando uma cobrança é negada, a YumePay pode tentar de novo automaticamente, em dias definidos, antes de considerá-la perdida.

A retentativa é configurada por lojista e vem desligada. Para ligar, mudar os intervalos ou desligar, em homologação ou produção, solicite ao suporte YumePay. O padrão é 3 retentativas, com 1, 3 e 5 dias de intervalo. Não há rota para alterar a configuração; há uma rota para consultá-la:

GET/api/v1/subscriptions/retry-policy

{
  "status": "success",
  "data": {
    "enabled": true,
    "intervalsDays": [1, 3, 5],
    "maxRetries": 3,
    "irreversibleDenialCodes": ["14", "54", "57", "62", "63", "78", "93"]
  }
}

Campo	Descrição
enabled	Se a retentativa está ligada para o seu lojista
intervalsDays	Dias entre uma tentativa e a seguinte. Com a retentativa desligada, mostra os intervalos que valeriam se fosse ligada
maxRetries	Quantas retentativas, além da primeira tentativa
irreversibleDenialCodes	Códigos de recusa que nunca são retentados

observação

Em homologação, a retentativa está ligada para o lojista 2 ("Loja Homolog Pag"), com [1, 3, 5] e 3 retentativas, e desligada para o lojista 4 ("Loja Homolog B"). Confira sempre pela rota acima.

Enquanto estiver desligada, toda cobrança negada fica com attempts: 1 e nextRetryAt: null — é o comportamento esperado, não um campo reservado.

Como funciona

• Reprocessa a mesma cobrança, com o cartão atual da assinatura e o valor gravado na cobrança. Se o cartão for trocado (Trocar o cartão) antes da data, a retentativa já usa o novo. Se o valor da assinatura for alterado (Atualizar assinatura), a retentativa continua cobrando o valor original.
• Cada intervalo conta a partir do dia da tentativa anterior. Com [1, 3, 5] e vencimento no dia D, as tentativas são em D, D+1, D+4 e D+9 — quatro no total.
• Datas são dias do calendário no horário de Brasília. A tentativa agendada para um dia roda nesse dia, no primeiro processamento a partir de 00h00 de Brasília (Processamento das cobranças).
• Enquanto há retentativa agendada, o nextDueDate da assinatura não avança. Avança quando a cobrança é confirmada ou quando a negação fica definitiva.
• Cada retentativa negada atualiza lastChargeAt e lastChargeStatus da assinatura, sem somar em consecutiveDeniedCharges.
• Cancelar (Cancelar assinatura) ou expirar a assinatura descarta a retentativa agendada.
• Recusas irreversíveis não são retentadas e já viram negação definitiva: 14 (cartão inválido), 54 (cartão vencido), 57 (transação não permitida), 62 (cartão restrito), 63 (violação de segurança), 78 (cartão bloqueado) e 93 (violação, transação não concluída).
• Falha de comunicação com o adquirente (denialCode: "transport_error") é retentada como recusa comum.

Exemplo — vencimento em 09/10, intervalos [1, 3, 5], recusa 05

Data	attempts	Resultado	Webhook	nextRetryAt
09/10	1	Negada	charge.retry_scheduled	2026-10-10
10/10	2	Negada	charge.retry_scheduled	2026-10-13
13/10	3	Negada	charge.retry_scheduled	2026-10-18
18/10	4	Negada	charge.denied	null

Se qualquer tentativa for aprovada, sai charge.confirmed e o ciclo segue normalmente. Depois da negação definitiva, a assinatura avança para o próximo vencimento — ela não é cancelada.

Configuração	O que charge.denied significa
Retentativa desligada	Cobrança negada; a assinatura segue para o próximo ciclo
Retentativa ligada	Cobrança negada em definitivo. Cada negação intermediária chega como charge.retry_scheduled

Régua própria?

Com os campos lastChargeStatus, consecutiveDeniedCharges e os webhooks, você pode manter uma régua do seu lado. Ligar a retentativa da YumePay é opcional e as duas convivem: os eventos dizem exatamente o que aconteceu em cada tentativa.