# Requisitos del terminal para Tarjeta Presente

Este documento de referencia describe los requisitos técnicos para integrar un terminal de hardware físico con la **Getnet Regional API** para transacciones **Tarjeta Presente**. Antes de enviar cualquier solicitud de pago, su terminal debe cumplir estas especificaciones para garantizar el éxito de la autorización y el cumplimiento de la normativa.

## Visión general

Cada transacción Tarjeta Presente en la Regional API está vinculada a un dispositivo físico específico y registrado. La pasarela (gateway) utiliza la identidad del terminal para aplicar políticas de seguridad, aplicar reglas fiscales regionales y permitir la conciliación por dispositivo. Cualquier solicitud a la que le falte la configuración del terminal o que esta sea incorrecta será rechazada.

## Requisitos de las solicitudes a la API

### Cabecera obligatoria

Todas las solicitudes de pago de Tarjeta Presente deben incluir la siguiente cabecera HTTP:

| Cabecera | Valor | Descripción |
| --- | --- | --- |
| `x-transaction-channel-entry` | `XX` | Identifica la plataforma que envía la transacción. Este código es asignado por Getnet y debe solicitarse al equipo de Soporte a la Integración. |

<Callout type="warning">

Esta cabecera es obligatoria para todas las transacciones integradas en el hardware.

</Callout>

### Objeto `terminal` obligatorio

El objeto `terminal` debe incluirse dentro de `data.payment` en cada solicitud de Tarjeta Presente. Identifica el dispositivo físico registrado específico que procesa la transacción.

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

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `terminal_number` | `string` | **Sí** | El identificador único del terminal físico registrado. Proporcionado por Getnet durante el alta del dispositivo. |

<Callout type="note">

El objeto `terminal` es un **objeto obligatorio para Tarjeta Presente**, tal como se define en el esquema de la API. Se rechazará cualquier solicitud que no contenga un `terminal_number` válido.

</Callout>

## Capacidades del hardware

Su terminal físico debe admitir las siguientes capacidades para procesar transacciones de Tarjeta Presente a través de la Regional API:

### Modos de entrada de tarjeta

El terminal debe ser capaz de leer al menos uno de los siguientes modos de entrada, que determina la carga de datos enviada a la API:

| Modo de entrada (`entry_mode`) | Requisito de hardware | Campo de datos principal |
| --- | --- | --- |
| `chip` | Lector de ranura ICC (Integrated Circuit Card) | `emv` (cadena TLV) |
| `chip_contactless` | Lector NFC (Near Field Communication) | `emv` (cadena TLV) |
| `magnetic_stripe` | Lector de cabezal de banda magnética | `track_2` |

### Métodos de verificación del titular (CVM)

El terminal debe admitir al menos uno de los siguientes métodos de verificación, que determina los campos de seguridad adicionales necesarios en la solicitud:

| CVM (`cardholder_verification_method`) | Requisito de hardware | Campos adicionales necesarios |
| --- | --- | --- |
| `online_pin` | Teclado PIN seguro con cifrado DUKPT | `pin_block`, `ksn` |
| `offline_pin` | Verificación local del chip ICC | Ninguno (gestionado por la tarjeta) |
| `signature` | Pantalla o recibo de papel | Ninguno (el comercio guarda la firma) |
| `no_cvm` | Ninguno (sin contacto de bajo valor) | Ninguno |

### Procesamiento de chip EMV

Para los modos de entrada `chip` y `chip_contactless`, el terminal debe:

- **Leer y analizar los datos TLV** del circuito integrado (IC) de la tarjeta.
- **Generar un criptograma de aplicación (ARQC)** para cada transacción.
- **Concatenar todas las etiquetas EMV** en una única cadena codificada en hexadecimal para el campo `emv`.
- **Proporcionar el Identificador de Aplicación (AID)** en el campo `aid`.

### Cifrado de PIN (DUKPT)

Para las transacciones de `online_pin`, el teclado de PIN del terminal debe:

- **Cifrar el PIN** utilizando el esquema de gestión **DUKPT (Derived Unique Key Per Transaction)**.
- **Generar un bloque de PIN** en formato **ISO 9564-1 Formato 0 (ISO-0)**.
- **Proporcionar el KSN** (Key Serial Number) —una cadena hexadecimal de 20 dígitos— para permitir que el HSM de Getnet obtenga la clave de descifrado correcta.

| Campo | Formato | Ejemplo |
| --- | --- | --- |
| `pin_block` | Cadena codificada en hex | `A0B6BA8D53C8D3C3` |
| `ksn` | Cadena hex de 20 dígitos | `BC756011020000400001` |

## Requisitos de conectividad

Su terminal debe poder conectarse a los puntos de enlace de la Getnet Regional API a través de HTTPS. Se aplican las siguientes URL base:

| Entorno | URL base |
| --- | --- |
| **Sandbox** | `https://api-sbx.pre.globalgetnet.com` |
| **Producción** | `https://api.pre.globalgetnet.com` |

### Topologías de red

La Regional API admite dos topologías de integración principales:

| Topología | Descripción |
| --- | --- |
| **Integración directa** | El firmware del terminal actúa como cliente de la API, gestionando directamente la autenticación OAuth 2.0 y la construcción del JSON. |
| **Host del comercio** | El terminal captura los datos del hardware (EMV, banda, bloque de PIN) y los envía a un servidor backend del comercio, que construye y envía la solicitud a la API. |

## Registro de terminales

Antes de procesar transacciones reales, su terminal debe estar registrado en Getnet. Póngase en contacto con el equipo de Soporte a la Integración para:

1. Obtener un `terminal_number` válido para cada dispositivo físico.
2. Solicitar el código `x-transaction-channel-entry` para su plataforma de integración.
3. Configurar la inyección de claves DUKPT para los terminales habilitados para PIN.

## Resumen de campos obligatorios

La siguiente tabla consolida todos los campos obligatorios para una solicitud de pago de Tarjeta Presente:

| Campo / Cabecera | Ubicación | Obligatorio para |
| --- | --- | --- |
| `x-transaction-channel-entry: XX` | Cabecera HTTP | Todas las transacciones de |
| `data.payment.terminal.terminal_number` | Cuerpo de la solicitud | Todas las transacciones de |
| `data.payment.card.entry_mode` | Cuerpo de la solicitud | Todas las transacciones de |
| `data.payment.card.emv` | Cuerpo de la solicitud | `chip`, `chip_contactless` |
| `data.payment.card.aid` | Cuerpo de la solicitud | `chip`, `chip_contactless` |
| `data.payment.card.track_2` | Cuerpo de la solicitud | `magnetic_stripe` (y a menudo `chip`) |
| `data.payment.card.pin_block` | Cuerpo de la solicitud | CVM `online_pin` |
| `data.payment.card.ksn` | Cuerpo de la solicitud | CVM `online_pin` |
| `data.payment.card.seq_number` | Cuerpo de la solicitud | `chip` con `online_pin` |

## Leer más

- **Modos de entrada de tarjeta**: Desglose detallado de las cargas de datos de `chip`, `chip_contactless` y `magnetic_stripe`.
- **Validación de PIN**: Requisitos técnicos para la transmisión de `pin_block` y `ksn`.
- **[Especificaciones de EMV Tags](/es/global-api/reference-global/emv-tags)**: Referencia de todas las etiquetas TLV incluidas en el campo `emv`.
- **Guía de inicio rápido**: Cree su primer pago Tarjeta Presente en el Sandbox.
- **Pagos de un solo paso**: Guía completa de los flujos inmediatos de venta y captura.