Códigos de Resposta
Quick Reference
WhatCódigos de resposta da API
WhyEntenda e trate cada resposta da API
A API retorna erros estruturados e payloads de status. Muitos valores são mapeados de códigos de retorno de adquirentes ou redes em um conjunto estável no qual você pode se basear na sua integração.
Busca na página
Use a busca do navegador (Ctrl+F / Cmd+F) nesta página para pesquisar a coluna de Código ou Descrição.
Variação por provedor
Os mapeamentos exatos podem variar por provedor e produto do cartão. Trate strings específicas de adquirentes como diagnósticas; implemente retentativas e mensagens ao cliente com base nos códigos normalizados abaixo.
Referência de códigos de resposta
| Código | Descrição | Ação sugerida | Troubleshooting |
|---|---|---|---|
CARD_DECLINED | Emissor ou rede recusou a transação. | Peça ao cliente para usar outro cartão ou contatar o banco. | Verifique se o cartão tem restrições internacionais ou para compras online |
INVALID_CARD | Número do cartão ou PAN falhou na validação (formato ou checksum). | Recolete os dados do cartão; bloqueie retentativa até a entrada ser corrigida. | Confirme que não há erros de digitação no número do cartão |
EXPIRED_CARD | Cartão está com validade expirada. | Solicite uma validade válida ou um cartão diferente. | Verifique o formato MM/AA na requisição |
INSUFFICIENT_FUNDS | Emissor recusou por saldo ou limite insuficiente. | Sugira outro método de pagamento ou tente novamente depois. | Considere oferecer parcelamento |
INVALID_CVC | Código de segurança incompatível ou ausente quando obrigatório. | Redigite o CVV; para cartões salvos, atualize as credenciais. | Verifique o mapeamento de campos na integração |
3DS_REQUIRED | Autenticação deve ser concluída antes da autorização. | Retome ou inicie o fluxo 3DS; não trate como recusa definitiva. | Confirme que return_url está definido na requisição |
3DS_FAILED | Autenticação 3DS falhou ou foi abandonada. | Retente o 3DS ou ofereça outro cartão ou método. | Verifique se o cartão suporta 3DS2 |
3DS_UNAVAILABLE | ACS ou directory server indisponível. | Retente uma vez; se persistir, use fallback conforme sua política de risco. | Verifique o enrollment 3DS do adquirente |
PROCESSING_ERROR | Erro transiente no adquirente ou plataforma. | Retente com chave de idempotência; escale se recorrente. | Inclua chave de idempotência na retentativa |
TIMEOUT | Timeout do provedor ou rede. | Consulte o status da cobrança antes de repetir a chamada financeira. | Verifique o status antes de retentar |
DUPLICATE_REQUEST | Replay idempotente detectado com corpo conflitante. | Alinhe o payload da requisição com o original ou use uma nova chave de idempotência. | Gere chaves únicas por tentativa |
FRAUD_SUSPECTED | Bloqueado por regras de fraude ou risco. | Encaminhe para revisão manual ou método alternativo; não force retentativas. | Revise o limiar de score antifraude |
CURRENCY_NOT_SUPPORTED | Carteira ou rota não suporta a moeda da cobrança. | Altere a moeda ou a configuração da carteira. | Veja capacidades por provedor |
AMOUNT_INVALID | Valor abaixo do mínimo, acima do máximo, ou precisão decimal incorreta. | CLP e COP são moedas sem decimais — envie inteiros. BRL, MXN, USD, PEN, ARS usam 2 decimais. EUR usa 2 decimais (exibição FX). | Veja regras de decimais por moeda |
amount_below_minimum | Valor abaixo do mínimo do adquirente ou método (código normalizado — mesmo que amount_too_low). | Aumente o valor. Boleto mínimo é R$5,00. | Veja capacidades por provedor |
amount_exceeds_maximum | Valor acima do máximo do método ou adquirente (código normalizado — mesmo que amount_too_high). | Reduza o valor ou divida em múltiplas cobranças. OXXO máximo é MXN $10.000. | Veja capacidades por provedor |
amount_too_low | Código nativo do adquirente para valor abaixo do mínimo (alias de amount_below_minimum). | Aumente o valor para continuar. | Alguns adquirentes retornam este em vez de amount_below_minimum |
amount_too_high | Código nativo do adquirente para valor acima do máximo (alias de amount_exceeds_maximum). | Tente um valor menor. | Alguns adquirentes retornam este em vez de amount_exceeds_maximum |
MERCHANT_NOT_ALLOWED | MCC, região ou configuração do comerciante bloqueia a venda. | Contate o suporte para ajustar roteamento ou habilitações. | Verifique as configurações do perfil do comerciante |
ACQUIRER_ERROR | Adquirente downstream retornou um erro não mapeado. | Tente novamente depois; inclua o ID de correlação em tickets de suporte. | Contate o suporte com o ID da cobrança |
Mapa rápido por categoria
Sem dados sensíveis
Nunca registre números completos de cartão ou dados sensíveis de autenticação ao capturar respostas de erro para suporte.
| Cenário | Códigos típicos |
|---|---|
| Cartão recusado (genérico) | CARD_DECLINED, INSUFFICIENT_FUNDS, FRAUD_SUSPECTED |
| Problemas nos dados do cartão | INVALID_CARD, EXPIRED_CARD, INVALID_CVC |
| 3DS | 3DS_REQUIRED, 3DS_FAILED, 3DS_UNAVAILABLE |
| Infraestrutura | PROCESSING_ERROR, TIMEOUT, ACQUIRER_ERROR, DUPLICATE_REQUEST |
| Valor / moeda | AMOUNT_INVALID, amount_below_minimum, amount_exceeds_maximum, amount_too_low, amount_too_high, CURRENCY_NOT_SUPPORTED |
| Configuração | MERCHANT_NOT_ALLOWED |