Comandos de la API

Esta referencia define la estructura de bajo nivel de los paquetes de comunicación y las secuencias operativas necesarias para interactuar con el Pinpad de Getnet.

Estructura de los mensajes y protocolo

Cada mensaje transmitido por la interfaz serie sigue un protocolo de estructura estricto, con caracteres de control ASCII. Así se garantiza la integridad de los datos.

Estructura general de la trama

Todos los paquetes deben seguir el siguiente formato: <STX> [PAYLOAD] <ETX> {LRC}

Componente	Valor hex	Descripción
`<STX>`	`02h`	Inicio de texto: indica el comienzo de una trama de mensaje.
[PAYLOAD]	Variable	El comando propiamente dicho y sus parámetros.
`<ETX>`	`03h`	Fin de texto: indica el final del payload del mensaje.
{LRC}	Variable	Carácter de verificación: byte de Longitudinal Redundancy Check.

Delimitadores internos del payload

Dentro de la sección [PAYLOAD], los parámetros se separan con el carácter Separador de Archivos (<FS>) (1Ch).

Matriz operativa de comandos

Esta matriz relaciona cada operación lógica con la secuencia de comandos requerida entre el Sistema Host y el Pinpad.

Operación	Configuración	Acción	Captura de datos	Finalización
Pago estándar	`Y19`	`Y15`	`Y02` (Auto PP)	`Y03`
Cashback	`Y19` (TTY 09)	`Y15`	`Y02` (Auto PP)	`Y03`
Devolución	`Y19` (TTY 20)	—	`Y02` (Auto PP)	`Y03`
Pago con QR	—	`Y0Q`	—	`Y0Q` (Limpiar)
Prueba de eco	—	`Y0I`	—	—
Actualización (YDL)	`YDL` (Init)	`YDL` (Data)	—	`YDL` (End)

Definiciones principales del payload

Cada campo que aparece a continuación se separa con <FS> (1Ch) y se enmarca con <STX>/<ETX>/{LRC}, como se describió antes. La columna Attr usa: H (hexadecimal), N (numérico), A (alfabético), AN (alfanumérico), ANS (alfanumérico y caracteres especiales).

Y19 - Inicializar transacción

Es obligatorio para iniciar las operaciones con tarjeta. El Host envía la clave RSA, el importe y los parámetros de cifrado; el Pinpad devuelve los datos de la tarjeta (flujo contactless).

Solicitud Y19 (Host → Pinpad)

Campo	Longitud	Attr	Descripción
`RSA`	256–512	ANS	Clave pública RSA (módulo) usada para cifrar la Pista I. Consulte Cifrado del Pinpad.
`EXP`	1–12	ANS	Exponente RSA.
`TEC`	3	N	Tiempo de espera entre comandos, en segundos (`000`–`999`).
`ET1`	1	N	Enviar la Pista I (banda). Sin uso: el Pinpad ignora el valor.
`PTC`	1	N	Solicitar el tipo de cuenta (se usa habitualmente con tarjetas MAESTRO).
`PMK`	1	AN	Posición de la clave maestra (`0`–`9`, o `N`). PMK del PIN = valor; PMK del PAN = valor + 1.
`WRK`	1–16	ANS	Clave de trabajo.
`ENC`	1	N	Cifrado DUKPT del PAN: `0` desactivado, `1` activado, `2` activado usando la ranura 3.
`IMP`	12	N	Importe de la compra; los dos últimos dígitos son decimales.
`ICB`	12	N	Importe del cashback (`000000000000` si no se usa); los dos últimos dígitos son decimales.
`TTY`	2	N	Tipo de transacción. Consulte Tablas de Códigos.

Respuesta Y19 (Pinpad → Host) — Contactless

Campo	Longitud	Attr	Descripción
`TJA`	1–19	N	Número de tarjeta (los primeros 8 y los últimos 4 dígitos; el resto enmascarado con `*`). Proviene de la Pista II.
`CSE`	3	N	Código de servicio (de la Pista II); se envía en claro.
`CBC`	3	N	Código del banco. Sin uso: siempre `000`.
`NYA`	1–26	ANS	Nombre del titular de la tarjeta para el comprobante (Pista I o TAG 5F20); se completa con espacios a la derecha.
`REG`	6	N	Número de registro. Sin uso: `000041`.
`MDI`	1	A	Modo de entrada (`M`, `B`, `C`, `L`, `E`). Consulte Tablas de Códigos.
`VER`	1–15	ANS	Versión del software del Pinpad.
`FDV`	4	N	Fecha de vencimiento (`YYMM`), de la Pista II.
`TC2`	256–512	ANS	Pista II cifrada con la clave RSA de Y19. Proviene de la Pista II o del TAG 57.
`1NL`	1	N	Indicador de Pista I no leída: `0` leída, `1` no leída.
`NSF`	1–12	N	Número de serie físico del Pinpad.
`CPG`	1–300	ANS	Criptograma EMV (TLV). `N` si no aplica.
`CAU`	6	N	Código de autorización. Se devuelve como 6 espacios en blanco.
`CRE`	2	N	Código de respuesta del emisor (TAG 8A y resultado del SDK).
`NSP`	3	N	Número de secuencia del PAN (TAG 5F34).
`APN`	0–32	ANS	Nombre de la aplicación EMV seleccionada, en hexadecimal, para el comprobante (TAG 9F12 / TAG 50).
`AID`	0–16	ANS	Identificador de la aplicación EMV seleccionada (TAG 4F).
`KSN-PAN`	20	H	Key Serial Number del PAN cifrado con DUKPT.
`ENC-PAN`	1–256	ANS	Criptograma del PAN cifrado con DUKPT.
`TDC`	1	AN	Tipo de cuenta (MAESTRO). `N` para no imprimirlo.
`PIN`	16–32	ANS	PINBLOCK si se ingresó un PIN; en caso contrario se omite.
`KSN`	20	N	Key Serial Number del PIN DUKPT; se incrementa en cada operación EMV con PIN. Se omite si no hay PIN.

Y02 - Respuesta de datos adicionales

Lo genera el Pinpad después de leer una tarjeta. La solicitud puede actualizar importes y pedir datos de banda; la estructura de la respuesta depende del modo de entrada (BANDA o CHIP).

Solicitud Y02 (Host → Pinpad)

Campo	Longitud	Attr	Descripción
`U4D`	1	N	Solicitar los últimos 4 dígitos (solo banda).
`CDS`	1	N	Solicitar el código de seguridad (solo banda).
`ET1`	1	N	Enviar la Pista I (banda). Sin uso: se ignora el valor.
`SPI`	1	N	Solicitar el PIN (solo banda).
`PTC`	1	N	Solicitar el tipo de cuenta (habitualmente MAESTRO).
`PMK`	1	AN	Posición de la clave maestra (`0`–`9`, o `N`). PMK del PIN = valor; PMK del PAN = valor + 1.
`WRK`	1–16	ANS	Clave de trabajo (`N` si no se solicita PIN ni cifrado de pistas). Sin uso: se ignora el valor.
`ENC`	1	N	Cifrado DUKPT del PAN: `0` desactivado, `1` activado, `2` activado usando la ranura 3.
`IMP`	12	N	Importe de la compra; actualiza el valor de `Y19.IMP`.
`ICB`	12	N	Importe del cashback; actualiza el valor de `Y19.ICB`.

Respuesta Y02 (Pinpad → Host) — Banda magnética (BANDA)

Campo	Longitud	Attr	Descripción
`TJA`	1–19	N	Número de tarjeta (los primeros 8 y los últimos 4; el resto enmascarado con `*`). Proviene de la Pista II.
`FDV`	4	N	Fecha de vencimiento (`YYMM`), de la Pista II.
`TC1`	256–512	ANS	Pista I cifrada con la clave RSA de Y19 (banda).
`TC2`	256–512	ANS	Pista II cifrada con la clave RSA de Y19 (banda).
`1NL`	1	N	Indicador de Pista I no leída: `0` leída, `1` no leída.
`CDS`	1–4	N	Código de seguridad cifrado con la clave RSA de Y19 (ingresado por el usuario).
`NSF`	1–12	N	Número de serie físico del Pinpad.
`KSN-PAN`	20	H	Key Serial Number del PAN cifrado con DUKPT.
`ENC-PAN`	1–256	ANS	Criptograma del PAN cifrado con DUKPT.
`TDC`	1	AN	Tipo de cuenta (MAESTRO). `N` para no imprimirlo.
`PIN`	16–32	ANS	PINBLOCK si se ingresó un PIN; en caso contrario se omite.
`KSN`	20	N	Key Serial Number del PIN DUKPT; se incrementa en cada operación con PIN.

Respuesta Y02 (Pinpad → Host) — Chip (CHIP)

Campo	Longitud	Attr	Descripción
`TJA`	1–19	N	Número de tarjeta (los primeros 8 y los últimos 4; el resto enmascarado con `*`). Proviene de la Pista II.
`FDV`	4	N	Fecha de vencimiento (`YYMM`), de la Pista II.
`TC2`	256–512	ANS	Pista II cifrada con la clave RSA de Y19. Proviene del TAG 57 (chip).
`1NL`	1	N	Indicador de Pista I no leída: `0` leída, `1` no leída.
`NSF`	1–12	N	Número de serie físico del Pinpad.
`CPG`	1–300	ANS	Criptograma EMV (formato TLV). `N` si no se envía información.
`CAU`	6	N	Código de autorización. Se devuelve como 6 espacios en blanco.
`CRE`	2	N	Código de respuesta del emisor.
`NSP`	3	N	Número de secuencia del PAN (TAG 5F34).
`APN`	0–32	ANS	Nombre de la aplicación EMV seleccionada, en hexadecimal, para el comprobante (TAG 9F12 / TAG 50).
`AID`	0–16	ANS	Identificador de la aplicación EMV seleccionada (TAG 4F).
`KSN-PAN`	20	H	Key Serial Number del PAN cifrado con DUKPT.
`ENC-PAN`	1–256	ANS	Criptograma del PAN cifrado con DUKPT.
`TDC`	1	AN	Tipo de cuenta (MAESTRO). `N` para no imprimirlo.
`PVF`	1	N	Indicador de PIN offline verificado por la tarjeta. Debe ser `0` para PIN online.
`PIN`	16–32	ANS	PINBLOCK si se ingresó un PIN; en caso contrario se omite.
`KSN`	20	N	Key Serial Number del PIN DUKPT; se incrementa en cada operación EMV con PIN.

Y03 - Autorización del Host

La instrucción final que el Host envía para completar el flujo.

Campos clave [Host]:

[CAU]: código de autorización del emisor.
[CRE]: código de respuesta (por ejemplo, “00” para éxito).

Manejo de errores (Y0E)

Si una operación falla, el terminal devuelve un reporte Y0E en lugar de la respuesta esperada de la secuencia.

Código	Mensaje	Descripción
01	CANCELADO	Cancelación iniciada por el usuario o el Host.
04	ERROR EMV	Fallo de lectura del chip o de protocolo.
08	SIN LLAVES	Faltan las claves DUKPT en la ranura 3.