> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Códigos de falha
> Códigos de falha de charges.
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éricos**
Có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](/integrate/sandbox#falhas-de-cartao) 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`
```json charge.failed theme={}
{
"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
O objeto `charge` e o ciclo de uma tentativa de cobrança.
O processo que materializa a charge e expõe `last_payment_error`.
Payload completo do webhook de cobrança recusada.
Schema público completo, com o objeto `payment_error`.