Procesar pagos con QR Code

Esta guía explica cómo usar la pantalla del terminal para mostrar QR Codes dinámicos en flujos de pago con carteras digitales mediante el comando Y0Q.

Cómo funciona

A diferencia de los pagos con tarjeta, donde el terminal lee los datos de un medio físico, una transacción QR invierte el flujo. El terminal muestra los datos del pago (la cadena del QR Code) y el dispositivo móvil del usuario la escanea.

Omisión de EMV: el flujo QR no usa la secuencia de inicialización estándar Y19/Y15 porque omite por completo el kernel EMV.
Renderizado dinámico: el terminal recibe del Sistema Host una cadena de datos alfanuméricos en bruto y renderiza la matriz QR 2D en la pantalla.
Visibilidad del importe: si la cadena de datos del QR contiene el Tag 54 (Importe), el Pinpad agrega automáticamente el símbolo ”$” y muestra el importe en la pantalla.

Todo el flujo se gestiona mediante el comando Y0Q. Mientras se muestra el QR, el Pinpad bloquea otros intentos de transacción e ignora cualquier comando distinto del comando de cancelación Y06.

Paso 1: Renderizar el QR Code (solicitud Y0Q)

El Sistema Host reúne los datos del destino del pago (por ejemplo, una cadena de cartera) y los envía directamente al Pinpad.

Campo	Atributo	Descripción
[CID]	3 ANS	Identificador del comando: “Y0Q”.
[TDP]	2 N	Tipo de pantalla: define qué estado de la interfaz se debe mostrar.
[TO]	3 N	Tiempo de espera: tiempo de exposición del QR en segundos (por ejemplo, “060”).
[QRD]	1..512 ANS	Datos del QR: la cadena alfanumérica que se codificará en la matriz.

Tabla de TDP (tipos de pantalla)

El campo TDP permite al Sistema Host alternar entre tres estados específicos de la interfaz:

Valor	Descripción
“01”	Mostrar QR: renderiza la imagen del QR y el importe opcional.
“02”	Procesando: muestra “Procesando información”.
“03”	Inactivo: devuelve el terminal a su estado base de espera.

Paso 2: Validar la visualización (respuesta Y0Q)

El Pinpad devuelve un ACK inmediatamente después de validar y analizar el comando. Luego, la capa de interfaz genera la matriz QR y la muestra en la pantalla.

Paso 3: Gestionar los cambios de estado (opcional)

Si el Sistema Host necesita informar el progreso (por ejemplo, “Procesando información”), primero debe enviar un comando Y06 para detener la exposición del QR y luego enviar un nuevo comando Y0Q con TDP en “02”.

Finalizar o cancelar

La transacción financiera ocurre entre el dispositivo del usuario y el proveedor de la cartera, por lo que el Pinpad no sabe automáticamente cuándo se completa el pago. El Sistema Host debe consultar el estado en su propia autorizadora.

Finalización por el Host: una vez confirmado el pago, el Sistema Host debe enviar un comando Y06 o un comando Y0Q con TDP en “03” para limpiar la pantalla y volver a IDLE.
Cancelación automática: si el usuario cancela la acción en el dispositivo o se alcanza el tiempo de espera, el Pinpad devuelve una respuesta Y0Q con un código de estado ([STS]):
“0”: cancelado por el usuario.
“1”: cancelado por tiempo de espera.

Referencia de implementación (Kotlin)

La siguiente lógica define cómo se procesa y renderiza el comando Y0Q dentro de la aplicación.

Gestión y análisis de comandos

La clase CommandY0Q se encarga de analizar los campos recibidos, mientras que handleCommandY0Q activa la lógica de visualización de la interfaz.

/**
 * This class represents a Y0Q command with functionality to parse 
 * and manage the received command fields. It extracts the content 
 * to be displayed in the QR (QRD).
 */
class CommandY0Q(rawCmd: String?) : Command()

/**
 * Handles the Y0Q command, "Display QR".
 * This method parses and displays a QR on the terminal screen.
 */
private fun handleCommandY0Q(inCmd: String?)

Generación de la matriz QR

El Pinpad usa la biblioteca ZXing para codificar la cadena alfanumérica en un mapa de bits de matriz 2D.

/**
 * Generate QR codes using the ZXing library.
 * Uses `BarcodeEncoder` to encode content into a QR code bitmap.
 */
object QrGeneration { ... }

Ejemplo de comunicación

Este ejemplo muestra el flujo para exhibir un QR Code con un importe de $200,30 y una posterior cancelación manual desde el Host.

El siguiente bloque de código muestra la solicitud del Host para exhibir el QR (Tag 54 = 200.3):

[SP] <STX>Y0Q<FS>010<FS>00020101021230230019ar.com.globalgetnet...5405200.3...<FS><ETX>a

El Pinpad valida y muestra:

[PP] <ACK>

Si el host aborta la exposición del QR:

[SP] <STX>Y06060<ETX>j

En ese caso, el Pinpad confirma la cancelación:

[PP] <ACK>

Siguientes pasos

Con los pagos con QR Code implementados, puede completar su integración revisando:

Cancelaciones y devoluciones: aprenda cómo interactúa el comando Y06 con las sesiones QR activas.
Comandos de la API: consulte la referencia técnica completa de cada campo del payload Y0Q.