Recusas de cartão

Uma parte relevante das transações de cartão de crédito é recusada durante a autorização — e, na grande maioria dos casos, a decisão é do banco emissor do cartão, não da UvviPay. Este guia explica os tipos de recusa, como identificá-los pela API e o que orientar ao seu cliente em cada situação.

A autorização de uma transação de cartão é sempre uma decisão do banco emissor (o banco do portador do cartão). Quando o emissor recusa, nem a UvviPay nem o lojista têm influência sobre essa decisão — a orientação correta é sempre que o portador entre em contato com o banco dele.

Quem pode recusar uma transação

Origem da recusa	O que significa
Banco emissor	O banco do portador não autorizou: saldo ou limite insuficiente, cartão vencido ou bloqueado, política de risco do próprio banco, compra fora do padrão de uso do cliente
Dados do cartão	Número, validade ou código de segurança (CVV) incorretos ou incompletos
Análise antifraude	A transação foi avaliada como de alto risco de fraude e chargeback
Indisponibilidade temporária	O emissor ou a rede de pagamento ficou momentaneamente fora do ar — vale tentar novamente após alguns minutos

Como identificar uma recusa na API

Uma transação recusada retorna status: "refused" acompanhado do objeto refusedReason na consulta do pagamento.

GET /v1/payments/{id}

{
  "id": "d398b016-3c29-41b4-afc0-bbf8c81c683c",
  "status": "refused",
  "amount": 15680,
  "paymentMethod": "credit_card",
  "refusedReason": {
    "category": "issuer_declined",
    "description": "Recusa do banco emissor"
  }
}

Campo	Como usar
`category`	Categoria abstraída do motivo, estável para lógica de negócio (valores na tabela abaixo)
`description`	Rótulo amigável da categoria, pronto para exibição ao comprador ou uso pelo time de atendimento

Categorias de recusa

Estas são as categorias que a UvviPay retorna em refusedReason.category e a orientação recomendada para cada uma:

`category`	`description`	O que significa	Como orientar o cliente
`issuer_declined`	Recusa do banco emissor	O banco do portador não autorizou: saldo/limite insuficiente, transação não permitida, política de risco do próprio banco	Oriente o cliente a contatar a central do cartão e pedir a liberação; depois, tentar novamente
`invalid_card_data`	Dados do cartão inválidos	Número, validade, CVV incorretos, cartão vencido ou não desbloqueado	Oriente o cliente a conferir os dados digitados ou usar outro cartão
`temporary_unavailable`	Indisponibilidade temporária	O emissor ou a rede ficou momentaneamente fora do ar	Oriente o cliente a aguardar alguns minutos e tentar novamente — vale a retentativa
`suspected_fraud`	Suspeita de fraude	A análise antifraude classificou a transação como de alto risco	Oriente o cliente a tentar outro cartão ou outro método de pagamento (ex.: PIX)
`installments_exceeded`	Número de parcelas acima do máximo permitido	O cartão ou o emissor não permite o número de parcelas escolhido	Oriente o cliente a tentar novamente em até 12x ou liberar o parcelamento no banco do cartão

Quando a recusa parte do banco emissor, a UvviPay recebe apenas um código e uma descrição genérica. A relação entre o banco e o portador é sigilosa — por norma do setor (ABECS), o emissor não compartilha o motivo detalhado com o lojista ou com o gateway. Somente o portador, falando diretamente com o banco dele, consegue o motivo exato e a liberação.

O que dizer ao seu cliente

O comprador costuma atribuir a recusa à loja ou ao meio de pagamento, quando na verdade a decisão foi do banco dele. Mensagens que funcionam bem no atendimento:

Recusa do emissor: “Seu banco não autorizou esta compra. Entre em contato com a central do seu cartão (telefone no verso) e peça a liberação; depois é só tentar novamente.”
Dados do cartão: “Confira o número, a validade e o código de segurança do cartão e tente de novo.”
Parcelas acima do máximo: “O número de parcelas escolhido excede o máximo permitido para este cartão. Tente novamente em até 12x ou libere o parcelamento no banco do cartão.”
Alternativa imediata: “Se preferir, você pode concluir a compra com outro cartão ou via PIX.”
Indisponibilidade temporária: “Houve uma instabilidade momentânea na rede do cartão. Aguarde alguns minutos e tente novamente.”

Recusas por indisponibilidade temporária ou por parcelas acima do máximo valem uma nova tentativa (em até 12x ou liberando o parcelamento no banco, no segundo caso). Já recusas do emissor tendem a se repetir até que o portador resolva a pendência com o banco — retentativas imediatas sem essa ação raramente aprovam.

Quem pode recusar uma transação

Como identificar uma recusa na API

Categorias de recusa

O que dizer ao seu cliente

Próximos passos

Consultar pagamento

Criar pagamento

​Quem pode recusar uma transação

​Como identificar uma recusa na API

​Categorias de recusa

​O que dizer ao seu cliente

​Próximos passos

Consultar pagamento

Criar pagamento

Quem pode recusar uma transação

Como identificar uma recusa na API

Categorias de recusa

O que dizer ao seu cliente

Próximos passos