Process QR Code Payments

This guide explains how to use the terminal’s screen to display dynamic QR codes for digital wallet payment flows using the Y0Q command.

How it works

Unlike card payments where the terminal reads data from a physical medium, a QR transaction inverses the flow: the terminal displays the payment data (the QR code string), and the user’s mobile device scans it.

• Bypassing EMV: The QR flow does not use the standard Y19/Y15 initialization sequence because it bypasses the EMV kernel entirely.
• Dynamic Rendering: The terminal receives a raw alphanumeric data string from the Host System and renders the 2D QR matrix on the display.
• Amount Visibility: If the QR data string contains Tag 54 (Amount), the Pinpad automatically adds a ”$” symbol and displays the amount on the screen.

The whole flow is managed through the Y0Q command. While the QR is displayed, the Pinpad blocks other transaction attempts and ignores any command other than the Y06 cancellation command.

Step 1: Render the QR code (Y0Q request)

The Host System gathers the payment target data (e.g., a wallet string) and sends it directly to the Pinpad.

TDP Table (Screen Types)

The TDP field allows the Host System to navigate between three specific UI states:

Step 2: Validate the display (Y0Q response)

The Pinpad returns an ACK immediately after validating and parsing the command. The UI layer then generates the QR matrix and displays it on the screen.

Step 3: Handle status changes (optional)

If the Host System needs to provide a progress update (e.g., “Processing information”), it must first send a Y06 command to stop the QR exposure and then send a new Y0Q command with TDP set to “02”.

Finalizing or canceling

Since the financial transaction occurs between the user’s device and the wallet provider, the Pinpad does not automatically know when the payment is complete. The Host System must monitor its own authorizer for the status.

• Host Completion: Once the payment is confirmed, the Host System must send a Y06 command or a Y0Q command with TDP set to “03” to clear the screen and return to IDLE.
• Automatic Cancellation: If the user cancels the action on the device or the timeout is reached, the Pinpad returns a Y0Q response with a status code ([STS]):
• “0”: Cancelled by the user.
• “1”: Cancelled by timeout.

Implementation reference (Kotlin)

The following logic defines how the Y0Q command is processed and rendered within the application.

Command handling and parsing

The CommandY0Q class handles the parsing of received fields, while handleCommandY0Q triggers the UI display logic.

/**
 * 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?)

QR matrix generation

The Pinpad utilizes the ZXing library to encode the alphanumeric string into a 2D matrix bitmap.

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

Communication example

This example illustrates the flow for displaying a QR code with a $200.30 amount and a subsequent manual cancellation from the Host.

The following code block displays the Host Requests QR Display (Tag 54 = 200.3):

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

The Pinpad validates and displays:

[PP] <ACK>

In the case the host aborts the QR exposure:

[SP] <STX>Y06060<ETX>j

In that case, the Pinpad confirms the cancellation:

[PP] <ACK>

Next steps

With QR Code payments implemented, you can complete your integration by reviewing:

1. Cancellations and Refunds: Learn how the Y06 command interacts with active QR sessions.
2. API Commands: Refer to the full technical reference for every field in the Y0Q payload.