QR Codes.

Gifty uses QR codes to encode gift card identifiers. These QR codes can contain either a complete URL pointing to our wallet system or a simple identifier code. This specification outlines the technical details of our QR code implementation and provides guidance for scanner configuration to ensure reliable scanning across different point-of-sale systems.

Code Structure

Our QR codes implement two distinct formats to accommodate different integration needs and system capabilities:

URL Format

The primary format encodes a complete URL that directs to our wallet system. This URL includes the gift card identifier and provides direct access to the digital wallet interface. For example:

          
            
https://wallet.gifty.nl/[identifier]/[token]
E.g. https://wallet.gifty.nl/ABCDABCDABCDABCD/123456

The URL structure consists of:

A domain (which may vary depending on the implementation)
One or more segments containing the gift card identifier
Characters limited to uppercase letters (A-Z) and numbers (0-9)

Direct Format (legacy)

For compatibility with older systems and specific integration requirements, we also support a simplified format that contains only the gift card identifier. This format is particularly useful when:

Working with POS systems that have limited URL handling capabilities
Importing gift card codes from external systems
Integrating with systems that prefer direct identifier processing

          
            
[identifier]
E.g. ABCDABCDABCDABCD

Technical Implementation

Our QR code implementation uses UTF-8 encoding for all QR codes, which includes Extended Channel Interpretation (ECI) information in the QR code data. While this adds some overhead to the QR code size, it ensures broad compatibility with modern scanning systems.

For URL Format QR codes, we restrict content to:

Basic ASCII characters (codes 0-127)
Alphanumeric characters only (A-Z, 0-9)
Essential URL characters when needed (forward slash, period, colon)

For Direct Format (Legacy) QR codes, we further restrict content to:

Alphanumeric characters only (A-Z, 0-9)

Scanner Configuration

Most barcode scanners can be configured in one of two ways:

Configuration Barcodes (most common)

Locate your scanner's manual or configuration guide
Find the section about QR code or 2D barcode settings
Scan the configuration barcodes needed to apply changes

Software Configuration

Connect your scanner to a computer using the manufacturer's software
Navigate to the QR code or 2D barcode settings
Make the needed configuration changes and write them to the barcode scanner

Common Scanner Settings

For optimal performance with Gifty QR codes, configure your scanner with these settings:

Set the primary encoding to UTF-8
Disable URL preprocessing
Disable prefix/suffix additions
Enable raw data transmission
Ensure sufficient maximum string length

Validation and testing

A properly configured scanner should output the complete content of the QR code without modification. You can verify this by scanning the QR-codes below to a simple text editor like Notepad (Windows) or Texteditor (MacOS).

URL Format

Expected output: https://wallet.gifty.nl/ABCDABCDABCDABCD/123456

Direct Format

Expected output: ABCDABCDABCDABCD

Common issues

Issue	Solution
Extra characters in the output \000026https://wallet.gifty.nl/...	This indicates the scanner is adding control characters. Disable special character processing in your scanner settings.
Truncated Content	If the content is cut off, verify your scanner's maximum string length setting can accommodate the full QR code content.
Character Corruption	If characters appear incorrect or garbled, check that UTF-8 support is properly enabled.