QR codes are the interface layer between a customer’s Lightning wallet and a merchant’s payment system. In theory, the interaction is simple: customer scans, payment arrives. In practice, I have watched dozens of checkout interactions go sideways because the QR presentation, the signage, or the error handling was not thought through.
This guide covers how to design a QR checkout flow that works for real customers, including people who have never paid with a Lightning wallet before. It is built from field observations during merchant onboarding sessions and from watching what actually confuses people at the point of sale.
The Basic QR Checkout Flow
A Lightning QR checkout works like this:
- The merchant enters the sale amount in their Lightning wallet or point-of-sale app
- The app generates a Lightning invoice encoded as a QR code
- The customer scans the QR code with their Lightning wallet
- The customer’s wallet decodes the invoice and shows the payment amount
- The customer confirms the payment
- The merchant’s device shows a confirmation that payment was received
Each step has potential failure points. Good checkout design minimises the chance that any step goes wrong and has clear recovery procedures when it does.
Screen Presentation: What the Customer Needs to See
QR Code Display
Size matters. The QR code must be large enough to scan reliably from a comfortable distance. On a phone screen, the QR should fill at least two-thirds of the screen width. If using a tablet or display screen, the QR should be at least 6cm x 6cm.
Contrast is critical. Black QR code on a white background. No coloured QR codes, no branded backgrounds, no low-contrast themes. Camera scanning software works best with high contrast.
Screen brightness. In bright outdoor conditions, particularly common in African market settings, phone screen brightness needs to be at maximum. A dim screen in direct sunlight makes QR codes nearly impossible to scan.
No screen clutter. The QR code screen should show: the QR code, the amount in local currency, and nothing else that distracts from the scanning interaction. Menu bars, notifications, and other wallet interface elements should not crowd the QR display.
Amount Display
Show the amount prominently. Display the payment amount in local currency, large and clear, above or below the QR code. The customer needs to verify that the amount matches what they expect to pay.
Show the amount in both currencies if possible. If your wallet displays both the local currency equivalent and the satoshi amount, show both. This gives the customer a cross-reference.
Do not show the Bitcoin price. The customer does not need to see the current Bitcoin-to-local-currency exchange rate during checkout. This information is distracting and can cause hesitation.
Physical Setup: Where the QR Code Lives
Counter-Top Presentation
The most common setup for small merchants is displaying the QR code on the merchant’s phone for the customer to scan. This works but has practical issues:
Angle the phone toward the customer. Lay the phone flat on the counter or use a phone stand that tilts the screen toward the customer. A phone held upright by the merchant creates an awkward scanning angle.
Stabilise the phone. A phone that moves or wobbles while the customer is trying to scan is frustrating. A cheap phone stand or even a small box to prop the phone at the right angle solves this.
Distance. The customer’s phone camera needs to be 10 to 25 centimetres from the QR code for most camera apps to focus and scan. Make sure the counter layout allows this.
Static QR Codes vs Dynamic Invoices
Static QR codes (a printed QR code that always resolves to the same Lightning address) are simpler but have limitations. The customer sets the payment amount themselves, which creates room for error. Some Lightning wallets do not support paying to a static address without an invoice.
Dynamic invoices (a new QR code generated for each transaction with the exact amount encoded) are better for merchant use because the amount is fixed and the customer simply confirms. The trade-off is that the merchant must generate a new code for each sale, which requires a working phone and app.
For most small merchants, dynamic invoices are the better choice despite the extra step, because they reduce payment amount errors.
Signage That Actually Helps
At the Point of Sale
Small, clear signage near the register that communicates:
- “We accept Lightning payments” (with a Lightning bolt icon if available)
- Simple step instructions: “1. Open your wallet. 2. Scan the code. 3. Confirm payment.”
- Do not use jargon. “Scan to pay” is better than “Pay via BOLT11 invoice”
For First-Time Customers
Merchants who regularly encounter customers trying Lightning for the first time benefit from a small printed reference card or counter sign that shows:
- What a Lightning wallet app looks like
- Where the scan button is in common wallet apps
- What to do if the scan does not work (try moving closer, increase screen brightness, check internet connection)
What Not to Put on Signage
- Bitcoin price information
- Exchange rates
- Technical specifications
- QR codes for multiple payment methods next to each other without clear labelling (this causes customers to scan the wrong code)
Common Checkout Failures and How to Handle Them
Customer Cannot Scan the QR Code
Most common cause: Screen brightness too low, QR code too small, or camera focus issue.
Fix: Increase screen brightness to maximum. Bring the phones closer together. If the customer’s camera app has trouble, suggest using the scan feature inside their Lightning wallet app rather than the phone’s general camera.
Customer Scans but Nothing Happens
Most common cause: The customer scanned with their regular camera rather than their Lightning wallet.
Fix: Ask the customer to open their Lightning wallet app first, then use the scan button within the wallet. Most phone cameras can read QR codes but will try to open them as URLs rather than Lightning invoices.
Payment Shows as Failed
Most common cause: Insufficient balance in the customer’s wallet, or a routing failure on the Lightning network.
Fix: Ask the customer to check their wallet balance. If they have sufficient funds, generate a new invoice and try again. Lightning routing failures are rare but do happen. A second attempt usually succeeds.
Invoice Has Expired
Most common cause: The merchant generated the invoice too early and the customer took too long to scan.
Fix: Generate a new invoice. Explain to the customer that Lightning invoices have a time limit.
Amount Looks Wrong to the Customer
Most common cause: The customer is seeing the amount in satoshis and does not recognise the equivalent in local currency, or the exchange rate has shifted slightly since the price was quoted.
Fix: Show the customer the local currency amount on your screen. Explain that the satoshi amount is the equivalent. Small differences due to exchange rate movement are normal and should be communicated calmly.
Design Principles for QR Checkout
Based on field observation, these principles consistently produce better checkout experiences:
Make the default path obvious. The customer should not have to figure out what to do. The QR code should be clearly displayed, the amount clearly visible, and the next step (scan this) self-evident.
Reduce decisions at the point of sale. The checkout moment is not the time for the customer to choose between payment methods, enter amounts, or configure settings. Generate the invoice, show the code, let the customer scan and confirm.
Acknowledge the payment visually. When payment is received, the merchant’s screen should change clearly: a green checkmark, a “paid” message, a sound. The customer needs confirmation that the transaction is complete.
Have a fallback ready. If Lightning checkout fails for any reason, smoothly offer an alternative payment method. Do not make the customer feel like the failure was their fault.
Common Questions
Should I use a printed static QR code or generate invoices for each transaction? Generate invoices for each transaction. Printed static QR codes create amount errors and do not work with all wallets.
What if my phone battery dies during business hours? Keep a charger at the counter. If your phone dies, accept cash or mobile money until it is charged. This is a basic operational resilience issue.
Can I use a tablet instead of a phone? Yes, and the larger screen makes QR codes easier to scan. If you have a tablet available, it is often a better checkout display device.
How do I handle a queue when generating invoices takes time? Practice the flow. Most Lightning wallets can generate an invoice in under five seconds. If your wallet is slow, consider switching to a faster option. The guide on Lightning for small merchants covers wallet selection.
Conclusion
QR checkout design is a detail that many people overlook in favour of the bigger questions about fees, settlement, and adoption. But at the moment of transaction, the checkout experience is everything. A confused customer who cannot scan a code will not come back to try again. A smooth, fast, clearly designed checkout builds confidence and earns repeat business.
The principles are simple: big QR codes, clear amounts, obvious confirmation, and graceful failure handling. Get these right and the checkout experience stops being a barrier.