# Terminal Requirements for Card Present

This reference document outlines the technical requirements for integrating a physical hardware terminal with the **Getnet Regional API** for **Card Present (CP)** transactions. Before submitting any payment request, your terminal must meet these specifications to ensure successful authorization and compliance.

## Overview

Every Card Present transaction in the Regional API is tied to a specific, registered physical device. The gateway uses the terminal's identity to enforce security policies, apply regional tax rules, and enable per-device reconciliation. A request that is missing or has an invalid terminal configuration will be rejected.

## API Request Requirements

### Mandatory Header

All Card Present payment requests must include the following HTTP header:

| Header | Value | Description |
| --- | --- | --- |
| `x-transaction-channel-entry` | `XX` | Identifies the platform sending the transaction. This code is assigned by Getnet and must be requested from the Integration Support team. |

<Callout type="warning">

This header is mandatory for all hardware-integrated transactions.

</Callout>

### Mandatory `terminal` Object

The `terminal` object must be included inside `data.payment` for every Card Present request. It identifies the specific registered physical device processing the transaction.

```json
"data": {
  "payment": {
    "terminal": {
      "terminal_number": "21000334"
    }
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `terminal_number` | `string` | **Yes** | The unique identifier of the registered physical terminal. Provided by Getnet during device onboarding. |

<Callout type="note">

The `terminal` object is a **mandatory object for Card Present** as defined in the API schema. A request without a valid `terminal_number` will be rejected.

</Callout>

## Hardware Capabilities

Your physical terminal must support the following capabilities to process Card Present transactions through the Regional API:

### Card Entry Modes

The terminal must be capable of reading at least one of the following entry modes, which determines the data payload sent to the API:

| Entry Mode (`entry_mode`) | Hardware Requirement | Primary Data Field |
| --- | --- | --- |
| `chip` | ICC (Integrated Circuit Card) slot reader | `emv` (TLV string) |
| `chip_contactless` | NFC (Near Field Communication) reader | `emv` (TLV string) |
| `magnetic_stripe` | Magnetic stripe head reader | `track_2` |

### Cardholder Verification Methods (CVM)

The terminal must support at least one of the following verification methods, which determines the additional security fields required in the request:

| CVM (`cardholder_verification_method`) | Hardware Requirement | Additional Fields Required |
| --- | --- | --- |
| `online_pin` | Secure PIN pad with DUKPT encryption | `pin_block`, `ksn` |
| `offline_pin` | ICC chip local verification | None (handled by card) |
| `signature` | Screen or paper receipt | None (merchant stores signature) |
| `no_cvm` | None (low-value contactless) | None |

### EMV Chip Processing

For `chip` and `chip_contactless` entry modes, the terminal must:

- **Read and parse TLV data** from the card's Integrated Circuit (IC).
- **Generate an Application Cryptogram (ARQC)** for each transaction.
- **Concatenate all EMV tags** into a single hex-encoded string for the `emv` field.
- **Provide the Application Identifier (AID)** in the `aid` field.

### PIN Encryption (DUKPT)

For `online_pin` transactions, the terminal's PIN pad must:

- **Encrypt the PIN** using the **DUKPT (Derived Unique Key Per Transaction)** management scheme.
- **Generate a PIN Block** in **ISO 9564-1 Format 0 (ISO-0)** format.
- **Provide the KSN** (Key Serial Number) — a 20-digit hexadecimal string — to allow the Getnet HSM to derive the correct decryption key.

| Field | Format | Example |
| --- | --- | --- |
| `pin_block` | Hex-encoded string | `A0B6BA8D53C8D3C3` |
| `ksn` | 20-digit hex string | `BC756011020000400001` |

## Connectivity Requirements

Your terminal must be able to reach the Getnet Regional API endpoints over HTTPS. The following base URLs apply:

| Environment | Base URL |
| --- | --- |
| **Sandbox** | `https://api-sbx.pre.globalgetnet.com` |
| **Production** | `https://api.pre.globalgetnet.com` |

### Network Topologies

The Regional API supports two primary integration topologies:

| Topology | Description |
| --- | --- |
| **Direct Integration** | The terminal firmware acts as the API client, handling OAuth 2.0 authentication and JSON construction directly. |
| **Merchant Host** | The terminal captures hardware data (EMV, Track 2, PIN Block) and forwards it to a merchant backend server, which then constructs and sends the API request. |

## Terminal Registration

Before processing live transactions, your terminal must be registered with Getnet. Contact the Integration Support team to:

1. Obtain a valid `terminal_number` for each physical device.
2. Request the `x-transaction-channel-entry` code for your integration platform.
3. Configure DUKPT key injection for PIN-enabled terminals.

## Mandatory Fields Summary

The following table consolidates all mandatory fields for a Card Present payment request:

| Field / Header | Location | Required For |
| --- | --- | --- |
| `x-transaction-channel-entry: XX` | HTTP Header | All CP transactions |
| `data.payment.terminal.terminal_number` | Request Body | All CP transactions |
| `data.payment.card.entry_mode` | Request Body | All CP transactions |
| `data.payment.card.emv` | Request Body | `chip`, `chip_contactless` |
| `data.payment.card.aid` | Request Body | `chip`, `chip_contactless` |
| `data.payment.card.track_2` | Request Body | `magnetic_stripe` (and often `chip`) |
| `data.payment.card.pin_block` | Request Body | `online_pin` CVM |
| `data.payment.card.ksn` | Request Body | `online_pin` CVM |
| `data.payment.card.seq_number` | Request Body | `chip` with `online_pin` |

## Read More

- **[Card Entry Modes](/en/global-api/sep-card-present/core-concepts-cp/card-entry-modes-cp)**: Detailed breakdown of `chip`, `chip_contactless`, and `magnetic_stripe` payloads.
- **[PIN Validation](/en/global-api/sep-card-present/core-concepts-cp/pin-validation)**: Technical requirements for `pin_block` and `ksn` transmission.
- **[EMV Tags Specifications](/en/global-api/reference-global/emv-tags)**: Reference for all TLV tags included in the `emv` field.
- **[Quickstart Guide](/en/global-api/sep-card-present/first-steps-cp/card-present-quickstart)**: Create your first Card Present payment in Sandbox.
- **[Single-Step Payments](/en/global-api/sep-card-present/payment-guides-cp/single-step-payment-cp)**: Full guide to immediate sale-and-capture flows.