Invoices and Payment Requests

Welcome to Course 6: Making and Receiving Payments! Now that you understand channels, liquidity, and security, let's get practical. In this lesson, we'll explore invoices and payment requests — the fundamental mechanism for requesting Lightning payments.

What Is a Lightning Invoice?

A Lightning invoice is a payment request — a structured piece of data that tells a payer how much to pay, or that any amount is acceptable, where to send the payment, a unique identifier for this specific payment, and exactly when the request expires. Unlike on-chain Bitcoin where you simply share a static address, Lightning payments typically require a fresh invoice for each individual transaction.

Anatomy of an Invoice

A Lightning invoice (BOLT 11 format) contains several essential components. It includes a payment hash which serves as a unique identifier (hash of the secret preimage), an amount requested in satoshis (which is optional), a timestamp indicating when the invoice was created, an expiry defining how long the invoice is valid (default often 1 hour), a description providing a human-readable note about the payment, the destination which is the receiving node's public key, routing hints offering suggestions for reaching private nodes, and a signature that proves the invoice came from the destination node.

The Invoice String

Invoices are encoded as strings starting with `lnbc` (mainnet) or `lntb` (testnet). These strings are long but complete. They can be copied and pasted, often displayed as QR codes for mobile devices, and are decoded by the sender's wallet to process the payment.

Creating an Invoice

To receive a Lightning payment, the process varies by method. Using wallet apps, simply tap "Receive" or "Request", optionally enter an amount and description, and the invoice generates automatically. You can then share the QR code or copy the string. Using command line with LND, you would run a command like `lncli addinvoice --amt 10000 --memo "Coffee payment"`. Most Lightning implementations also provide API endpoints for invoice creation.

Paying an Invoice

To pay a Lightning invoice, follow these steps. First, obtain the invoice by scanning a QR code or pasting the string. Next, verify the details including the amount, description, and destination. Then authorize the payment by confirming in your wallet. Your node performs route discovery to find a path, executes the payment by locking funds along the path with HTLCs, waits for the receiver to reveal the preimage, and finally settles the payment, typically completing in seconds.

Invoice Expiry

Invoices expire — typically after 1 hour by default. This happens for several important reasons. Liquidity reasons mean the receiver must have inbound capacity ready, and long-lived invoices create uncertainty. Security reasons dictate that payment hashes should be used promptly. Practical reasons acknowledge that amounts and conditions may change over time. However, expiry can be set longer or shorter when creating the invoice to match your specific use case.

Zero-Amount Invoices

Invoices don't require a fixed amount. "Any amount" invoices let the payer decide how much to send. Use cases include donations and tips, variable service costs, and "pay what you want" models. This works by the invoice omitting the amount field, allowing the payer to include the amount when paying.

Invoice Descriptions and Metadata

Good invoice practices are essential for clarity. It is considered best practice to include a clear, concise description explaining what the payment is for. For longer descriptions, a description hash is included in the invoice while the full text is shared separately. Common examples of clear descriptions might include "Coffee - Corner Café," "Monthly subscription - January," or "Tip for episode #42," as these details help both the payer and the receiver track and identify payments easily.

Routing Hints for Private Nodes

If your node uses private channels, payers might not find a route. Routing hints solve this by including suggested paths in the invoice to reach you, with hints pointing through your private channel partner, enabling payments to non-public nodes. Most wallet software handles this automatically.

Invoice Limitations

Invoices have important limitations to understand. Each invoice is designed for single use, as the payment hash becomes "used" after payment. They are not reusable — unlike Bitcoin addresses, you can't publish one invoice for multiple payments. They have expiration windows and must be paid within the validity period. The receiver must usually be online to reveal the preimage and complete the payment.

BOLT 12 Offers: The Future

BOLT 12 "Offers" address invoice limitations with several improvements. They provide reusable payment requests allowing one offer to handle many payments, eliminate expiry issues by generating invoices on-demand, offer better payer privacy, and enable two-way communication with a request flow before the invoice is generated. BOLT 12 is being implemented across Lightning software and represents the future of payment requests.

Best Practices for Invoices

When creating invoices, include clear descriptions, set appropriate expiry for your use case, include routing hints if using private channels, and generate fresh invoices for each payment. When paying invoices, verify the amount before confirming, check the destination if possible, be aware of fee estimates, and pay promptly before expiry.

In this lesson, we've learned about Lightning invoices — the standard way to request payments. Understanding invoices is fundamental to using Lightning for everyday transactions.

In our next lesson, we'll explore Keysend and Pubkey Payments — sending payments without an invoice.