Recusas de Pagamento (Erros de Cartão)

Quando uma cobrança no cartão é recusada pelo emissor/adquirente (ex.: fundos insuficientes, cartão vencido, senha incorreta), a API retorna HTTP 402 com um envelope de erro específico de pagamento. D

Visão Geral

Quando uma cobrança no cartão é recusada pelo emissor/adquirente (ex.: fundos insuficientes, cartão vencido, senha incorreta), a API retorna HTTP 402 com um envelope de erro específico de pagamento. Diferente dos erros genéricos (ver Tratamento de Erros), o envelope de recusa carrega o motivo da recusa (code), uma mensagem pronta para o comprador (displayMessage, em pt-BR) e um flag de retentabilidade (reversible).

Recusas acontecem nas operações que cobram cartão: criação e captura de Transações e cobranças de Assinaturas.

Envelope de Recusa (HTTP 402)

{
  "error": {
    "status": "Request Failed",
    "statusCode": 402,
    "category": "payment",
    "code": "insufficientFundsError",
    "type": "cardError",
    "message": "The request was valid, but the payment process failed.",
    "details": "Please verify your payment information and try again.",
    "params": [
      { "payment": "Saldo insuficiente para realizar esta compra. Verifique seu limite disponível." }
    ],
    "displayMessage": "Saldo insuficiente para realizar esta compra. Verifique seu limite disponível.",
    "reversible": false
  }
}

Campos

Campo	Tipo	Descrição
`error.code`	string	Motivo da recusa, estável e legível por máquina — use-o na sua lógica (ex.: `insufficientFundsError`).
`error.category`	string	Sempre `payment` para recusas de cartão.
`error.type`	string	Classe do erro: `cardError`, `invalidRequestError` ou `processingError`.
`error.message` / `error.details`	string	Texto técnico (inglês) — não mostre ao comprador.
`error.displayMessage`	string	Mensagem em pt-BR pronta para exibir ao portador do cartão.
`error.params`	array	Detalhe da recusa por campo (ex.: `payment` → mensagem).
`error.reversible`	boolean	Se o adquirente indica que a cobrança pode ser retentada (ver abaixo).
`error.status` / `error.statusCode`	string / integer	`"Request Failed"` / `402`.

Regra de ouro: trate a recusa pelo error.code e mostre o error.displayMessage ao comprador. Nunca exiba message/details (são técnicos, em inglês).

Catálogo de Códigos de Recusa (type: "cardError")

`code`	`displayMessage` (pt-BR)	Causa típica
`insufficientFundsError`	Saldo insuficiente para realizar esta compra. Verifique seu limite disponível.	Limite/saldo insuficiente
`cardDeclined`	Seu cartão foi recusado pelo banco. Entre em contato com sua instituição financeira para mais detalhes.	Recusa genérica do emissor
`expiredCardError`	Seu cartão está vencido. Use um cartão válido ou atualize a data de validade.	Cartão vencido
`invalidCardNumber`	Número do cartão inválido. Verifique os dados digitados e tente novamente.	Número de cartão inválido
`invalidExpiryMonth`	O mês de validade do cartão está incorreto. Verifique os dados e tente novamente.	Mês de validade inválido
`invalidExpiryYear`	O ano de validade do cartão está incorreto. Verifique os dados e tente novamente.	Ano de validade inválido
`invalidPinCode`	A senha do cartão está incorreta. Verifique a senha e tente novamente.	Senha (PIN) incorreta
`authorizationRefused`	Transação não autorizada. Entre em contato com seu banco ou tente outro cartão.	Autorização recusada pelo emissor
`cardCustomerNotAssociated`	Nenhum cartão ativo encontrado. Adicione um cartão válido para continuar.	Sem cartão ativo associado

Quando o motivo não é reconhecido, o padrão é code: "cardDeclined" com displayMessage: "Contate a administradora do cartão e tente pagar novamente."

Retentabilidade (reversible)

O flag error.reversible reflete o que o adquirente informa e determina o que acontece com a transação:

`reversible`	Status da transação	Comportamento
`false`	`failed` (terminal)	Recusa definitiva. Para cobrar de novo, inicie uma nova transação (idealmente com outro cartão/forma de pagamento).
`true`	`awaiting`	Falha potencialmente transitória — a transação é mantida e o sistema reprocessa automaticamente em segundo plano. Acompanhe o resultado pelos webhooks.

Como a recusa também aparece de forma assíncrona

Além da resposta 402, o resultado da cobrança se reflete na transação e nos webhooks:

Status da transação: failed (recusa terminal) ou awaiting (recusa reversível, em reprocessamento).
Webhook: uma recusa terminal dispara o evento transaction.failed (ver Catálogo de Eventos).
Detalhe do adquirente na transação: os dados da tentativa ficam disponíveis no objeto da transação, incluindo acquirer.responseCode (código do emissor) e acquirer.buyerMessage (a mesma mensagem do displayMessage).

Boas Práticas

Keye no error.code, não no texto — message/displayMessage podem mudar.
Mostre error.displayMessage ao comprador; ele já vem localizado e seguro para exibição.
Não retente recusas reversible: false automaticamente no mesmo cartão — peça outro meio de pagamento. Para reversible: true, deixe o reprocessamento em segundo plano agir e escute os webhooks.
Trate insufficientFundsError, expiredCardError e invalidCardNumber com mensagens de orientação ao comprador (corrigir dados, usar outro cartão).
Teste os cenários com os Cartões de Teste (ex.: o cartão de failed) antes de ir para produção.

Notas

Outros códigos com type: "invalidRequestError" (também 402) indicam problemas de operação/conta do vendedor, não do cartão do comprador: insufficientEscrowFundsError (saldo do vendedor para transferência), captureTransactionError, voidTransactionError, noActionTaken, sellerAuthorizationRefused (vendedor ainda não habilitado a cobrar).
Erros de geração de boleto por dados inválidos retornam 422 com type: "processingError" e code: "serverApiError".

Recusas de Pagamento (Erros de Cartão)

On this page