What Is BIP21 in Crypto Payments?

The Problem BIP21 Was Designed to Solve

Before BIP21 was published in 2012, Bitcoin payment requests were communicated by sharing a raw wallet address — a string of 25–34 alphanumeric characters with no amount, no label, and no context. A merchant who wanted a customer to pay exactly 0.05 BTC had to send the address and the amount separately, with the customer manually entering both into their wallet. Address transcription errors were common, and there was no standardised way to associate a payment amount or description with an address in a machine-readable format.

BIP21 solved this by defining a URI (Uniform Resource Identifier) scheme for Bitcoin that encodes all payment request parameters — address, amount, label, and message — in a single string that wallets can parse and pre-populate automatically. Scanning a BIP21 QR code opens the user's Bitcoin wallet with the recipient address and amount already filled in, reducing manual entry to a single confirmation tap.

The BIP21 URI Format Specification

A BIP21 URI follows the structure: bitcoin:[address]?[parameter1]=[value1]&[parameter2]=[value2]

The components are:

●        bitcoin: — the URI scheme identifying this as a Bitcoin payment request. This scheme is registered with the IANA and recognised by Bitcoin wallet applications.

●        [address] — the recipient's Bitcoin address. Required. Can be a legacy (P2PKH), P2SH, or bech32/bech32m native SegWit address.

●        amount — the requested payment amount in BTC. Optional but strongly recommended. Expressed as a decimal (e.g., amount=0.001 for 0.001 BTC). Payment gateways always include this to prevent customer errors.

●        label — a short label for the sending wallet to display as a description (e.g., label=Finassets%20Order%20123). Optional. URL-encoded.

●        message — a message for the payer's reference that does not appear in the transaction (e.g., message=Thank%20you%20for%20your%20order). Optional.

A complete BIP21 URI for a €50 payment at 0.002 BTC to address bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwfvenl would look like:

How Wallets Parse and Handle BIP21 URIs

When a user scans a BIP21 QR code or clicks a bitcoin: link on a mobile device, the operating system routes the URI to the registered Bitcoin wallet application. The wallet parses the URI parameters, populates its send form with the decoded address and amount, displays the label and message as contextual information, and presents the pre-filled transaction for the user to review and confirm.

The parsing must handle URL encoding correctly — spaces in labels are encoded as %20, special characters are percent-encoded — and must validate that the decoded address is a valid Bitcoin address before populating the send form. Well-implemented wallets also display the amount in both BTC and a local fiat equivalent using the current market price, helping users verify the expected fiat value before confirming.

BIP21 Extensions — Unified QR Codes and Lightning

BIP21 has evolved to support unified payment requests that offer both on-chain Bitcoin and Lightning Network payment options in a single QR code. An extended BIP21 URI can include a lightning parameter containing a BOLT11 or BOLT12 invoice: bitcoin:[address]?amount=[value]&lightning=[bolt11_invoice]. When a customer scans this unified QR code, a Lightning-capable wallet uses the Lightning invoice for instant, low-fee payment; a wallet without Lightning capability falls back to the on-chain address.

This unified QR approach solves a practical problem in Lightning adoption: merchants previously had to present two separate QR codes (one for on-chain, one for Lightning) or choose one and exclude the other user segment. The unified BIP21 QR allows simultaneous Lightning and on-chain support from a single checkout display, with the customer's wallet automatically selecting the appropriate payment method based on its capabilities. Payment gateways supporting both Bitcoin payment types now commonly generate unified BIP21 URIs rather than separate codes.

Generating BIP21 URIs Programmatically

For payment gateways generating BIP21 URIs as part of invoice creation, the implementation requires: a valid Bitcoin address (generated from the HD wallet for this specific invoice), the payment amount converted from the fiat invoice value to BTC at the current exchange rate (rounded to 8 decimal places), an Order ID or label for the merchant's reference, and URL encoding of any string parameters. The resulting URI is then encoded into a QR code using a QR code generation library with appropriate error correction level and quiet zone.

Gateways should regenerate the BIP21 URI and its QR code if the exchange rate changes significantly during the payment window — some implement automatic rate refresh at mid-window to ensure the displayed amount remains accurate if the price has moved. The new URI with the updated amount should replace the old QR code on the checkout page with a clear notification that the amount has been recalculated.

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.