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.

This header is mandatory for all hardware-integrated transactions.

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.

"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.

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.

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:

Obtain a valid terminal_number for each physical device.
Request the x-transaction-channel-entry code for your integration platform.
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`

Card Entry Modes: Detailed breakdown of chip, chip_contactless, and magnetic_stripe payloads.
PIN Validation: Technical requirements for pin_block and ksn transmission.
EMV Tags Specifications: Reference for all TLV tags included in the emv field.
Quickstart Guide: Create your first Card Present payment in Sandbox.
Single-Step Payments: Full guide to immediate sale-and-capture flows.