declined na resposta síncrona e dispara um webhook payment.refused. Ambos trazem um objeto refusalCode que diz por que o pagamento falhou e o que fazer em seguida.
O objeto refusalCode
Somente
reasonCode e recoveryAction são seguros para construir lógica. originalReasonCode / originalReason são diagnósticos de repasse e seu formato não é estável entre provedores.recoveryAction
O Therius classifica cada recusa em uma de quatro ações de recuperação para que o seu checkout possa responder sem codificar manualmente uma decisão para os mais de 60 códigos.
retry
A recusa pode se resolver em uma segunda tentativa — uma mensagem malformada ou fora de hora, uma falha do sistema, ou uma resposta genérica do emissor (incluindo “Do not honor”). Refazer o mesmo cartão uma vez é razoável. Sempre limite as novas tentativas a um número fixo pequeno — não faça loops.
switch_method
Refazer este cartão não vai ajudar (fundos insuficientes, cartão expirado, cartão restrito), mas um método de pagamento diferente pode ter sucesso. Peça ao cliente para tentar outro cartão ou um método alternativo.
terminal
Um bloqueio definitivo — cartão a reter/perdido/roubado, conta encerrada, suspeita de fraude, ou uma ordem de revogação. Não ofereça uma nova tentativa nem um método alternativo. Mostre uma mensagem de falha neutra e pare.
update_data
Tentar de novo sem mudanças vai falhar até que um dado informado pelo comprador seja corrigido, como CPF/CNPJ, chave Pix, conta bancária ou nome. Peça ao comprador para corrigir o dado e envie novamente. Usado pelos métodos de pagamento alternativos.
reasonCode não reconhecido ou ausente é reportado como switch_method — o padrão seguro, já que refazer cegamente uma recusa não classificada arrisca penalidades por tentativas excessivas das bandeiras de cartão.
Reroteamento automático
A maioria das recusas temporárias é refeita pelo Therius antes de você as ver — o roteamento inteligente leva o pagamento em cascata para a próxima conexão da rota. Portanto, a recusa que você recebe na resposta é o resultado depois de o Therius já ter esgotado as alternativas daquela rota. As recusas definitivas (terminal acima, além de algumas outras como PIN incorreto e falhas de CVV) são retornadas imediatamente e nunca são rerroteadas, porque refazê-las em outro adquirente só acrescentaria violações da bandeira.
Assinaturas e gestão de cobranças
Para as renovações de assinatura, o Therius aplica a mesma classificação internamente: uma recusaterminal para a sequência de gestão de cobranças imediatamente (a assinatura vai para suspended e dispara subscription.suspended), em vez de desperdiçar as novas tentativas restantes em um cartão que o emissor nunca vai aprovar.
Referência de códigos de recusa
Os valores dereasonCode normalizados que o Therius pode retornar, com seu significado e sua recoveryAction padrão.
}
Códigos de métodos de pagamento alternativos
As recusas de métodos de pagamento alternativos trazem umreasonCode APM_*. O prefixo é reservado: um valor APM_* nunca é um código de cartão. Uma recusa de método alternativo que o Therius não consegue classificar é reportada como APM_DECLINED, e uma falha técnica como APM_TECHNICAL_ERROR. O código próprio do provedor continua disponível em originalReasonCode.
Pagamentos expirados e cancelados
Quando um pagamento de método alternativo termina comoexpired ou canceled porque o pagador não pagou ou desistiu, o pagamento traz APM_EXPIRED ou APM_PAYER_CANCELED, e GET /payment/inquiry devolve um refusalCode com recoveryAction: retry. Um cancelamento que você solicita pela API não traz motivo.