Getnet DocsGetnet Docs

Error Handling

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

The Pinpad Getnet application uses a structured error reporting system to inform the Host System of issues encountered during command execution, user interactions, or hardware failures.

The Y0E error report

When a process fails or is interrupted, the Pinpad automatically sends a Y0E report. This is an asynchronous response that replaces the expected success response (such as a Y02). Your Host System logic must be prepared to catch a Y0E at any point during an active transaction flow.

Y0E response structure [Pinpad]

The report contains specific identifiers to help your software diagnose the failure:

FieldAttributeDescription
[CID]3 ANSCommand Identifier (“Y0E”).
[COE]2 NError Code: Numeric value identifying the root cause.
[MOE]20 ANSError Message: Descriptive text (e.g., “CANCELADO”).

Common error codes

Understanding these codes is essential for implementing graceful recovery logic and clear user messaging on your Host System.

CodeMessageDescription/Cause
01CANCELADOThe user pressed the red “Cancel” button or the Host sent a Y06 command.
02FALLA LECTURAGeneral card reading failure (e.g., damaged chip or unreadable stripe).
03TARJETA INVALIDAThe card is not supported or is blocked.
04ERROR EMVA protocol error occurred during the EMV L3 flow.
05ERROR PINAn error occurred during the secure PIN entry process.
07TIMEOUTThe wait time for a user action or command has expired.
08SIN LLAVESThe required DUKPT or RSA keys are missing from the terminal.

Managing timeouts

To prevent the device from hanging indefinitely if a user walks away, the system employs dynamic and hardware-backed timeouts.

Session timeouts

The Host System defines the maximum wait time for user interaction at the start of the transaction.

  • Field: [TEC] inside the initialization command (Y19).
  • Value: Set in seconds (e.g., 060 for 60 seconds).
  • Behavior: If the user does not present a card within this window, the Pinpad aborts the operation and sends a Y0E with code 07 (Timeout).

Internal hardware timeouts

Certain cryptographic or hardware initialization events have hardcoded internal timeouts. If an internal process fails due to a hardware fault, the terminal typically returns a general error code.

Communication integrity (ACK/NAK)

Before the application logic processes a command, the low-level communication layer (SerialCom) validates message integrity.

  • <ACK> (06h): Sent if the message structure and LRC/CRC checksum are correct.
  • <NAK> (15h): Sent if the message is corrupted. You should immediately retry sending the last command.

Next steps

With your error handling logic in place, you can move toward the final stages of your integration:

  1. API Commands Dictionary: Refer to the full technical reference for every command and its possible error states.