Erros
Códigos de erro
Catálogo dos códigos que a criação, a consulta e o estorno de cobranças podem devolver, com a causa e a ação de cada um, e onde estão os erros de saldo, saques e extrato.
Esta tabela reúne os códigos mais úteis. Trate também códigos desconhecidos, sem assumir aprovação: um código novo pode aparecer sem aviso.
Criação de cobrança: erros HTTP
| HTTP | type | Causa | Ação |
|---|---|---|---|
400 | invalid_idempotency_key | Idempotency-Key vazia ou com mais de 200 caracteres. | Corrija a chave. |
400 | amount_must_be_integer_minor_units | Valor de cartão com casas decimais. | Envie inteiro em centavos. |
400 | amount_mismatch | A soma de paymentMethods[].amount difere de amount. | Iguale o valor do método ao total. |
400 | minimum_amount_not_met | Valor abaixo do mínimo do método (cartão: 50). | Aumente o valor ou use outro método. |
400 | amount_exceeds_maximum | Pix parcelado acima de R$ 10.000,00. | Reduza o valor. |
400 | invalid_currency | Moeda não aceita pelo método (Pix e Pix parcelado só BRL). | Corrija a moeda. |
400 | method_combination_invalid | Combinação de métodos não permitida. | Envie um método por cobrança. |
400 | INVALID_CUSTOMER_ADDRESS_POSTAL_CODE | Cartão sem customer.address, ou endereço brasileiro (ou sem country) sem zipCode. | Envie o endereço; no Brasil, com CEP. |
400 | INVALID_CUSTOMER_ADDRESS | Bloco customer.address sem country, ou brasileiro sem CEP. | Preencha country; no Brasil, também zipCode. |
400 | INVALID_SHIPPING_ADDRESS | Bloco shipping.address sem country, ou brasileiro sem CEP. | Preencha country; no Brasil, também zipCode. |
400 | three_ds_checkout_origin_invalid | threeDs.checkoutOrigin fora do formato ou não cadastrado para a sua conta. | Envie uma origem HTTPS cadastrada. Veja várias lojas. |
400 | three_ds_checkout_origin_required | A venda exige 3DS e a conta tem várias origens, sem padrão. | Envie threeDs.checkoutOrigin. |
400 | INVALID_STATEMENT_DESCRIPTOR | statementDescriptor com mais de 22 caracteres. | Encurte. |
400 | invalid_payment_method_options | Opção fora do intervalo, como parcelas fora de 1 a 24. | Corrija a opção. |
400 | mcc_invalid | mccs com item inválido ou mais de 3 itens. | Use de 1 a 3 códigos de 4 dígitos, sem 0000. |
400 | split_amount_mismatch | A soma do split passa do total. | Corrija as regras. |
400 | split_percentage_scale_invalid | Percentual com mais de 4 casas ou fora de 0 a 100. | Corrija o percentual. |
400 | split_flat_amount_must_be_integer_minor_units | Valor fixo de split com decimais. | Envie inteiro em centavos. |
400 | pagaleve_customer_document_required | Pix parcelado sem CPF. | Envie customer.document. |
400 | pagaleve_invalid_approve_url, pagaleve_invalid_cancel_url | URL de retorno inválida ou com mais de 2048 caracteres. | Corrija a URL. |
400 | pagaleve_checkout_failed | A geração do checkout não concluiu. | Confira dados, telefone e valor. |
400 | high_risk_transaction | A análise de risco recusou a compra. | Não repita automaticamente. |
400 | PaymentIntentCreationError | Dado inválido descrito em detail: nome ou e-mail ausentes, e-mail ou telefone inválidos, cartão inválido ou vencido, código de segurança inválido, bloco card ausente em cartão, problema no split. | Leia detail, corrija e use nova chave. Pode ocorrer depois do processamento: veja Como tratar erros. |
409 | idempotency_key_in_flight | A mesma chave ainda está em processamento. | Aguarde Retry-After e repita. |
409 | idempotency_key_payload_mismatch | A chave foi usada com outro corpo. | Não reutilize a chave. |
422 | merchant_not_eligible | A conta não está habilitada para essa cobrança. | Fale com a equipe de integração. |
422 | PAYMENT_METHOD_NOT_ENABLED | Método, bandeira ou moeda não habilitados na conta. | Confira a habilitação com a equipe de integração. |
422 | merchant_currency_not_enabled | A conta não tem liquidação habilitada na moeda. | Use BRL ou peça a habilitação. |
422 | currency_not_supported, card_not_supported, installments_not_supported | Moeda, cartão ou parcelamento não aceitos para a conta. | Ofereça outra condição. |
422 | merchant_configuration_incomplete, no_provider_available, authentication_required | A cobrança não pode ser processada nas condições atuais da conta. | Fale com a equipe de integração. |
422 | card_token_not_found | Token inexistente, de outra conta (inclusive da outra operação, doméstica ou offshore) ou com formato inválido. | Confira o token e a chave usada. |
422 | card_token_not_usable | Token revogado, suspenso ou sem credencial ativa. | Peça outro cartão. |
422 | card_token_consumed | Token do SDK de campos já usado por outra cobrança. | Gere um novo token. |
422 | card_token_expired | Token do SDK de campos com mais de 1 hora. | Gere um novo token. |
500 | pix_generation_failed | O QR Code não pôde ser gerado. | Repita com a mesma chave. |
503 | temporarily_unavailable | Indisponibilidade temporária. | Repita após Retry-After. |
503 | vault_unavailable | Cofre de cartões indisponível. | Repita após Retry-After, com a mesma chave. |
503 | idempotency_unavailable | O controle de idempotência está indisponível; nada foi processado. | Repita após Retry-After, com a mesma chave. |
Criação de cobrança: lastPaymentError.code em 201 Failed
code | category | Causa |
|---|---|---|
Código do emissor, como 05, 51, 54 | issuer_decline ou card_data_invalid | Recusa do banco emissor. |
CARD_REFUSED | issuer_decline | Recusa sem código específico. |
card_data_invalid | card_data_invalid | Dados do cartão inválidos. |
installments_not_supported | provider_rejected | Parcelamento não disponível para o cartão. |
provider_rejected | provider_rejected | O processador recusou a transação. |
provider_unavailable | provider_unavailable | Processamento indisponível. |
three_ds_session_token_required | contract_validation | A compra exige 3DS e não foi enviada threeDs.sessionToken. |
three_ds_session_not_found | authentication | Sessão 3DS inexistente ou com formato inválido. |
three_ds_session_expired | authentication | Sessão 3DS vencida. Abra outra. |
three_ds_session_already_used | authentication | Sessão já usada por outra cobrança. Abra outra. |
three_ds_device_data_required | authentication | A coleta do dispositivo não foi concluída para esta sessão. |
three_ds_session_amount_mismatch | — | Valor ou moeda da cobrança diferente do da sessão. |
three_ds_session_scope_mismatch | — | transaction_scope da sessão diferente do escopo da conta. |
INVALID_BILLING_POSTAL_CODE | — | CEP inválido para o 3DS, como 00000000. |
merchant_not_eligible, currency_not_supported, card_not_supported, installments_not_supported, no_provider_available, authentication_required | acceptance | A cobrança não é aceita para a conta, o cartão ou as condições. |
card_token_not_found, card_token_not_usable, card_token_consumed, card_token_expired, vault_unavailable | — | Problema com o token, detectado durante a autenticação. |
Consulta
| HTTP | type | Causa |
|---|---|---|
404 | PaymentIntentNotFound | Cobrança inexistente. Logo depois da criação, repita após alguns segundos. |
404 | sem corpo | O id não é um UUID. |
500 | PaymentIntentRetrievalError | Falha temporária. Repita. |
Estorno
| HTTP | type | Causa |
|---|---|---|
404 | PaymentIntentNotFound | Cobrança inexistente. |
409 | AlreadyRefunded | Estorno já concluído. |
422 | PaymentIntentNotRefundable | A cobrança não está Succeeded. |
500 | outros | Falha inesperada. Repita com a mesma idempotencyKey. |
Para sessão 3DS, SDK de campos, tokenização, saldo, saques e extrato, veja os erros em cada página: sessão 3DS, SDK de campos, tokenização, saldo, saques e extrato.