Tratamento de erros
O aplicativo Pinpad Getnet utiliza um sistema estruturado de relatório de erros para informar o Sistema Host sobre problemas encontrados durante a execução de comandos, interações do usuário ou falhas de hardware.
O relatório de erro Y0E
Quando um processo falha ou é interrompido, o Pinpad envia automaticamente um relatório Y0E. Esta é uma resposta assíncrona que substitui a resposta de sucesso esperada (como um Y02). A lógica do seu Sistema Host deve estar preparada para capturar um Y0E em qualquer ponto durante um fluxo de transação ativa.
Estrutura da resposta Y0E [Pinpad]
O relatório contém identificadores específicos para ajudar seu software a diagnosticar a falha:
| Campo | Atributo | Descrição |
|---|---|---|
| [CID] | 3 ANS | Identificador do Comando (“Y0E”). |
| [COE] | 2 N | Código de Erro: Valor numérico identificando a causa raiz. |
| [MOE] | 20 ANS | Mensagem de Erro: Texto descritivo (ex: “CANCELADO”). |
Códigos de erro comuns
Entender esses códigos é essencial para implementar uma lógica de recuperação suave e mensagens claras para o usuário em seu Sistema Host.
| Código | Mensagem | Descrição/Causa |
|---|---|---|
| 01 | CANCELADO | O usuário pressionou o botão vermelho “Cancela” ou o Host enviou um Y06. |
| 02 | FALLA LECTURA | Falha geral na leitura do cartão (ex: chip danificado ou tarja ilegível). |
| 03 | TARJETA INVALIDA | O cartão não é suportado ou está bloqueado. |
| 04 | ERROR EMV | Ocorreu um erro de protocolo durante o fluxo EMV L3. |
| 05 | ERROR PIN | Ocorreu um erro durante o processo de entrada segura do PIN. |
| 07 | TIMEOUT | O tempo de espera para uma ação do usuário ou comando expirou. |
| 08 | SIN LLAVES | As chaves DUKPT ou RSA necessárias estão ausentes no terminal. |
Gerenciando timeouts
Para evitar que o dispositivo trave indefinidamente se um usuário se afastar, o sistema utiliza timeouts dinâmicos e baseados em hardware.
Timeouts de sessão
O Sistema Host define o tempo máximo de espera para a interação do usuário no início da transação.
- Campo:
[TEC]dentro do comando de inicialização (Y19). - Valor: Definido em segundos (ex:
060para 60 segundos). - Comportamento: Se o usuário não apresentar um cartão dentro desta janela, o Pinpad aborta a operação e envia um Y0E com código 07 (Timeout).
Timeouts internos de hardware
Certos eventos criptográficos ou de inicialização de hardware possuem timeouts internos fixos. Se um processo interno falhar devido a uma falha de hardware, o terminal normalmente retorna um código de erro geral.
Integridade da comunicação (ACK/NAK)
Antes que a lógica do aplicativo processe um comando, a camada de comunicação de baixo nível (SerialCom) valida a integridade da mensagem.
<ACK>(06h): Enviado se a estrutura da mensagem e o checksum LRC/CRC estiverem corretos.<NAK>(15h): Enviado se a mensagem estiver corrompida. Você deve tentar reenviar imediatamente o último comando.
Próximos passos
Com sua lógica de tratamento de erros implementada, você pode avançar para os estágios finais da sua integração:
- Dicionário de Comandos da API: Consulte a referência técnica completa para cada comando e seus possíveis estados de erro.