Códigos de falha

Quando uma cobrança não é aprovada, a charge chega ao estado failed e carrega o motivo da recusa num único objeto: payment_error. Em vez de devolver o código numérico bruto da rede de pagamentos, normalizamos a resposta — baseada no padrão internacional de mensageria financeira ISO 8583 — em um conjunto estável de códigos em texto. Você integra contra esses códigos, não contra a numeração de uma bandeira ou rede específica.

Você nunca lida com códigos numéricosCódigos como os definidos pela ISO 8583 variam por rede e podem mudar. O contrato público expõe sempre o mesmo payment_error.code legível (insufficient_funds, expired_card, …), independente de qual instituição recusou. Assim sua integração não quebra se a origem do processamento mudar.

Como a recusa chega até você

A recusa vem sempre agrupada num único objeto, com três campos:

Campo	Tipo	Descrição
`payment_error.category`	`string \| null`	Categoria coarse da recusa — agrupa os códigos em quatro baldes acionáveis (veja abaixo).
`payment_error.code`	`string \| null`	Código estável e legível do motivo da recusa (`insufficient_funds`, `expired_card`, …).
`payment_error.message`	`string \| null`	Mensagem em inglês, voltada a logs e desenvolvedores.

O objeto inteiro é null em cobranças aprovadas. Quando preenchido, os três campos vêm juntos.

payment_error.message é texto para dev/log em inglês. A mensagem amigável que o comprador vê no checkout hospedado é localizada em português e derivada do mesmo payment_error.code — veja a coluna “Mensagem ao cliente” abaixo.

Testar códigos no sandbox

Todos os payment_error.code desta página têm um cartão de sandbox correspondente. Use a tabela completa em Sandbox para escolher o cartão e ver o resultado esperado (payment_error.category, payment_error.code e payment_error.message).

Categorias (`category`)

category agrupa os motivos em quatro baldes, úteis para decidir o tratamento sem precisar ramificar por cada code:

`category`	Significado	O que costuma resolver
`issuer_declined`	O banco emissor recusou (saldo, validade, bloqueio, limite).	Outro cartão, ou o cliente contata o banco.
`invalid`	Dados do cartão incorretos (ex.: CVV).	Revisar e reenviar os dados.
`blocked`	Recusa por restrição/suspeita de fraude.	O cliente precisa falar com a central do cartão.
`processing_error`	Falha técnica ou de conectividade na rede.	Repetir a tentativa em instantes.

Códigos da operadora (`code`)

Cada motivo de falha vira um payment_error.code estável e granular. Abaixo, os códigos agrupados por category. A coluna Significado explica o que aconteceu na tentativa de cobrança; a Mensagem ao cliente é o texto exibido ao comprador no checkout hospedado.

`issuer_declined` — o banco emissor recusou

`code`	Significado	Mensagem ao cliente
`insufficient_funds`	Saldo ou margem insuficiente para concluir a compra.	”Tente usar outro cartão ou verifique o seu saldo/limite disponível.”
`do_not_honor`	Recusa do emissor sem motivo específico (a mais comum).	”Transação não autorizada pelo banco. Tente outro cartão ou entre em contato com o emissor.”
`generic_decline`	Recusa genérica, em geral por divergência nos dados.	”Confirme os dados do cartão ou tente usar outro cartão.”
`call_issuer`	O emissor pede que o portador entre em contato.	”Entre em contato com o banco emissor do cartão.”
`card_velocity_exceeded`	Limite de valor ou de quantidade de transações excedido.	”Limite de uso do cartão atingido. Entre em contato com o banco ou tente outro cartão.”
`invalid_amount`	Valor não permitido para o cartão.	”O valor da compra não é permitido para este cartão. Verifique com o banco.”
`invalid_account`	Conta vinculada ao cartão inexistente ou inválida.	”A conta vinculada ao cartão é inválida. Verifique com o banco emissor.”
`transaction_not_permitted`	Operação não habilitada para o portador (ex.: compra pela internet).	”Verifique com o banco se o seu cartão está habilitado para compras pela internet.”
`service_not_allowed`	Tipo de transação não permitido para o cartão.	”Este tipo de transação não é permitido para o cartão. Verifique com o banco.”
`card_not_supported`	Cartão não aceita este tipo de compra.	”O cartão não aceita este tipo de compra. Tente outro cartão.”
`currency_not_supported`	Cartão não aceita a moeda da transação.	”O cartão não aceita a moeda da transação. Tente outro cartão.”
`card_not_activated`	Cartão ainda não desbloqueado pelo cliente.	”Desbloqueie o cartão no app do seu banco e tente novamente.”
`authentication_required`	Transação exige autenticação do portador.	”Sua transação precisa de autenticação. Tente novamente e confirme com o banco.”
`reenter_transaction`	O emissor não processou a transação; vale repetir.	”Não foi possível processar. Tente novamente.”
`approve_with_id`	Não foi possível autorizar o pagamento.	”Não foi possível autorizar o pagamento. Tente novamente ou use outro cartão.”
`not_permitted`	Operação não suportada pelo cartão.	”A operação não é suportada pelo cartão. Tente outro cartão.”
`testmode_decline`	Recusa disparada por um cartão de teste.	”Não foi possível concluir o pagamento. Tente novamente.”
`payment_failed`	Recusa sem um motivo detalhado disponível (fallback).	”Não foi possível concluir o pagamento. Tente novamente.”

`invalid` — dados do cartão incorretos

`code`	Significado	Mensagem ao cliente
`expired_card`	Cartão vencido ou data de validade já passou.	”Verifique a data de validade ou utilize um cartão válido.”
`incorrect_cvc`	Código de segurança (CVV) não confere.	”Confirme o código de segurança (CVV) do cartão.”
`incorrect_number`	Número do cartão incorreto.	”Confirme o número do cartão e tente novamente.”
`invalid_number`	Número do cartão inválido ou emissor inexistente.	”O número do cartão é inválido. Confira os dados e tente novamente.”
`incorrect_pin`	Senha do cartão incorreta.	”A senha do cartão está incorreta.”
`invalid_pin`	Senha do cartão inválida.	”A senha do cartão é inválida.”
`pin_try_exceeded`	Tentativas de senha excedidas.	”Número de tentativas de senha excedido. Use outro cartão.”
`invalid_transaction`	Transação inválida.	”Não foi possível processar a transação. Confira os dados e tente novamente.”
`no_payment_method`	Nenhuma forma de pagamento disponível para cobrar (ex.: assinatura sem cartão).	”Nenhuma forma de pagamento disponível para a cobrança.”
`card_unusable`	Cartão salvo não pôde ser usado.	”O cartão salvo não pôde ser usado. Use outro cartão.”
`payment_method_mismatch`	Forma de pagamento não pertence ao cliente cobrado.	”Use uma forma de pagamento deste cliente.”

`blocked` — restrição ou suspeita de fraude

`code`	Significado	Mensagem ao cliente
`lost_card`	Cartão informado como perdido.	”Transação recusada. Entre em contato com a central do seu cartão.”
`stolen_card`	Cartão informado como roubado.	”Transação recusada. Entre em contato com a central do seu cartão.”
`pickup_card`	Cartão retido por orientação do emissor.	”Transação recusada. Entre em contato com a central do seu cartão.”
`restricted_card`	Cartão em lista de restrição do emissor.	”Transação recusada. Entre em contato com a central do seu cartão.”
`fraudulent`	Transação marcada como suspeita de fraude.	”Transação recusada. Entre em contato com a central do seu cartão.”
`security_violation`	Recusa por violação de segurança.	”Transação recusada por segurança. Entre em contato com a central do seu cartão.”
`stop_payment_order`	Ordem de sustação para o cartão.	”Há uma ordem de sustação para este cartão. Entre em contato com o banco.”
`revocation_of_authorization`	Autorização do cartão revogada.	”A autorização deste cartão foi revogada. Entre em contato com o banco.”
`revocation_of_all_authorizations`	Todas as autorizações do cartão revogadas.	”As autorizações deste cartão foram revogadas. Entre em contato com o banco.”
`transaction_not_allowed`	Transação não permitida.	”Transação não permitida. Entre em contato com a central do seu cartão.”

`processing_error` — falha técnica ou de conectividade

`code`	Significado	Mensagem ao cliente
`issuer_unavailable`	Banco emissor fora do ar ou timeout na comunicação.	”Sistema do banco temporariamente indisponível. Tente novamente em instantes.”
`routing_error`	Não foi possível rotear a transação ao emissor.	”Não foi possível concluir o pagamento. Tente novamente em instantes.”
`duplicate_transaction`	Transação duplicada detectada.	”Esta transação parece duplicada. Verifique se o pagamento já foi feito.”
`try_again_later`	Falha temporária no processamento.	”Não foi possível processar o pagamento. Tente novamente em instantes.”
`connection_error`	Falha de conexão com o processador.	”Não foi possível conectar ao processador de pagamento. Tente novamente.”
`customer_unavailable`	Cliente não pôde ser identificado para a cobrança.	”Não foi possível identificar o cliente para esta cobrança.”
`processing_error`	Falha de comunicação na rede ou erro interno.	”Ocorreu uma falha no processamento. Tente novamente.”

Não mostre o code cru para o comprador — ele é um identificador técnico. Use a mensagem amigável (a coluna “Mensagem ao cliente”), que o checkout hospedado já exibe automaticamente.

Onde o motivo aparece

Resposta da API — GET /v1/charges/{id} traz payment_error; GET /v1/payment-intents/{id} traz last_payment_error da última tentativa.
Webhooks — charge.failed carrega payment_error e payment.intent.failed carrega last_payment_error, ambos no objeto completo em data.object.
Checkout hospedado — o comprador vê a mensagem localizada correspondente ao code, sem nenhum código técnico.

Exemplo: `charge.failed`

{
  "id": "evt_123",
  "object": "event",
  "created_at": "2026-05-19T18:35:00Z",
  "data": {
    "object": {
      "id": "ch_123",
      "object": "charge",
      "amount": 9990,
      "amount_captured": 0,
      "currency": "brl",
      "paid": false,
      "payment_error": {
        "category": "issuer_declined",
        "code": "insufficient_funds",
        "message": "The card has insufficient funds to complete the purchase."
      },
      "status": "failed"
    }
  },
  "livemode": true,
  "organization": "org_123",
  "type": "charge.failed"
}

Como tratar a recusa

Ramifique pela payment_error.category para o tratamento geral e pelo payment_error.code quando precisar de uma mensagem específica. Recusas processing_error costumam valer uma nova tentativa; já blocked (como restricted_card, lost_card ou stolen_card) exigem que o cliente acione o banco.

Reaja ao webhook charge.failed (ou payment.intent.failed) em vez de fazer polling.
Use o metadata da charge/intent para correlacionar a recusa com o pedido no seu sistema.
Para cobranças recorrentes, uma recusa de ciclo move a assinatura para past_due ou unpaid — acompanhe o evento subscription.updated.

Próximos passos

Cobranças

O objeto charge e o ciclo de uma tentativa de cobrança.

Payment Intents

O processo que materializa a charge e expõe last_payment_error.

Evento charge.failed

Payload completo do webhook de cobrança recusada.

Objeto charge

Schema público completo, com o objeto payment_error.

​Como a recusa chega até você

​Testar códigos no sandbox

​Categorias (category)

​Códigos da operadora (code)

​issuer_declined — o banco emissor recusou

​invalid — dados do cartão incorretos

​blocked — restrição ou suspeita de fraude

​processing_error — falha técnica ou de conectividade

​Onde o motivo aparece

​Exemplo: charge.failed

​Como tratar a recusa

​Próximos passos

Cobranças

Payment Intents

Evento charge.failed

Objeto charge

Como a recusa chega até você

Testar códigos no sandbox

Categorias (`category`)

Códigos da operadora (`code`)

`issuer_declined` — o banco emissor recusou

`invalid` — dados do cartão incorretos

`blocked` — restrição ou suspeita de fraude

`processing_error` — falha técnica ou de conectividade

Onde o motivo aparece

Exemplo: `charge.failed`

Como tratar a recusa

Próximos passos