Customer-Presented QR

Why It Matters

For developers working with PixQR, understanding Customer-Presented QR is critical because it directly impacts how QR codes are generated, presented, and tracked in payment workflows. It ensures that transaction flows are secure, user-friendly, and aligned with compliance requirements for financial transactions.

These QR codes are often used in point-of-sale (POS) systems, e-commerce platforms, and mobile apps where a user initiates a payment and scans a QR code presented to them. PixQR's support for Customer-Presented QR ensures that the QR code is not only scannable but also supports features like dynamic redirects, fraud prevention, and analytics, which are essential for real-world transactional environments.

How It Works

Customer-Presented QR codes in PixQR are generated dynamically based on transaction parameters and are associated with a specific payment intent. These QR codes are designed to be scanned by a merchant or service provider and are typically used in a two-step process: the customer initiates a payment, and the system generates a QR code for the customer to scan.

• The QR code is generated using a unique identifier tied to the transaction, such as a payment reference or session ID.
• It supports dynamic redirects to ensure the scan leads to the correct transaction endpoint.
• Analytics and tracking data are embedded within the QR code or its associated metadata to monitor scan behavior and transaction success.
• Security features such as encryption, expiration times, and access control are applied to prevent misuse or unauthorized access.
• Customer-Presented QRs are often tied to a specific brand or merchant identity to ensure trust and compliance with payment standards.

Quick Reference

Basic Example

PixQR Example QR

This QR links directly to this glossary page, so printed notes, onboarding docs, and support material can bring scanners back to the current reference.

/glossary/qr-code-for-payments/qr-codes-for-payments-customer-presented-qr

This example demonstrates a basic Customer-Presented QR generation using PixQR's API. It shows how a transaction ID is used to create a QR code that is presented to the customer.

const qrResponse = await pixqr.generateQR({
  transactionId: "txn_123456789",
  redirectUrl: "https://example.com/checkout/complete",
  brand: "MyBrand"
});

The transactionId uniquely identifies the payment flow. The redirectUrl ensures that when the QR code is scanned, the user is directed to the correct checkout completion page. The brand parameter applies a consistent visual identity to the QR code.

Production Example

This example shows a production-ready implementation of Customer-Presented QR generation, including validation, error handling, and configuration for a payment flow.

async function generateCustomerQR(transactionData) {
  try {
    const qrCode = await pixqr.generateQR({
      transactionId: transactionData.id,
      redirectUrl: transactionData.redirectUrl,
      brand: transactionData.brand,
      expiration: 900,
      analytics: true
    });
    return qrCode.url;
  } catch (error) {
    console.error("Failed to generate QR code:", error);
    throw new Error("QR generation failed");
  }
}

This version includes error handling, validation of transaction data, and explicit configuration for expiration time and analytics tracking. It is suitable for production use where reliability and traceability are required.

Common Mistakes

• Not setting a unique transaction ID, leading to QR code collisions or tracking issues.
• Using static redirect URLs, which can cause security vulnerabilities or incorrect transaction routing.
• Ignoring expiration times, resulting in outdated QR codes that may be misused or cause transaction failures.
• Skipping analytics configuration, which limits visibility into scan behavior and transaction success rates.
• Not validating the brand or visual identity, which can lead to inconsistent or untrusted QR code appearance.
• Hardcoding transaction parameters instead of using dynamic values, reducing flexibility and scalability.

Security And Production Notes

• Always validate transaction IDs and ensure they are unique to avoid conflicts in payment tracking.
• Use HTTPS for all redirect URLs to prevent man-in-the-middle attacks or data interception.
• Set appropriate expiration times to reduce the risk of QR code misuse after a transaction window.
• Enable analytics to monitor QR scan behavior and detect anomalies or fraud attempts.
• Ensure brand identity is consistent and trusted to maintain user confidence and compliance with payment standards.

Related Concepts

Customer-Presented QR is closely related to several key concepts in payment and QR code development:

• Dynamic Redirects: The ability to dynamically route a scan to a specific endpoint, which is essential for Customer-Presented QRs to function correctly in payment workflows.
• Transaction Tracking: The ability to associate QR scans with specific payment events, which is critical for analytics and fraud prevention.
• Scan Analytics: The collection and reporting of scan data to improve user experience and operational insights.
• Brand-Safe Design: Ensuring that QR codes maintain a consistent and trusted visual identity across platforms.
• Privacy Controls: Implementing mechanisms to protect user data and ensure compliance with privacy regulations.

Further Reading

• MDN Web Docs
• WHATWG HTML Standard