# PIN Validation

In the **Card Present (CP)** ecosystem, the Personal Identification Number (PIN) serves as the most secure **Cardholder Verification Method (CVM)**. Unlike the static CVV used in e-commerce, a PIN interaction involves a sophisticated cryptographic handshake between the hardware terminal, the card's chip, and the issuer's authorization system to ensure that sensitive data is never transmitted in "clear text".

## Online vs. Offline PIN Validation

The **Regional API** supports two distinct methods for validating a customer's PIN, determined by the card's configuration and the terminal's capabilities.

### Offline PIN Validation

The PIN is validated locally by the secure chip on the card itself.

- **Process**: The customer enters their PIN on the terminal, and the terminal sends it directly to the card's Integrated Circuit (IC) for comparison.
- **Benefit**: Allows for verification even if the terminal is temporarily offline or in a low connectivity environment.
- **API Impact**: In your request, `cardholder_verification_method` is set to `offline_pin`, and because verification happened locally, the `pin_block` is typically not sent to the gateway.

### Online PIN Validation

The PIN is encrypted by the hardware and sent to the card issuer for real time verification.

- **Process**: The terminal encrypts the PIN using a unique transaction key and packages it into a **PIN Block**.
- **Security**: Utilizes **DUKPT** (Derived Unique Key Per Transaction) to ensure that even if one transaction's key is compromised, all other transactions remain secure.
- **API Impact**: This method requires the transmission of both the **`pin_block`** and the **`ksn`** (Key Serial Number) in the API payload.

## The Components of Secure Online PIN

When implementing **Online PIN**, your hardware integration must provide three critical cryptographic elements to the Regional API:

### PIN Block

A secure, encrypted data structure (typically 8 bytes for TDES or 16 bytes for AES) that carries the PIN. Most implementations use the **ISO 9564-1 Format 0** (ISO-0), which XORs the customer's PIN with the last 12 digits of their card number (PAN) to ensure the resulting block is unique to that specific card.

### KSN (Key Serial Number)

A 20 digit hexadecimal identifier that acts as the "map" for the gateway to decrypt the PIN. It is composed of a base key ID, a device identifier, and a transaction counter.

- **Function**: The KSN allows the Getnet HSM (Hardware Security Module) to derive the exact **Working Key** used by the terminal for that specific transaction.

### DUKPT Encryption

The **Derived Unique Key Per Transaction** (DUKPT) management scheme ensures that the terminal generates a new, non reusable encryption key for every single card read. This prevents "replay attacks" and ensures end-to-end security from the physical PIN pad to the Getnet gateway.

## Technical Mapping in the Regional API

For any transaction where `cardholder_verification_method` is set to `online_pin`, the following fields in the `card` object are mandatory:

```json
"card": {
  "entry_mode": "chip",
  "cardholder_verification_method": "online_pin",
  "pin_block": "A0B6BA8D53C8D3C3",
  "ksn": "BC756011020000400001",
  "emv": "9f2701809f3303e0f8c8950580000080..."
}
```

| Field | Requirement | Description |
| --- | --- | --- |
| **`cardholder_verification_method`** | Mandatory | Set to `online_pin`. |
| **`pin_block`** | Mandatory | The hexencoded encrypted PIN data. |
| **`ksn`** | Mandatory | The 20 digit hex key serial number. |

## Read More

- **[Card Entry Modes](/en/global-api/sep-card-present/core-concepts-cp/card-entry-modes-cp)**: Understand the difference between `chip`, `chip_contactless`, and `magnetic_stripe` payloads.
- **[EMV Technology Overview](/en/global-api/sep-card-present/core-concepts-cp/emv-technology)**: Deep dive into TLV tags and chip cryptograms.
- **[Single-Step Payments](/en/global-api/sep-card-present/payment-guides-cp/single-step-payment-cp)**: Learn how to execute a full sale with PIN verification.