Getnet DocsGetnet Docs

Referência de códigos de erro

Esta página cataloga os códigos de resultado que o SDK White Label retorna. Use-a para associar um código à sua causa e decidir como reagir. Para um passo a passo orientado a tarefas, consulte Solução de problemas.

Esquema de códigos de resultado

Todo desfecho carrega um código de resultado. O prefixo identifica a classe da falha.

PrefixoTipoSignificado
00SUCCESSTransação aprovada ou paga.
1-POS_ERRORErro local, do terminal, de leitura do cartão ou do operador (família ADQ).
3-CriptográficoReservado para erros criptográficos. Está definido, mas hoje não é emitido.
33-HOST_ERRORErro do serviço de pagamento (SEP) — um erro HTTP ou uma recusa do host.

Exemplos

CódigoSignificado
00Aprovada.
1-02Cancelada pelo usuário ou pelo operador (ou um TIMEOUT / CANCELED do kernel).
1-21Recusa offline ou erro genérico do terminal.
33-<reason>Recusa do host. <reason> é o reason_code da resposta do SEP (HTTP 200, DENIED).
33-<httpCode>Erro HTTP retornado pelo SEP, por exemplo 33-400, 33-401, 33-500.
33-99Erro genérico do host, sem código utilizável.

Os erros de host estão migrando do prefixo antigo 4-xx para 33-xx: os dígitos não mudam (4-503 passa a ser 33-503). Terminais que ainda não foram atualizados podem retornar 4-xxx. Trate 4-xxx e 33-xxx como equivalentes.

Categorias de causa

Toda não aprovação pertence a uma categoria, que indica como reagir. Cada código de host abaixo traz a sua categoria.

CategoriaSignificado
Portador / cartãoO emissor ou o cartão recusou a operação. Peça outro cartão ou oriente o cliente a falar com o banco.
Transitório — nova tentativaCondição temporária. Tente de novo após uma breve espera; se houve timeout, consulte a transação antes.
Duplicada / em andamentoA transação pode já estar concluída ou cancelada. Consulte antes de tentar de novo.
Referência não encontradaO paymentId ou a referência não corresponde a nenhuma transação. Confirme o valor e o ambiente.
Configuração do estabelecimento / produtoO estabelecimento, o produto, a bandeira ou o terminal não está habilitado. Fale com a Getnet.
AutenticaçãoO terminal não conseguiu se autenticar no gateway. Verifique as credenciais e o ambiente.
Integração / requisiçãoA requisição estava malformada ou foi rejeitada pela validação. Corrija a integração.
Plataforma / sistemaFalha no lado do servidor. Tente de novo uma vez; se persistir, trate como incidente.

Estrutura do erro de host

Os erros de host (33-) têm origem no gateway do SEP. O campo em que você deve ramificar é o error_code; o reason_code traz o motivo do emissor em uma recusa.

CampoDescrição
messageMensagem de erro legível.
nameTipo do erro, por exemplo GetnetTransactionError.
status_codeStatus HTTP da resposta, por exemplo 400.
details[].statusStatus da transação, por exemplo DENIED.
details[].error_codeO código de erro em que você deve ramificar, por exemplo PAYMENTS-999.
details[].reason_codeMotivo do emissor em uma recusa, por exemplo 503.

Erros de host (33-) por status HTTP

HTTP 400 — 33-400

error_codeCategoriaDescrição
PAYMENTS-012Integração / requisiçãoValor informado é maior ou igual ao valor da transação.
PAYMENTS-013Integração / requisiçãoValor da parcela inválido.
PAYMENTS-015Portador / cartãoEntre em contato com o emissor.
PAYMENTS-016Integração / requisiçãoNSU inválido.
PAYMENTS-019Portador / cartãoData de emissão do cartão inválida.
PAYMENTS-020Portador / cartãoData de validade inválida.
PAYMENTS-024Transitório — nova tentativaTransação revertida.
PAYMENTS-025Portador / cartãoAutenticação inválida.
PAYMENTS-026Portador / cartãoAutorização inválida.
PAYMENTS-029Integração / requisiçãoPré-autorização inválida.
PAYMENTS-044Integração / requisiçãoErro de formato.
PAYMENTS-050Portador / cartãoEntre em contato com a instituição.
PAYMENTS-051Portador / cartãoRecusada por uma regra configurada.
PAYMENTS-054Duplicada / em andamentoConfirmação pendente.
PAYMENTS-055Transitório — nova tentativaTransação cancelada.
PAYMENTS-056Portador / cartãoTransação não permitida neste ciclo.
PAYMENTS-058Transitório — nova tentativaReverta a transação.
PAYMENTS-060Integração / requisiçãoCartão obrigatório para a transação.
PAYMENTS-061Portador / cartãoRejeição genérica.
PAYMENTS-066Configuração do estabelecimento / produtoMeio de pagamento inválido.
PAYMENTS-068Portador / cartãoDígito do cartão inválido.
PAYMENTS-069Duplicada / em andamentoTransação repetida.
PAYMENTS-070Portador / cartãoNúmero do cartão não corresponde.
PAYMENTS-072Integração / requisiçãoA transação não pode ser cancelada.
PAYMENTS-073Duplicada / em andamentoTransação já cancelada.
PAYMENTS-078Integração / requisiçãoDados inválidos no cancelamento.
PAYMENTS-079Integração / requisiçãoValor de cancelamento inválido.
PAYMENTS-080Portador / cartãoCartão inválido.
PAYMENTS-081Integração / requisiçãoApós a data permitida.
PAYMENTS-082Integração / requisiçãoCancelamento inválido.
PAYMENTS-083Portador / cartãoUse a função débito.
PAYMENTS-084Portador / cartãoUse a função crédito.
PAYMENTS-085Duplicada / em andamentoTransação já realizada.
PAYMENTS-090Portador / cartãoTransação não autorizada pelo cartão.
PAYMENTS-091Integração / requisiçãoFora do período permitido.
PAYMENTS-093Duplicada / em andamentoAutorização já em processamento.
PAYMENTS-094Transitório — nova tentativaAutorização aguardando confirmação de recebimento.
PAYMENTS-098Configuração do estabelecimento / produtoCliente não cadastrado.
PAYMENTS-117Portador / cartãoPeça ao portador que ligue para o emissor.
PAYMENTS-118Configuração do estabelecimento / produtoCartão inválido ou produto não habilitado.
PAYMENTS-999Transitório — nova tentativaTransação não processada.
GENERIC-400Portador / cartãoCartão de crédito inválido.
GENERIC-400Integração / requisiçãoErro de validação.
GENERIC-400Integração / requisiçãoValidação de cabeçalho.
GENERIC-400Integração / requisiçãoErro ao solicitar o cancelamento.
GENERIC-400Plataforma / sistemaErro de serviço.
GENERIC-400Integração / requisiçãoParâmetro inválido.
GENERIC-400Integração / requisiçãoArgumento inválido.
GENERIC-400Configuração do estabelecimento / produtoCódigo da bandeira não habilitado.
GENERIC-400Integração / requisiçãoErro de validação da consulta.

HTTP 401 — 33-401

error_codeCategoriaDescrição
GENERIC-401AutenticaçãoNão autorizado.

HTTP 402 — 33-402

error_codeCategoriaDescrição
PAYMENTS-001Integração / requisiçãoValor não informado.
PAYMENTS-002Portador / cartãoCartão inválido.
PAYMENTS-003Portador / cartãoCartão expirado.
PAYMENTS-004Integração / requisiçãoParâmetro inválido.
PAYMENTS-005Portador / cartãoCódigo de segurança inválido.
PAYMENTS-006Configuração do estabelecimento / produtoBandeira inválida.
PAYMENTS-007Configuração do estabelecimento / produtoOperação não permitida.
PAYMENTS-008Integração / requisiçãoDados inválidos.
PAYMENTS-009Integração / requisiçãoValor mínimo da parcela inválido.
PAYMENTS-010Integração / requisiçãoNúmero de parcelas inválido.
PAYMENTS-011Integração / requisiçãoNúmero de parcelas acima do limite.
PAYMENTS-014Configuração do estabelecimento / produtoParcelamento não permitido.
PAYMENTS-022Configuração do estabelecimento / produtoCódigo de moeda inválido.
PAYMENTS-023Configuração do estabelecimento / produtoBandeira não pertence à rede.
PAYMENTS-030Portador / cartãoErro na autenticação do usuário.
PAYMENTS-032Portador / cartãoNegada pelo emissor.
PAYMENTS-033Configuração do estabelecimento / produtoEstabelecimento inválido.
PAYMENTS-034Configuração do estabelecimento / produtoSolicitação não autorizada.
PAYMENTS-036Integração / requisiçãoIdentificador da requisição inválido.
PAYMENTS-037Duplicada / em andamentoTransação em andamento.
PAYMENTS-038Integração / requisiçãoTransação inválida.
PAYMENTS-039Integração / requisiçãoValor da transação inválido.
PAYMENTS-041Transitório — nova tentativaRefaça a transação.
PAYMENTS-045Portador / cartãoCartão restrito.
PAYMENTS-046Portador / cartãoCartão perdido.
PAYMENTS-047Portador / cartãoCartão roubado.
PAYMENTS-048Portador / cartãoCartão não cadastrado.
PAYMENTS-049Portador / cartãoTransação não permitida para este cliente.
PAYMENTS-052Duplicada / em andamentoTransação duplicada.
PAYMENTS-053Portador / cartãoCartão bloqueado.
PAYMENTS-067Portador / cartãoValor limite excedido.
PAYMENTS-077Portador / cartãoNúmero do cartão inválido.
PAYMENTS-096Portador / cartãoCrédito excedido.
PAYMENTS-101Plataforma / sistemaAutorizador offline.
PAYMENTS-102Portador / cartãoCliente sem limite de crédito.
PAYMENTS-103Portador / cartãoTransação não autorizada pela rede autorizadora.
PAYMENTS-104Integração / requisiçãoErro de integração.
PAYMENTS-105Portador / cartãoTransação não autorizada.
PAYMENTS-109Duplicada / em andamentoExiste uma transação a confirmar.
PAYMENTS-112Referência não encontradaNenhum documento correspondente para cancelar.
PAYMENTS-113Portador / cartãoSaldo insuficiente.
PAYMENTS-114Portador / cartãoExcede o limite de valor para aprovação.
PAYMENTS-115Portador / cartãoExcede o limite de frequência de saques.
PAYMENTS-116Portador / cartãoAutorização recusada.
SERVICE-402Plataforma / sistemaErro ao capturar a transação de crédito.
SERVICE-402Plataforma / sistemaErro ao ajustar a transação de pré-autorização de crédito.
GENERIC-402Plataforma / sistemaErro ao criar a transação diferida.
GENERIC-402Integração / requisiçãoPagamento diferido expirado.
GENERIC-402Portador / cartãoRecusada pela análise antifraude.
GENERIC-402Integração / requisiçãoDocumento inválido.
GENERIC-402Plataforma / sistemaErro ao cancelar a transação de crédito.
GENERIC-402Integração / requisiçãoErro ao validar as regras de negócio.

HTTP 403 — 33-403

error_codeCategoriaDescrição
GENERIC-403Configuração do estabelecimento / produtoMeio de pagamento não permitido.
GENERIC-403Configuração do estabelecimento / produtoTipo de bandeira não permitido.
GENERIC-403Configuração do estabelecimento / produtoServiço não habilitado.
GENERIC-403AutenticaçãoToken inválido ou já usado.
GENERIC-403AutenticaçãoErro de não autorizado.
GENERIC-403Configuração do estabelecimento / produtoProduto Pix não habilitado.

HTTP 404 — 33-404

error_codeCategoriaDescrição
PAYMENTS-043Referência não encontradaRegistro não encontrado.
PAYMENTS-057Referência não encontradaA transação não existe.
PAYMENTS-076Referência não encontradaTransação não disponível.
PAYMENTS-095Referência não encontradaAutorização não encontrada.
GENERIC-404Referência não encontradaErro ao criar a transação diferida.
GENERIC-404Referência não encontradaTransação não encontrada.
GENERIC-404Referência não encontradaRegistro não encontrado.

HTTP 409 — 33-409

error_codeCategoriaDescrição
GENERIC-409Integração / requisiçãoNão foi possível processar a requisição por conflito entre parâmetros.

HTTP 412 — 33-412

error_codeCategoriaDescrição
GENERIC-412Integração / requisiçãoParâmetro não encontrado.
GENERIC-412Integração / requisiçãoParâmetro não definido.

HTTP 422 — 33-422

error_codeCategoriaDescrição
GENERIC-422Integração / requisiçãoEntidade não processável.

HTTP 500 — 33-500

error_codeCategoriaDescrição
PAYMENTS-042Plataforma / sistemaResposta inválida.
PAYMENTS-059Transitório — nova tentativaProblema na rede local.
PAYMENTS-062Plataforma / sistemaInstituição temporariamente fora de operação.
PAYMENTS-063Plataforma / sistemaFalha no sistema.
PAYMENTS-064Plataforma / sistemaErro no banco de dados.
PAYMENTS-071Plataforma / sistemaAutorizador temporariamente bloqueado.
PAYMENTS-086Plataforma / sistemaErro na transação.
PAYMENTS-099Plataforma / sistemaAutorizador não inicializado.
PAYMENTS-100Plataforma / sistemaCanal desconectado.
PAYMENTS-107Transitório — nova tentativaErro de comunicação.
PAYMENTS-500Plataforma / sistemaErro interno do servidor.
GENERIC-500Plataforma / sistemaO servidor encontrou um erro inesperado.

HTTP 501 — 33-501

error_codeCategoriaDescrição
GENERIC-501Plataforma / sistemaResposta inválida do servidor upstream.

HTTP 503 — 33-503

error_codeCategoriaDescrição
PAYMENTS-021Transitório — nova tentativaSistema do emissor indisponível — tente de novo.
GENERIC-503Transitório — nova tentativaO servidor não pode atender à requisição agora — tente mais tarde.

HTTP 504 — 33-504

error_codeCategoriaDescrição
PAYMENTS-031Transitório — nova tentativaTempo excedido (timeout).
PAYMENTS-089Transitório — nova tentativaTimeout interno.
GENERIC-504Transitório — nova tentativaTimeout de conexão.

Erros de cartão / EMV (1-)

Origem: o kernel EMV e o hardware do terminal. A coluna Tipo de leitura agrupa os códigos pela forma como o cartão foi apresentado; Nova tentativa marca os códigos que o SDK pode repetir e Fallback indica o método de leitura para o qual recorrer. Os códigos marcados como Interno não são exibidos ao portador e normalmente exigem suporte da Getnet.

ConstanteCódigo de resultadoTipo de leituraNova tentativaFallbackDescrição
CTLSFALLBACK1-53Contactless (NFC)SimContactlessNão foi possível ler por contactless. Insira o chip ou passe a tarja. Fallback normal.
ERRCTLSS1-33 (tarja 1-08)Contactless (NFC)Sim—Erro na leitura por contactless. Tente o chip ou a tarja.
CTLSSPROBLEMS1-33 (tarja 1-08)Contactless (NFC)SimContactlessProblema na leitura por contactless. Tente de novo ou insira o cartão.
CTLSSMULTIPLE1-21Contactless (NFC)——Vários cartões detectados. Apresente um único cartão ao leitor.
CTLSSAPPNAV1-50Contactless (NFC)Sim—O cartão não suporta contactless. Insira o chip.
CTLSSAPPNAUT1-50Contactless (NFC)Sim—Contactless não autorizado para este cartão. Insira o chip.
CTLSSINVALIDAT1-34Contactless (NFC)SimContactlessCartão contactless não válido (expirado ou inativo). Fale com o banco.
CTLSSEXTCVM1-21Contactless (NFC)Sim—O cartão exige PIN. Insira o chip.
CARDBLOCKED1-34Cartão com chip——O cartão está bloqueado. Fale com o banco.
CARDINV1-21Cartão com chip——O cartão não é válido. Tente outro cartão.
CARDINVALIDAT1-34Cartão com chipSimChipCartão expirado ou ainda não ativo. Fale com o banco.
CARDNOTEFFECT1-21Cartão com chip——Cartão ainda não válido. Fale com o banco.
CARDINVDATA1-21Cartão com chip——Não foi possível ler os dados do chip. Tente de novo ou use outro método.
CARDAPPNAV1-50Cartão com chipSim—Cartão não compatível com este terminal. Tente outro cartão.
CARDAPPNAUT1-21Cartão com chip——O cartão não autorizou a transação. Fale com o banco.
CARDPROBLEMS1-21Cartão com chipSimChipProblema na leitura do chip. Limpe o cartão e tente de novo.
DUMBCARD1-36Cartão com chipSimChipO cartão não tem chip. Passe a tarja magnética.
ERRFALBACK1-36FallbackSimChipNão foi possível ler o chip. Passe a tarja magnética.
NOCARD1-36LeituraSimContactlessNenhum cartão detectado. Aproxime, insira ou passe o cartão.
TIMEOUT1-02Leitura——O tempo de espera acabou. Tente de novo. Tratado como cancelamento.
CANCELED1-02Operação——A transação foi cancelada pelo operador ou pelo cliente.
ERRPIN1-21PIN——Erro na digitação do PIN. Verifique e tente de novo.
NOBALANCE1-21Autorização——Saldo insuficiente. Tente outro cartão.
LIMITEXC1-21Autorização——O valor excede o limite do cartão. Fale com o banco.
LOCKED1-21Terminal——O terminal está travado. Anote o número de série e fale com a Getnet.
TABLE_ERROR1-21Interno——Erro nas tabelas de configuração EMV (AID/terminal) carregadas no kernel.
NO_MATCH1-21InternoSim—Nenhum AID do cartão corresponde aos AIDs configurados no terminal.
INVPARM1-21Interno——Parâmetro inválido enviado ao kernel EMV (erro de programação).
EXECERR1-21Interno——Erro interno de execução no kernel EMV.
TABERR1-21Interno——Erro ao acessar uma tabela interna do EMV.
UNKNOWNSTAT1-21Interno——Estado desconhecido retornado pelo kernel.
RSPERR1-21Interno——Erro na resposta recebida do host ou do autorizador.
COMMTOUT1-21Interno——Timeout de comunicação com o host. Consulte a transação antes de tentar cobrar de novo.
INTERR1-21InternoSim—Erro interno do kernel. Emitido em todo onPanic e no onError(INTERR) do kernel.
MCDATAERR1-33 (tarja 1-08)InternoSim—Erro nos dados lidos da tarja magnética.
PINBUSY1-21Interno——O módulo de PIN está ocupado processando outra requisição.
ERRCARD1-36InternoSimChipErro genérico de cartão, sem classificação específica.
CARDERRSTRUCT1-21InternoSimChipErro na estrutura do chip (TLV malformado).

Erros de warm-up

O SDK informa estes erros antes de uma venda, por meio de setOnWarmUpStatus.

CódigoConstanteCategoriaO que significaAção
-1ERROR_NO_CONNECTIONTransitório — nova tentativaSem conexão de rede.Verifique o Wi-Fi ou os dados móveis e tente de novo na tela de warm-up.
-2ERROR_TIMEOUTTransitório — nova tentativaTimeout de rede durante o warm-up.Verifique a conexão e tente de novo. Se persistir em vários terminais, escale o caso.
-3ERROR_SSLPlataforma / sistemaFalha no handshake SSL/TLS.Confira a data e a hora do dispositivo; se estiverem corretas, fale com a Getnet.
-4ERROR_CONNECTTransitório — nova tentativaNão foi possível conectar ao host.Verifique a conexão e o ambiente; tente de novo.
-5ERROR_SOCKETTransitório — nova tentativaErro de socket durante a transferência.Tente de novo; se persistir, escale o caso (conexão instável).
400HTTP_BAD_REQUESTIntegração / requisiçãoRequisição de warm-up ou de configuração rejeitada como malformada.Fale com a Getnet — credenciais ou configuração do terminalCode.
401HTTP_UNAUTHORIZEDAutenticaçãoclient_id / client_secret inválidos (falha no OAuth2).Fale com a Getnet — credenciais ou ambiente incorretos.
404HTTP_NOT_FOUNDReferência não encontradaTerminal ou recurso de configuração não encontrado.Anote o código do terminal e fale com a Getnet — o terminal pode não estar cadastrado.
422HTTP_UNPROCESSABLEIntegração / requisiçãoRequisição de configuração rejeitada semanticamente.Fale com a Getnet — valores de configuração do sub-merchant ou do terminal.

Ambientes

AmbienteBuildURL base
Pré-produção / Desenvolvimentodebughttps://api.pre.globalgetnet.com/
Homologação (HML)hmlhttps://api.sbx.globalgetnet.com/
Produçãoreleasehttps://api.globalgetnet.com/

Mapeamento dos meios de pagamento

Como cada meio de pagamento é mapeado da configuração no SDK para o valor enviado ao SEP e o tipo de aplicação.

MeioConfiguração no SDKValor no SEPTipo de aplicação
CréditoBrSaleSetup.Credit / IBrSaleMethod.CreditCardDIRECT_CREDIT01
DébitoBrSaleSetup.Debit / IBrSaleMethod.DebitCardDIRECT_DEBIT02
VoucherBrSaleSetup.Voucher / IBrSaleMethod.VoucherDIRECT_VOUCHER12
PixBrSaleSetup.Pix / IBrSaleMethod.PixFluxo de QR Code (não o corpo de cartão)30

Serviços que o SDK chama

Você não chama esses serviços diretamente — o SDK chama. Eles estão listados para mostrar de onde vêm os erros de host (33-) e de warm-up.

MétodoCaminhoFinalidade
POSTdpm/payments-gwproxy/v2/paymentsCria um pagamento (venda / etapa única). É a principal transação presencial.
POSTdpm/payments-gwproxy/v2/payments/cancelCancela ou estorna um pagamento.
POSTdpm/payments-gwproxy/v2/payments/qrcode/pixGera um QR Code Pix.
GETdpm/hub-payment-info/v1/payments/info/{payment_id}Consulta o status de uma transação ou de um Pix. Use após um timeout.
POSTauthentication/oauth2/access_tokenToken OAuth2 (client_credentials), injetado como Bearer em toda chamada ao SEP.
POSTtms/terminal-management-adp/v1/configurationBusca a configuração do terminal durante o warm-up.
PATCHtms/terminal-management-adp/v1/configuration/confirmationConfirma a configuração do terminal.

Recursos relacionados