API Commands

This reference defines the low-level structure of the communication packets and the operational sequences required to interact with the Getnet Pinpad.

Message framing and protocol

Every message transmitted over the serial interface follows a strict framing protocol using ASCII control characters to ensure data integrity.

General frame structure

All packets must adhere to the following format: <STX> [PAYLOAD] <ETX> {LRC}

Component	Hex Value	Description
`<STX>`	`02h`	Start of Text: Indicates the beginning of a message frame.
[PAYLOAD]	Variable	The actual command and its parameters.
`<ETX>`	`03h`	End of Text: Indicates the end of the message payload.
{LRC}	Variable	Check Character: Longitudinal Redundancy Check byte.

Internal payload delimiters

Within the [PAYLOAD] section, multiple parameters are separated by the File Separator (<FS>) character (1Ch).

Command operational matrix

This matrix maps specific logical operations to the required command sequence between the Host System and the Pinpad.

Operation	Setup	Action	Data Capture	Finalization
Standard Payment	`Y19`	`Y15`	`Y02` (Auto PP)	`Y03`
Cashback	`Y19` (TTY 09)	`Y15`	`Y02` (Auto PP)	`Y03`
Refund	`Y19` (TTY 20)	—	`Y02` (Auto PP)	`Y03`
QR Payment	—	`Y0Q`	—	`Y0Q` (Clear)
Echo Test	—	`Y0I`	—	—
Update (YDL)	`YDL` (Init)	`YDL` (Data)	—	`YDL` (End)

Core payload definitions

Each field below is separated by <FS> (1Ch) and framed by <STX>/<ETX>/{LRC} as described above. The Attr column uses: H (hexadecimal), N (numeric), A (alpha), AN (alphanumeric), ANS (alphanumeric and special characters).

Y19 - Initialize transaction

Mandatory for starting card-based operations. The Host sends the RSA key, amount, and encryption parameters; the Pinpad returns the card data (contactless flow).

Y19 Request (Host → Pinpad)

Field	Length	Attr	Description
`RSA`	256–512	ANS	RSA public key (modulus) used to encrypt Track 1. See Pinpad Encryption.
`EXP`	1–12	ANS	RSA exponent.
`TEC`	3	N	Inter-command timeout in seconds (`000`–`999`).
`ET1`	1	N	Send Track 1 (stripe). Unused: the value is ignored by the Pinpad.
`PTC`	1	N	Request account type (commonly used for MAESTRO cards).
`PMK`	1	AN	Master key position (`0`–`9`, or `N`). PIN PMK = value; PAN PMK = value + 1.
`WRK`	1–16	ANS	Working key.
`ENC`	1	N	PAN DUKPT encryption: `0` off, `1` on, `2` on using slot 3.
`IMP`	12	N	Purchase amount; the last two digits are decimals.
`ICB`	12	N	Cashback amount (`000000000000` if not used); the last two digits are decimals.
`TTY`	2	N	Transaction type. See Code Tables.

Y19 Response (Pinpad → Host) — Contactless

Field	Length	Attr	Description
`TJA`	1–19	N	Card number (first 8 and last 4 digits; the rest masked with `*`). From Track II.
`CSE`	3	N	Service code (from Track II); sent in clear.
`CBC`	3	N	Bank code. Unused: always `000`.
`NYA`	1–26	ANS	Cardholder name for the receipt (Track I or TAG 5F20); right-padded with spaces.
`REG`	6	N	Record number. Unused: `000041`.
`MDI`	1	A	Entry mode (`M`, `B`, `C`, `L`, `E`). See Code Tables.
`VER`	1–15	ANS	Pinpad software version.
`FDV`	4	N	Expiration date (`YYMM`), from Track II.
`TC2`	256–512	ANS	Track II encrypted with the Y19 RSA key. From Track II or TAG 57.
`1NL`	1	N	Track I not-read indicator: `0` read, `1` not read.
`NSF`	1–12	N	Pinpad physical serial number.
`CPG`	1–300	ANS	EMV cryptogram (TLV). `N` if not applicable.
`CAU`	6	N	Authorization code. Returned as 6 blank spaces.
`CRE`	2	N	Issuer response code (TAG 8A and SDK result).
`NSP`	3	N	PAN sequence number (TAG 5F34).
`APN`	0–32	ANS	Selected EMV application name in hex, for the receipt (TAG 9F12 / TAG 50).
`AID`	0–16	ANS	Selected EMV application identifier (TAG 4F).
`KSN-PAN`	20	H	Key Serial Number for the DUKPT-encrypted PAN.
`ENC-PAN`	1–256	ANS	DUKPT-encrypted PAN cryptogram.
`TDC`	1	AN	Account type (MAESTRO). `N` to avoid printing.
`PIN`	16–32	ANS	PINBLOCK if a PIN was entered; otherwise omitted.
`KSN`	20	N	Key Serial Number for the DUKPT PIN; increments per EMV operation with PIN. Omitted if no PIN.

Y02 - Additional data response

Generated by the Pinpad after a card is read. The request can update amounts and request stripe data; the response structure depends on the entry mode (BANDA or CHIP).

Y02 Request (Host → Pinpad)

Field	Length	Attr	Description
`U4D`	1	N	Request last 4 digits (stripe only).
`CDS`	1	N	Request security code (stripe only).
`ET1`	1	N	Send Track 1 (stripe). Unused: the value is ignored.
`SPI`	1	N	Request PIN (stripe only).
`PTC`	1	N	Request account type (commonly MAESTRO).
`PMK`	1	AN	Master key position (`0`–`9`, or `N`). PIN PMK = value; PAN PMK = value + 1.
`WRK`	1–16	ANS	Working key (`N` if not requesting PIN or track encryption). Unused: the value is ignored.
`ENC`	1	N	PAN DUKPT encryption: `0` off, `1` on, `2` on using slot 3.
`IMP`	12	N	Purchase amount; updates the value from `Y19.IMP`.
`ICB`	12	N	Cashback amount; updates the value from `Y19.ICB`.

Y02 Response (Pinpad → Host) — Magnetic Stripe (BANDA)

Field	Length	Attr	Description
`TJA`	1–19	N	Card number (first 8 and last 4; the rest masked with `*`). From Track II.
`FDV`	4	N	Expiration date (`YYMM`), from Track II.
`TC1`	256–512	ANS	Track I encrypted with the Y19 RSA key (stripe).
`TC2`	256–512	ANS	Track II encrypted with the Y19 RSA key (stripe).
`1NL`	1	N	Track I not-read indicator: `0` read, `1` not read.
`CDS`	1–4	N	Security code encrypted with the Y19 RSA key (user-entered).
`NSF`	1–12	N	Pinpad physical serial number.
`KSN-PAN`	20	H	Key Serial Number for the DUKPT-encrypted PAN.
`ENC-PAN`	1–256	ANS	DUKPT-encrypted PAN cryptogram.
`TDC`	1	AN	Account type (MAESTRO). `N` to avoid printing.
`PIN`	16–32	ANS	PINBLOCK if a PIN was entered; otherwise omitted.
`KSN`	20	N	Key Serial Number for the DUKPT PIN; increments per PIN operation.

Y02 Response (Pinpad → Host) — Chip (CHIP)

Field	Length	Attr	Description
`TJA`	1–19	N	Card number (first 8 and last 4; the rest masked with `*`). From Track II.
`FDV`	4	N	Expiration date (`YYMM`), from Track II.
`TC2`	256–512	ANS	Track II encrypted with the Y19 RSA key. From TAG 57 (chip).
`1NL`	1	N	Track I not-read indicator: `0` read, `1` not read.
`NSF`	1–12	N	Pinpad physical serial number.
`CPG`	1–300	ANS	EMV cryptogram (TLV format). `N` if no information is sent.
`CAU`	6	N	Authorization code. Returned as 6 blank spaces.
`CRE`	2	N	Issuer response code.
`NSP`	3	N	PAN sequence number (TAG 5F34).
`APN`	0–32	ANS	Selected EMV application name in hex, for the receipt (TAG 9F12 / TAG 50).
`AID`	0–16	ANS	Selected EMV application identifier (TAG 4F).
`KSN-PAN`	20	H	Key Serial Number for the DUKPT-encrypted PAN.
`ENC-PAN`	1–256	ANS	DUKPT-encrypted PAN cryptogram.
`TDC`	1	AN	Account type (MAESTRO). `N` to avoid printing.
`PVF`	1	N	Offline PIN verified-by-card indicator. Must be `0` for Online PIN.
`PIN`	16–32	ANS	PINBLOCK if a PIN was entered; otherwise omitted.
`KSN`	20	N	Key Serial Number for the DUKPT PIN; increments per EMV operation with PIN.

Y03 - Host authorization

The final instruction sent by the Host to complete the flow.

Key Fields [Host]:

[CAU]: Authorization code from the issuer.
[CRE]: Response code (e.g., “00” for success).

Error handling (Y0E)

If an operation fails, the terminal returns a Y0E report instead of the expected sequence response.

Code	Message	Description
01	CANCELADO	User or Host-initiated cancellation.
04	ERROR EMV	Chip reading or protocol failure.
08	SIN LLAVES	Missing DUKPT keys in Slot 3.