Payment request standards
A payment request turns an address and an amount into a single link or QR code that a wallet can read. Done well, it removes the most common causes of failed or wrong payments: mistyped addresses, wrong amounts and the wrong network. Two published standards cover most of the ground, BIP-21 for Bitcoin and EIP-681 for Ethereum.
Key points
- BIP-21 and EIP-681 define URI formats that wallets can turn into a pre-filled payment.
- BIP-21 amounts are in bitcoin as a decimal; EIP-681 values are in the smallest unit of the asset.
- EIP-681 can name a chain id so the request points at the intended network.
- Test every request format on a testnet before using it with real funds.
Why payment requests matter
On-chain payments are generally irreversible, so the cost of a typo is high. An address copied by hand can be wrong by one character. An amount can be entered in the wrong unit. A customer can send the right asset on the wrong network. A payment request fixes the details in advance, so the payer's wallet fills them in.
A request is just text: a URI with a scheme, a target and optional parameters. A QR code is that same text drawn as an image. Your invoice, checkout page or point-of-sale screen can show either.
BIP-21: Bitcoin payment URIs
BIP-21 defines a URI that starts with the scheme bitcoin:, followed by the receiving address and then optional query parameters. An illustrative format, with placeholder values, looks like this: bitcoin:ADDRESS?amount=0.0125&label=Example%20Shop&message=Invoice%201042.
Wallets that support BIP-21 read the address and parameters and present a pre-filled payment for the payer to confirm. Text in labels and messages is URL-encoded, which is why spaces appear as %20.
| Parameter | Meaning | Notes |
|---|---|---|
| amount | Amount to pay | Decimal bitcoin, using a period as the decimal separator, not satoshis |
| label | Name of the recipient | Shown to the payer; not stored on the blockchain |
| message | Note describing the payment | Useful for an invoice number; not stored on the blockchain |
| req- prefix | A parameter the wallet must understand | A wallet that does not recognize a required parameter should treat the URI as invalid |
EIP-681: Ethereum payment requests
EIP-681 defines a URI that starts with ethereum:, followed by a target address. It can then include an @ sign and a chain id, a slash and a function name, and query parameters.
For a plain transfer of ether, the request names the recipient and a value parameter in wei, the smallest unit of ether. An illustrative format is ethereum:RECIPIENT@1?value=2.014e18, which asks for 2.014 ether on chain id 1, Ethereum mainnet. Scientific notation is allowed, which helps with very large integers.
For a token transfer, the target is the token's contract address and the function is transfer. The recipient goes in an address parameter and the amount in a uint256 parameter, expressed in the token's smallest units. An illustrative format is ethereum:TOKEN_CONTRACT@1/transfer?address=RECIPIENT&uint256=1.5e6. For a token with six decimal places, that is 1.5 tokens; for a token with a different number of decimals, it is a different amount.
Amounts and units: the most common mistake
The two standards use different units, and tokens add another layer. Always confirm the unit and, for tokens, the number of decimal places the token uses before generating a request.
| Request type | Amount field | Unit |
|---|---|---|
| Bitcoin (BIP-21) | amount | Bitcoin, as a decimal |
| Ether (EIP-681) | value | Wei; 1 ether is 10^18 wei |
| Token on Ethereum (EIP-681) | uint256 with transfer | The token's smallest unit, set by its decimals |
Treating a decimal amount as base units, or the reverse, can be wrong by many orders of magnitude. Generate amounts in code from a single tested function, never by hand.
Chain ids and testnets
Many networks share Ethereum's address format, so an address alone does not say which network a payment belongs on. EIP-681's optional chain id fixes that. If no chain id is present, the payer's wallet uses whatever network it is currently set to, which may not be the one you expect.
Test networks, or testnets, have their own chain ids and their tokens have no monetary value. Bitcoin's test network uses different address formats from mainnet. Label any testnet request clearly so it can never be mistaken for a real invoice, and keep test and live configuration separate in your systems.
Not every wallet supports every parameter. Test the requests you generate with the wallets your customers actually use.
Building and testing a request
The payment request QR sandbox builds BIP-21 and EIP-681 requests for simulation only, with testnet settings and no real funds. The invoice builder sandbox shows how a request fits on an invoice, and the developer guide collects related material.
- Decide the asset, network and receiving address for the invoice.
- Convert the amount to the right unit in code, with tests for decimals.
- Build the URI, URL-encoding labels and messages.
- Render it as a QR code and scan it with a testnet wallet to check every field.
- Show the address and amount as text next to the QR code so the payer can cross-check.
- Set an expiry for the quote and say what happens to late payments.
What a payment request does not do
A request does not guarantee that the payer sends the exact amount, on time or at all. It does not lock a price, carry the payer's identity or confirm settlement. You still need to match the payment to the invoice when it arrives; see reconciling on-chain payments.
A QR code can also be replaced. A sticker over a printed code or a tampered checkout page can point payers to someone else's address. Showing the address as text, and protecting the systems that generate requests, are part of the defence; see crypto payment scams.
Questions people ask
Is the amount in a Bitcoin payment URI in satoshis?
No. BIP-21 specifies the amount in bitcoin as a decimal number, using a period as the separator.
What happens if an EIP-681 request has no chain id?
The payer's wallet keeps its current network setting, so the payment may be sent on a network you did not intend. Including the chain id avoids that ambiguity.
Can one QR code work for any wallet?
Only for wallets that support the standard and the parameters you used. Test with the wallets your customers use and show the address and amount as text too.
Do label and message fields go on the blockchain?
In BIP-21 they are shown to the payer by the wallet and are not part of the on-chain transaction, so keep your own record linking the payment to the invoice.
Sources
- BIP-21 — URI scheme
- EIP-681 — URL format for transaction requests
- bitcoin.org — Developer guide: block chain
Reviewed October 30, 2026. Educational information only; not financial, legal, tax or investment advice. This site does not process payments or hold funds.