Solução de problemas

Este guia ajuda você a diagnosticar falhas durante uma integração com o SDK White Label e a decidir o que fazer em cada caso. Ele cobre as falhas que você trata no seu próprio aplicativo. Entre elas estão problemas de warm-up, pagamentos recusados, erros de serviço, falhas na leitura do cartão, timeouts e estornos que não se concluem.

Para o catálogo completo de códigos de resultado e mensagens, consulte a Referência de códigos de erro.

Leia primeiro o código de resultado

Toda falha traz um código de resultado com um prefixo que indica a classe da falha. Leia o prefixo antes de qualquer outra coisa.

O código chega ao seu aplicativo em TransactionResult.result, acompanhado de um resultMessage legível. Trate 00 como aprovação e qualquer outro valor como não aprovação.

Identifique a tela de erro

Nos fluxos com cartão, o SDK exibe uma de duas telas de erro antes de devolver o controle ao seu aplicativo. O Pix tem a própria tela de erro.

Tela	Quando aparece	O que o operador deve fazer
	O terminal leu o cartão corretamente, mas o emissor recusou o pagamento (33-<reason>).	A recusa vem do banco do portador do cartão, não do terminal. Peça outro cartão ou oriente o cliente a falar com o banco dele.
	O serviço de pagamento falhou ou estava indisponível — um erro de host ou um timeout (33-5xx).	Verifique o status da transação antes de tentar de novo, para não cobrar duas vezes. Se continuar acontecendo em vários terminais, trate como incidente de plataforma.

Classifique a falha

Toda não aprovação cai em uma destas categorias. A categoria indica se você trata a falha no seu aplicativo, pede uma ação ao operador ou aciona a Getnet.

Cenários comuns

Cada cenário apresenta o sintoma, a causa provável e a solução.

O warm-up falha e o SDK nunca fica pronto

O SDK informa Failure(cause) por meio de setOnWarmUpStatus, ou uma operação nunca começa.

Causa. O warm-up carrega a configuração do terminal e se autentica no serviço de pagamento. Ele falha quando não há conexão de rede, quando as credenciais estão erradas ou quando o terminal não está registrado.

Solução

1. Verifique o Wi-Fi ou os dados móveis do terminal.
2. Analise o código de erro do warm-up. De -1 a -5 são condições de rede — tente de novo. 401 indica que o clientId / clientSecret ou o ambiente está errado. 404 indica que o terminal não está registrado para esta configuração.
3. Para recuperar, chame ApoloSdk.shutdown() e depois configure e execute build() novamente.
4. Se um 401, 404 ou 422 persistir, confirme as credenciais, o terminalCode e o ambiente com a Getnet.

Consulte os códigos de warm-up na Referência de códigos de erro.

Um pagamento é recusado

O terminal lê o cartão normalmente, mas o resultado é 33-<reason> e a tela “Pagamento recusado” aparece.

Causa. O emissor recusou a autorização — por exemplo, saldo insuficiente, cartão bloqueado ou cartão vencido. É uma decisão do lado do portador do cartão, não uma falha do terminal.

Solução

1. Peça outro cartão ao cliente ou oriente-o a falar com o banco.
2. Escale o caso somente se um cartão que o cliente diz ser válido falhar em vários terminais.

“Pagamento interrompido” — erro de serviço

A tela “Pagamento interrompido” aparece com um código 33-5xx (por exemplo, 33-500, 33-503, 33-504).

Causa. O serviço de pagamento falhou ou ficou temporariamente indisponível — uma condição de servidor ou de timeout.

Solução

1. Não tente de novo imediatamente.
2. Consulte a transação pelo paymentId para confirmar se ela foi concluída.
3. Se não foi, tente de novo uma vez, após uma breve espera.
4. Se persistir ou afetar vários terminais, trate como incidente de plataforma e acione a Getnet.

O cartão não é lido

O terminal repete “insira, aproxime ou passe o cartão”, ou a leitura por aproximação falha.

Causa. A leitura por aproximação ou por chip falhou. Em geral, esse é um fallback normal, não um erro.

Solução

1. Peça ao cliente para inserir o chip. Se o chip falhar, peça para passar a tarja magnética.
2. Se o terminal detectar vários cartões ao mesmo tempo, peça ao cliente para apresentar um único cartão, longe de outros cartões ou da carteira.
3. Se um cartão específico falhar em todos os métodos, peça outro cartão.

Timeout — você não sabe se o cliente foi cobrado

O resultado é um timeout (33-504) ou a operação termina sem um desfecho claro.

Causa. A resposta não chegou dentro da janela de tempo limite, então o desfecho é desconhecido — a cobrança pode ter sido concluída ou não.

Solução

1. Não inicie uma nova venda com o mesmo valor por enquanto.
2. Consulte a transação pelo paymentId para confirmar se ela foi autorizada.
3. Inicie uma nova venda somente depois de confirmar que a primeira não foi concluída.

Um estorno ou cancelamento falha com “not found”

O estorno retorna um 33-404 com a mensagem “not found”.

Causa. O paymentId ou o ambiente usado no estorno não corresponde à transação original. Uma referência errada é a causa mais comum.

Solução

1. Confirme o paymentId da transação original.
2. Confirme que você está no mesmo ambiente em que fez a venda.
3. Tente o estorno de novo com a referência corrigida.

A transação é informada como duplicada ou já existente

O resultado indica que a transação já está em andamento, já foi concluída ou já foi cancelada.

Causa. A operação já terminou, ou ainda está em processamento.

Solução

1. Verifique o recibo impresso ou consulte o pagamento antes de agir.
2. Não repita a operação até confirmar o estado real dela.

Antes de acionar a Getnet

Algumas falhas exigem o suporte da Getnet: configuração, autenticação, um 5xx persistente, um terminal travado ou um erro interno de EMV. Reúna estas informações antes de entrar em contato, para que o suporte localize a transação e reproduza o problema.

Próximos passos

• Referência de códigos de erro — o catálogo completo de códigos de host, de cartão e de warm-up.
• Referência do resultado da transação — os campos de resultado e os payloads retornados ao seu aplicativo.
• Referência de inicialização — os estados do warm-up e como se recuperar de um Failure.
• Registre telemetria — registre suas próprias entradas de diagnóstico para correlacionar com os traces do SDK.