Retentativa e códigos de recusa

Retentar uma cobranca recusada parece simples e e onde a maioria das integracoes perde dinheiro. Este documento explica a regra que usamos e por que ela e assim.

O problema

Quando o emissor recusa uma cobranca, ele diz por que. Esse motivo muda completamente o que vale fazer em seguida:

• "saldo insuficiente" pode mudar amanha, quando o salario cair;
• "cartao perdido" nao vai mudar nunca.

Retentar as duas do mesmo jeito custa dinheiro na segunda. O Normativo nº 021 da ABECS formaliza essa distincao e alerta diretamente sobre o custo:

O EC deve se atentar a possibilidade de cobranca de penalidade pela retentativa. Desta forma, e recomendado verificar a razao da negativa antes de submeter novo pedido de autorizacao.

As duas classes de recusa

O Art. 5º do normativo define duas categorias:

Reversivel

O emissor nao pode aprovar neste momento. Falta de limite, indisponibilidade de sistema, suspeita de fraude, excesso de tentativas de senha. Sao decisoes temporarias que podem mudar com o tempo.

Tratamento previsto: a proxima transacao pode ter os mesmos campos, mas deve ocorrer em tempo ou data diferente.

Irreversivel

O emissor nunca aprovara. Cartao cancelado, perdido, roubado, fraude confirmada, transacao nao permitida para o produto.

Nas palavras do normativo: "qualquer tentativa de autorizacao que antes tenha recebido uma recusa Irreversivel sem alteracao de algum campo da mensageria nao obtera sucesso".

Tratamento previsto: so faz sentido tentar de novo alterando algum campo, o que resulta em uma transacao distinta. Sem alteracao possivel, o caminho e pedir outro meio de pagamento ao cliente.

Recusa do antifraude da Cielo. ANTIFRAUD_REJECT nao vem do emissor e nao esta na tabela ABECS: e o codigo do Minstrel para a venda que a analise de fraude embutida na autorizacao recusou. Entra na classe irreversivel (SUSPECTED_FRAUD, DO_NOT_RETRY) e nao ha configuracao que mude isso: tentar de novo, ou em outra conta, seria contornar a analise. Veja Transacoes.

Como aparece na resposta

Toda recusa vem classificada:

{
  "object": "payment",
  "status": "failed",
  "decline": {
    "reason": "INSUFFICIENT_FUNDS",
    "reversibility": "REVERSIBLE",
    "retryAction": "RETRY_LATER"
  },
  "attempts": [
    {
      "attemptNumber": 1,
      "connector": "cielo",
      "rawResponseCode": "51",
      "declineReason": "INSUFFICIENT_FUNDS",
      "reversibility": "REVERSIBLE",
      "retryAction": "RETRY_LATER"
    }
  ]
}

O rawResponseCode e o codigo bruto do emissor - use-o para falar com o adquirente. O declineReason e a classificacao canonica, igual para todas as bandeiras - use-o para decidir o que fazer e para agrupar relatorios.

Acoes possiveis

Suspensao de recorrencia: o caso que exige atencao

Os codigos R0, R1 e R3 da Visa, e o Merchant Advice Code 21 da Mastercard, significam que o portador revogou a autorizacao da cobranca recorrente junto ao emissor.

Isso nao e uma recusa comum: e uma determinacao. Insistir gera chargeback e penalidade de bandeira.

Quando recebemos um desses codigos, o Minstrel cancela a assinatura automaticamente, marca canceledByIssuer: true e emite o evento subscription.canceled_by_issuer. Nao existe configuracao que sobreponha esse comportamento.

Quando o emissor diz quando retentar

A Mastercard envia, junto da recusa, o Merchant Advice Code (DE48 SE84), registrado no Anexo II do normativo. Alguns valores informam o intervalo exato:

Quando o MAC esta presente, ele tem precedencia sobre o intervalo da sua politica - mas apenas para aumenta-lo. Se a sua politica pede 24 horas e o emissor pede 4 dias, esperamos 4 dias. O contrario nao acontece.

Politicas de retentativa

A politica padrao faz 1 cobranca mais 3 retentativas em 7 dias:

{
  "name": "padrao-7-dias",
  "maxAttempts": 4,
  "schedule": [
    { "attempt": 2, "delayHours": 24 },
    { "attempt": 3, "delayHours": 72 },
    { "attempt": 4, "delayHours": 96 }
  ],
  "windowDays": 10,
  "respectIssuerAdvice": true,
  "stopOnIrreversible": true,
  "preferredHourLocal": 10,
  "timezone": "America/Sao_Paulo"
}

Os intervalos caem em datas distintas de credito do portador (D+1, D+3, D+7), equilibrando conversao e custo.

Dois campos merecem explicacao:

respectIssuerAdvice mantem a precedencia do Merchant Advice Code. Desligar aumenta o risco de penalidade - nao recomendamos.

stopOnIrreversible encerra em recusa irreversivel. Hoje o motor trata o campo como sempre ligado: recusa irreversivel nunca e retentada, e nenhuma politica, cadastrada ou escolhida num no de fluxo, muda isso. Retentar o que o emissor ja informou que nao aprovara e pagar por tentativa perdida.

Qual politica vale: a do no ou a da assinatura

A fatura recusada e reagendada pela politica que o no Retentativa do fluxo escolheu. Quando o fluxo que processou a cobranca nao passou por um no Retentativa, ou o no esta em "Politica da assinatura", vale a politica do plano ou da assinatura (e, sem nenhuma, a padrao). A ordem, da primeira que existir:

1. a politica cadastrada informada no no (retryPolicyId), buscada na sua organizacao - um id que nao existe nela e ignorado;
2. o preset do no (policyPreset);
3. a politica da assinatura (a do plano, quando a assinatura nao tem uma);
4. a politica padrao (padrao-7-dias).

A politica escolhida define o numero de tentativas, os intervalos e a janela. Ela nao afrouxa o que vem de fora:

• recusa irreversivel continua sem retentativa, e R0, R1, R3 (Visa) e o MAC 21 (Mastercard) continuam cancelando a assinatura;
• o intervalo minimo e o teto de tentativas do adquirente (ex.: Cielo, "4 vezes em 16 dias") valem sobre qualquer politica: o menor teto prevalece e o maior intervalo prevalece.

A decisao fica gravada com a tentativa (retry_attempts), e os eventos invoice.payment_failed, retry.scheduled e retry.exhausted trazem policy: { name, source }, com source igual a flow_node, subscription ou default, para responder de onde veio o intervalo.

A tabela completa

A tabela do Anexo I cobre 50 situacoes, com os codigos de Elo, Visa, Mastercard, Hiper e American Express, e a reversibilidade declarada por cada bandeira. Ela esta em Codigos de recusa.

Vale notar uma divergencia que a tabela registra: o codigo 57 e irreversivel na Visa e na Elo, mas reversivel na Mastercard. Por isso a classificacao considera a bandeira, e nao apenas o codigo.