Bitcoin QR Codes: BIP 21 and Lightning Guide for 2026

A coffee shop in El Salvador, a Bitcoin conference in Prague, and a browser extension tipping a content creator all share the same two QR formats: BIP 21 for on-chain transactions and BOLT11 for Lightning invoices. Getting these right matters more than for other QR types because an incorrectly encoded Bitcoin address can send funds to a burn address, unrecoverable. This guide walks through the specifications, shows a valid example of each, and explains where BTCPay Server, Strike, and Cash App differ in how they handle merchant flows in 2026.

Quick answer

A Bitcoin payment QR code is a text payload starting with bitcoin: (BIP 21 on-chain) or lightning: (BOLT11 Lightning invoice), rendered into a standard QR code. BIP 21 supports on-chain payments with optional amount, label, and message parameters. BOLT11 invoices are payment requests that encode amount, expiry, preimage hash, and a routing hint set, all cryptographically signed by the invoice issuer. Most modern wallets auto-detect both formats from the scheme prefix.

Table of contents

• BIP 21 URI format
• Valid BIP 21 example with all optional fields
• BOLT11 Lightning invoice structure
• Decoding a Lightning invoice
• Why merchants use Lightning
• Fee estimation for on-chain
• BTCPay Server integration
• Strike and Cash App merchant flows
• Hardware wallet and NFC alternatives
• Common failure modes
• FAQ

BIP 21 URI format

BIP 21 is the Bitcoin Improvement Proposal that defines the bitcoin: URI scheme. It was authored by Nils Schneider and Matt Corallo, accepted as Final status in 2012, and has remained stable since.

The grammar, simplified:

bitcoin:<address>[?amount=X][&label=Y][&message=Z][&<req-param>=W][&lightning=<BOLT11>]

All parameters after the address are optional. The address can be any valid Bitcoin address format: P2PKH (starting with 1), P2SH (starting with 3), or native SegWit Bech32 (starting with bc1). Taproot addresses (starting with bc1p) are accepted by all major wallets released after 2022.

Parameters

The lightning= parameter inside a BIP 21 URI is a BIP 21 extension (informally called BIP 21 with Lightning) that lets a single QR carry both an on-chain address and a Lightning invoice. Wallets that support Lightning try the Lightning path first and fall back to on-chain if Lightning is unavailable.

Valid BIP 21 example with all optional fields

bitcoin:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh?amount=0.00250000&label=QRCrack%20Coffee&message=Order%20%23412&lightning=lnbc25u1pn2pj83pp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdqqcqzpgxqyz5vqsp5usyc4lk9chsfp53kvcnvq456ganh60d89reykdngsmtj6yw3whfq9qyyssqy4lgd8tj637qcjp05rdto96fqn4hdd2lecs6w3wct6dlztu9tj2vdehj8af6pag4g8zjnmhnjp3prl6qfj6e3nx6t5pr0sl2duav60qqg2vh07

This pays 0.0025 BTC on-chain to the listed SegWit address with the label "QRCrack Coffee" and the message "Order #412". The Lightning parameter carries a BOLT11 invoice for 2500 satoshis as a faster alternative. A Lightning-first wallet scans, pays the Lightning invoice, and the on-chain address becomes a fallback.

At this payload size (about 420 bytes), the QR code sits at version 17 (85 by 85 modules) at ECC level M. Print at 5 cm square or larger for reliable scans.

BOLT11 Lightning invoice structure

BOLT11 is part of the BOLT (Basis of Lightning Technology) specification set, defined in the Lightning Network protocol documents. An invoice is a bech32-encoded string prefixed with lnbc (mainnet) or lntb (testnet).

The structure:

1. Human-readable part: lnbc plus the amount and unit (10u means 10 microBTC = 1000 satoshis)
2. Timestamp: Unix seconds when the invoice was created
3. Tagged fields: payment hash, expiry, description, payee public key, routing hints, features
4. Signature: secp256k1 signature over the invoice payload, proving the invoice came from the payee

Decoded fields include:

BOLT11 invoices are single-use. The payee generates the invoice, the payer pays it, and once paid, the invoice cannot be reused.

Decoding a Lightning invoice

Walking through a short example: lnbc25u1pn2pj83pp5...

• lnbc prefix marks mainnet
• 25u means 25 microBTC, which is 2500 satoshis
• 1pn2pj83 is the bech32-encoded timestamp and multiplier
• pp5qqqsyqcyq... is the payment hash tagged field
• The rest carries description, payee pubkey, and signature

Libraries that decode BOLT11 include lightning-invoice (Rust), bolt11 (JavaScript), and lndecode (Python). For quick local inspection, lncli decodepayreq on LND works without a remote server call.

Why merchants use Lightning

Three reasons dominate:

1. Settlement speed: Lightning payments confirm in under 3 seconds. On-chain confirmation takes 10 minutes to 6 hours depending on fees and congestion.
2. Fee size: Lightning fees on a 0.5 USD coffee purchase run roughly 1 satoshi, about 0.0006 USD. On-chain fees during congestion can exceed the payment amount for small purchases.
3. Privacy: Lightning payments are onion-routed and do not appear on a public ledger.

The trade-offs are liquidity management (the merchant needs inbound channel capacity to receive payments) and counterparty trust (Lightning channels require online nodes).

Fee estimation for on-chain

On-chain Bitcoin fees are paid per virtual byte (vbyte), not per transaction. A typical SegWit payment transaction is about 140 vbytes. In April 2026, mempool fee rates have been running between 2 and 15 sat/vbyte during normal periods, with spikes above 200 sat/vbyte during ordinal mint events.

Fee estimation APIs:

• mempool.space: The most-used source. Returns fast, medium, slow estimates.
• bitcoiner.live: Feed-style estimates.
• Blockstream.info API: Simple /fee-estimates endpoint.

BTCPay Server polls mempool.space by default and adjusts the on-chain invoice at QR render time. For retail use where the customer is at the counter, prefer Lightning to avoid on-chain fee variability.

BTCPay Server integration

BTCPay Server is the open-source, self-hosted merchant payment processor. It generates BIP 21 QR codes with Lightning fallback, handles webhook callbacks, and runs against your own Bitcoin and Lightning node.

A typical flow:

1. Merchant creates an invoice in BTCPay admin (or via API)
2. BTCPay returns a checkout URL
3. Customer opens the URL, BTCPay displays a QR with BIP 21 plus Lightning
4. Customer scans with any Bitcoin wallet
5. BTCPay detects on-chain broadcast or Lightning settlement
6. Merchant webhook fires with payment status

BTCPay's QR rendering uses qrcode-generator at ECC level M. You can override to L if your merchant signage has good contrast and you want a smaller code.

Strike and Cash App merchant flows

Strike is a Lightning-first app built on Bitcoin rails. Strike merchants generate Lightning invoices that can be paid by any BOLT11-compatible wallet, not just other Strike users. Strike handles USD settlement for merchants who prefer dollar-denominated accounting.

Cash App supports Bitcoin sends via BIP 21 QR scan, but Cash App generates its own proprietary QR format for receives (scan with a Cash App camera, not a generic Bitcoin wallet). For merchants, Cash App is Cash App to Cash App only, not open Bitcoin.

The practical lesson: if a merchant wants to accept Bitcoin from any wallet, BTCPay Server or Voltage or a similar open processor is the right choice. Cash App and Strike solve different problems.

Hardware wallet and NFC alternatives

Hardware wallets (Ledger, Trezor, Coldcard) display BIP 21 QR codes on their screens for receive addresses. On send, they display partially signed Bitcoin transactions (PSBTs) as QR codes that can be passed to watch-only wallets via air-gapped scanning. This is the basis for the Blue Wallet, Sparrow Wallet, and Seed Signer air-gap workflows.

NFC is the newer alternative. The Wallet of Satoshi and Phoenix Lightning wallets both support NFC tag reads for Lightning invoices, which is faster than scanning a QR. The trade-off: NFC requires hardware proximity, which does not work for online or remote payments.

Common failure modes

1. Invalid address checksum: A typo in the address causes wallet to reject with "invalid address." Always generate QRs programmatically, not by hand typing.
2. Expired Lightning invoice: BOLT11 invoices default to 1 hour expiry. A QR printed on a menu is useless for Lightning unless the invoice is refreshed dynamically.
3. Missing amount for retail: A BIP 21 QR without amount= lets the customer type any value. For retail, always include the amount.
4. Lightning invoice larger than QR payload limit: A BOLT11 invoice with many routing hints can exceed 600 bytes, pushing QR to version 20 or higher. Use routing hint compression or LNURL instead.
5. lightning: versus lightning= prefix: Some wallets expect a top-level lightning: URI, others expect the BIP 21 embedded lightning= parameter. Generate both forms for maximum wallet coverage.

LNURL and BOLT12

Two newer formats deserve mention. LNURL is a set of sub-protocols for Lightning that let a static QR code point to a server endpoint which issues fresh invoices on demand. LNURL-pay enables tip jars and donation QRs that stay valid indefinitely.

BOLT12 (the offer format) is the next-generation Lightning invoice spec. Offers are reusable, support recurring payments, and fit in smaller QR codes. Wallet adoption is still limited in 2026, with Phoenix, Core Lightning, and Eclair leading.

FAQ

Can I use the same QR code for on-chain and Lightning?

Yes, via BIP 21 with Lightning. Put the on-chain address at the start and include &lightning= as a parameter. Wallets that support Lightning take the fast path; others fall back to on-chain.

Do Bitcoin QR codes expire?

BIP 21 on-chain QRs do not expire. BOLT11 Lightning invoices expire after the invoice's embedded expiry time, typically 1 hour from issuance.

What wallet should I recommend to customers?

For Lightning, Phoenix, Wallet of Satoshi, and Blue Wallet are popular. For on-chain self-custody, Sparrow and Bitcoin Core remain the gold standard. For beginners, Muun combines on-chain and Lightning in a single interface.

Is BIP 21 the same as the Bitcoin URI scheme?

Yes. BIP 21 is the formal specification of the bitcoin: URI scheme registered with IANA.

How do I accept Bitcoin without running a node?

Use a hosted processor like OpenNode, IBEX, or Strike Business. You trade custody (they hold the funds until settlement) for operational simplicity.

Sources

• BIP 21 at github.com/bitcoin/bips/blob/master/bip-0021.mediawiki
• BOLT11 specification at github.com/lightning/bolts/blob/master/11-payment-encoding.md
• BTCPay Server documentation (2025 release notes)
• Lightning Network BOLT12 offer specification, draft status April 2026
• mempool.space open-source mempool explorer

Use QRCrack's Bitcoin QR generator to build a BIP 21 payment QR with Lightning fallback support, address validation for P2PKH, P2SH, SegWit, and Taproot, and print-ready export. All generation happens in the browser with no server calls.

_By the QRCrack engineering team. Published April 15, 2026. Last verified 2026-04-15._