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 no POST, no GET e no webhook transaction.refused (o mesmo objeto vai em transaction.status.updated). A resposta não devolve código nem texto da adquirente.

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

Webhook de recusa

No cartão recusado, transaction.refused e transaction.status.updated carregam o mesmo refusedReason da API: só category e description. O campo não aparece em pagamento aprovado, nem em PIX ou boleto. Saldo ou limite insuficiente sai como insufficient_funds. Transação não permitida para o cartão, inclusive compra internacional bloqueada pelo próprio cartão, sai como transaction_not_allowed. CVV, número ou validade incorretos saem como invalid_card_data.

transaction.refused

{
  "id": "64e2e7b3-aff7-4739-bdf1-274de071b224",
  "pix": null,
  "card": {
    "brand": "VISA",
    "first_six": "411111",
    "last_four": "1111"
  },
  "event": "transaction.refused",
  "items": [
    {
      "title": "Item",
      "quantity": 1,
      "tangible": null,
      "unitPrice": 1000
    }
  ],
  "amount": 1000,
  "status": "refused",
  "channel": "online",
  "customer": {
    "name": "Cliente Teste",
    "email": "cliente@example.com",
    "address": null
  },
  "terminal": null,
  "createdAt": "2026-10-19T14:21:05.065Z",
  "installments": 1,
  "paymentMethod": "credit_card",
  "refusedReason": {
    "category": "insufficient_funds",
    "description": "Saldo ou limite insuficiente"
  },
  "externalReference": "pedido-1000"
}

Para dados inválidos ou CVV, o mesmo payload traz:

"refusedReason": {
  "category": "invalid_card_data",
  "description": "Dados do cartão inválidos"
}

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 a compra por política do próprio banco	Oriente o cliente a contatar a central do cartão e pedir a liberação; depois, tentar novamente
`insufficient_funds`	Saldo ou limite insuficiente	O banco do portador recusou a compra por falta de saldo ou de limite	Oriente o cliente a liberar limite, usar outro cartão ou tentar novamente
`transaction_not_allowed`	Transação não permitida para o cartão	O banco do portador não permite esta transação para o cartão, inclusive compra internacional bloqueada pelo cartão	Oriente o cliente a usar outro cartão ou falar com a central do cartão
`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.”
Saldo ou limite insuficiente: “Seu banco recusou a compra por falta de saldo ou limite. Libere limite ou tente com outro cartão.”
Transação não permitida para o cartão: “Seu banco não permite esta compra neste cartão. Use outro cartão ou fale com a central do cartão.”
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.

Começando

Funcionalidades

Quem pode recusar uma transação

Como identificar uma recusa na API

Webhook de recusa

Categorias de recusa

O que dizer ao seu cliente

Próximos passos

Consultar pagamento

Criar pagamento

Começando

Funcionalidades

​Quem pode recusar uma transação

​Como identificar uma recusa na API

​Webhook de recusa

​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

Webhook de recusa

Categorias de recusa

O que dizer ao seu cliente

Próximos passos