> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Recusas de cartão
> Entenda por que uma transação de cartão é recusada, o que o campo refusedReason retorna e como orientar o seu cliente
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](/api-reference/payments/get).
```json GET /v1/payments/{id} theme={null}
{
"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.
## Próximos passos
Veja o status e o refusedReason de uma transação pelo ID
Referência completa do endpoint de criação de pagamentos