Pago con QR Code

Esta guía explica cómo realizar pagos con QR Code en un TPV Integrado. Los pagos con QR Code usan la misma operación Sale con SaleType configurado como QR Code; su comportamiento es idéntico en conexiones USB y de red.

¿Qué es un pago con QR Code?

Un pago con QR Code es una venta en la que el cliente escanea un QR Code que se muestra en el TPV con una billetera o app compatible. El sistema de automatización envía una solicitud Sale con SaleType configurado como QR code (o el enum equivalente). El terminal muestra el QR Code y espera a que el cliente escanee y apruebe; luego devuelve la misma estructura de respuesta que una venta con tarjeta, con los campos específicos de tarjeta omitidos o nulos.

El método de pago con QR Code no admite propinas. Las cuotas para QR las gestiona la billetera del titular de la tarjeta. No envíes Installments, PlanId, Interest, OperationMode ni Tip en ventas con QR Code: si los envías, se ignoran.

Antes de comenzar

Antes de realizar un pago con QR Code:

Debes crear y validar un Connector con Polling
El Modo TPV Integrado debe estar activo
El terminal debe admitir pagos con QR Code

Paso 1: Inicia un pago con QR Code

Para iniciar un pago con QR Code, llama a la operación Sale con el parámetro SaleType configurado como QrCode.

Parámetros para una venta con QR Code

Parámetro	Tipo	Obligatorio	Descripción
`Amount`	Long	No	Importe de la transacción en moneda local (por ejemplo, `7500` = 75,00). Si se omite, el TPV solicita el importe.
`SaleType`	Enum	No	Configúralo como `QrCode` (o el enum/entero equivalente). Si se omite, el terminal muestra la pantalla de selección del tipo de pago.
`PrintOnPos`	Bool	No	Indica si el TPV debe imprimir un recibo cuando corresponda. El comportamiento puede variar según el flujo de la billetera.
`EmployeeId`	Int	No	Identificación opcional del operador.
`SkipReceipt`	Bool	No	Si es `true`, omite la pantalla de recibo del cliente cuando corresponda.
`CallerId`	String	No	ID generado por el sistema de automatización, usado para consultar la transacción más tarde con Check Status. Sin caracteres especiales ni Unicode.

Como se menciona en la descripción general, las ventas con QR Code no admiten parámetros de cuotas ni de propina. Omítelos.

Ejemplo: solicitud de venta con QR Code

El siguiente ejemplo muestra cómo llamar a un pago con QR Code:

var saleRequest = new SaleRequest
{
    Amount = 7500,                    // 75.00 in local currency
    SaleType = SaleType.QrCode,
    PrintOnPos = true,
    SkipReceipt = false
};

var saleResult = await connector.SaleAsync(saleRequest);

Una vez enviada la solicitud, el TPV procesa la entrada y muestra el QR Code en pantalla para que el cliente lo escanee.

Paso 2: Interacción del cliente

El cliente escanea el QR Code con una aplicación de pago (billetera) compatible. Luego el TPV espera la confirmación del pago desde la billetera.

El TPV gestiona el tiempo de espera y el comportamiento de cancelación. La operación se puede cancelar solo hasta que el cliente escanea el QR Code. Cuando el terminal detecta el escaneo, el botón de cancelar se desactiva y la venta ya no se puede cancelar en el terminal. Si el cliente cancela antes de escanear o la operación se aborta, el flujo vuelve al modo de espera.

Paso 3: Maneja la respuesta

Cuando el cliente completa el pago en su billetera, el TPV devuelve una respuesta estructurada. A continuación se muestra un ejemplo de respuesta completa para una venta con QR Code:

{
  "Code": 0,
  "Message": "APPROVED",
  "AuthorizationCode": "123456",
  "Amount": 7500,
  "OriginalAmount": 7500,
  "AccountingDate": "2025-08-25T16:11:23.0000000Z",
  "RealDate": "2025-08-25T13:11:50.8570000-03:00",
  "SaleType": "QrCode",
  "CommerceCode": "1234567890",
  "TerminalId": "GET00123",
  "CardType": null,
  "CardBrand": null,
  "Last4Digits": null
}

Como muestra el ejemplo, los campos específicos de tarjeta no aplican a las transacciones con QR Code. Esto incluye el tipo de tarjeta, la marca y los últimos 4 dígitos, que se devuelven como null o vacíos.

Cuando el cliente completa una venta con QR Code mediante una billetera, algunos atributos de la respuesta pueden devolverse como null.

Consulta de estado posterior: Una transacción QR PCT (Point of Capture) consultada con Check Status siempre devuelve AUTHORIZED (código 1), nunca APPROVED. Un QR Code procesado con datos de tarjeta devuelve APPROVED (código 0) una vez capturado.

Verifica siempre el parámetro Code y el SaleType antes de procesar el resultado.

Siguientes pasos

Para pagos con tarjeta y una descripción general completa de los parámetros de Sale, consulta la guía Pago en un solo paso.
Para procesar devoluciones de transacciones con QR Code, consulta la guía Devolver un pago.