What a BOLT11 Invoice Contains
BOLT11 is the Lightning Network standard (BOLT = Basis of Lightning Technology, document 11) that defines the payment request format. A BOLT11 invoice is a bech32-encoded string beginning with 'lnbc' (Lightning Network Bitcoin mainnet), 'lntb' (testnet), or 'lnbcrt' (regtest). The invoice encodes:
● Destination node public key: Identifies which Lightning node should receive the payment.
● Payment hash: A 32-byte hash that the payer uses to construct the HTLC (Hash Time-Locked Contract) that secures the payment in transit.
● Amount: The requested amount in millisatoshis (1,000 millisatoshis = 1 satoshi). If omitted, the payer can choose any amount.
● Expiry: How long the invoice is valid, in seconds from creation. Default is 3,600 seconds (1 hour).
● Timestamp: Unix timestamp of invoice creation.
● Description: A short human-readable description of the payment (or a hash of a longer description).
● Route hints: Optional hints for how to reach the destination node through private channels, needed when the destination does not have public channels.
● Cryptographic signature: The destination node's signature over the invoice data, proving authenticity.
How HTLCs Make Lightning Payments Atomic
The payment hash in a BOLT11 invoice is the SHA256 hash of a secret preimage known only to the payment recipient. When the sender initiates the payment, they route a Hash Time-Locked Contract (HTLC) along the payment path: each hop locks funds conditional on revealing the preimage that produces the payment hash. When the payment reaches the recipient, the recipient reveals the preimage to claim the funds at the final hop. Each intermediate node then uses the revealed preimage to claim its funds from the previous hop, atomically settling the entire payment path.
If the payment cannot reach the recipient — due to a failed channel, insufficient capacity, or an offline node — no funds move at any hop because the HTLC conditions are never satisfied. The payment either succeeds completely or fails completely, with no partial settlements and no loss of funds. This atomic property is what makes Lightning safe for payment processing despite routing through untrusted intermediate nodes.
Invoice Expiry and Its Implications for Merchants
BOLT11 invoices have a defined expiry — by default one hour, but payment gateways typically set 10–30 minute expiries to align with their price lock windows. An expired invoice cannot be paid: the recipient's wallet will reject a payment attempt using an expired invoice even if the payment arrives at the destination node.
For merchants, this means that BOLT11 invoices must be generated on demand rather than pre-generated in bulk, and customers must complete payment before the invoice expires. Payment gateways that serve Lightning invoices generate them at the moment of checkout and monitor for payment receipt within the expiry window. If the invoice expires unpaid, a new invoice with a refreshed price lock must be generated, which payment gateways handle automatically in their checkout flow.
BOLT11 vs. BOLT12 — The Next-Generation Invoice Format
BOLT12 (also called Offers) is a successor to BOLT11 that addresses several of its limitations. BOLT11 invoices are single-use: each invoice encodes a unique payment hash and can only be paid once. BOLT12 offers are reusable payment identifiers — a merchant publishes a static Offer that customers can pay multiple times, with the recipient's node generating a unique invoice per payment request on the fly. BOLT12 also improves privacy by supporting blinded paths that hide the recipient's node identity.
As of 2025, BOLT12 support is growing but not yet universal. The majority of Lightning wallets and payment gateways still use BOLT11. Merchants considering Lightning payment integration should verify their chosen gateway's BOLT12 roadmap, as the transition will improve the user experience of recurring Lightning payments significantly.
Route Hints and Private Channels
A BOLT11 invoice from a node with no public channels — a node that only has private channels to specific peers — cannot be found by the sender's routing algorithm because it does not appear in the public Lightning Network graph. Route hints solve this: the BOLT11 invoice includes encrypted hints for how to reach the destination node through one or more of its private channel peers.
Payment gateways that operate Lightning nodes for merchant payment receipt typically maintain private channels with well-connected routing nodes and include route hints in all generated BOLT11 invoices. This allows customers on any Lightning wallet to route payments to the gateway's node even though the gateway's channels may not be publicly advertised. The privacy benefit is that the gateway's node topology and channel balances are not visible to the entire network.
Compliance Note: This glossary entry is provided for general educational purposes only and does not constitute financial, investment, legal, or tax advice. Industry terminology may vary across jurisdictions and providers; definitions herein may not directly reflect the specific features, terms, or specifications of Finassets' services. For details on Finassets' offerings, please refer to official product documentation or contact our team directly.