A Bitcoin payment request can carry an amount and a shop label along with its destination. The amount has a defined unit. The label is supplied text. Neither tells you that money moved.
For someone reading a request in a wallet, the useful question is what each field asks the app to do. A Bitcoin payment URI uses the bitcoin: scheme to package those instructions. The current specification is BIP 321, which replaces BIP 21.
What a Bitcoin payment URI contains
The address is one part of the request. Query fields can add an amount, a recipient label and a message. A wallet can use those details when presenting the proposed payment.
Here are separate decoded fragments from a fictional request, not a complete URI. DEMO-DESTINATION is deliberately invalid. There is no payable address, link or QR code to open.
| Field | Fictional fragment | What it describes |
|---|---|---|
| Address | DEMO-DESTINATION | The requested destination, represented by an unusable placeholder here. |
amount | 0.00001234 | The requested amount in decimal BTC. |
label | DEMO SHOP | A label supplied with the request. |
message | DEMO ORDER | A description supplied for the user. |
The label is not an authenticated merchant identity. The message is request context, not a promise that those words appear in a blockchain transaction. Nor is it a customer-routing field such as an XRP destination tag. Our memo and destination-tag guide explains that separate role.
The amount uses BTC, even if the wallet displays sats
In BIP 321, amount is expressed in decimal BTC. A period separates the whole and fractional parts; commas are not allowed in that field. A wallet's display unit does not change the unit specified by the request.
There are 100,000,000 satoshis in one BTC. For the invented amount above:
0.00001234 BTC × 100,000,000 = 1,234 satoshis.
The request asks for 1,234 sats. The comma in this prose helps group the digits; it is not part of the amount fragment. This is teaching arithmetic, not a current payment, fee quote or transaction we submitted.
Unknown parameters: optional or required?
Suppose a request also carries an invented field called demo-note. Under BIP 321, a client that does not implement that optional field can ignore it. Ignoring it does not establish that the app understood its meaning.
Now change the invented name to req-demo-note. The req- prefix makes handling required. If the client does not implement it, the specification says to treat the entire URI as invalid. Dropping the unknown required field to make the request acceptable would lose that requirement.
The distinction concerns what the software can interpret. It does not rate the recipient or establish that a payment is safe.
A specification and a wallet version can differ
The checked Bitcoin Core v32.1 Qt parser handles lowercase amount, label and message, rejects unknown required fields and permits unknown optional ones. That is the common subset used by our example. The parser source and URI test source document those cases.
There are limits to that comparison. BIP 321 makes query keys case-insensitive and disallows repeated amount fields. The inspected Core parser compares those field names in lowercase; its test for repeated amounts expects the last value to win. Do not assume that every parser implements the entire current specification identically.
Our example therefore uses a single lowercase field of each kind. This is a source-code comparison, not a test of a running Bitcoin Core app or another wallet. BIP 321 also describes additional payment instructions and an optional return of payment information. Their presence in the standard does not establish support in a particular client.
A request is not a payment record
BIP 321 requires user authorization before a client acts on a URI. Reading or parsing a request is separate from authorizing, submitting or completing a payment. A populated amount and a convincing label can exist before any of those steps.
The optional return of payment information is a separate exchange after payment; putting a return instruction in the original request is not the same as receiving that result. No callback is constructed here.
For an onchain payment, reading the transaction record answers a different question from reading the request. If the request is all you have, you know what was asked for. You still need the relevant payment record to establish what happened.
Sources
Full specifications and the versioned Core parser and test source were checked on 18 November 2026. BIP 21 is superseded by BIP 321. The example uses invented, unusable fragments; it is not a payment link or captured wallet output. No wallet, parser binary, QR code, callback, signature or payment was opened, generated or tested.
- BIP 321: URI Scheme — current fields, amount units, required parameters, compatibility and payment-information return rules.
- BIP 21: URI Scheme — the superseded specification and replacement notice.
- Bitcoin Core v32.1: Qt URI parser — the specific field handling discussed above.
- Bitcoin Core v32.1: URI tests — documented test cases, including unknown parameters and repeated amounts. These tests were read, not executed.
See something wrong? Brokzi logs material changes. Prepare a correction note.




