# 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](https://docs.globalgetnet.com/en/products/in-store-payments/host-to-host?doc=h2h-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](/en/host-to-host/reference-h2h/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](/en/host-to-host/reference-h2h/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.        |