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.

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

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.

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

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.

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:

Obtener un terminal_number válido para cada dispositivo físico.
Solicitar el código x-transaction-channel-entry para su plataforma de integración.
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: 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.