To request bitcoin, the receiver must provide the sender with a payment request. There are many ways to do this and payment request formats that can be used. This page covers generating, presenting, and sharing payment requests. We also cover receiving bitcoin.
Ways to request #
When a user requests bitcoin, there are three general ways in which this can be done:
- Single-use payment requests
- Reusable payment requests
- Withdraw requests
Single-use payment requests #
The most common way bitcoin is requested is in the form of single-use payment requests. Lightning payments use BOLT11 invoices. On-chain uses BIP21 and addresses of various types. A BOLT11 invoice can be embedded into a BIP21 URI to form a single payment request so senders can use what is most convenient for them and requesters do not have to be worried about requesting from on-chain or lightning.
Single-use payment requests are convenient for one-time or in-person payments. Generating them should be fast and convenient from the users home screen. Wallet balances should not be shown when generating single-use payment requests. This is due to the users funds being visible to nearby third-parties, which negatively impacts their privacy and puts the user at risk of theft.
When generating single-use payment requests, the receiver may want to add an amount to be paid. Entering an amount from the home screen is recommended.
Zero amount single-use payment requests should also be easily generated from the home screen by tapping request without an amount entered. By allowing the sender to set the amount when they are ready to pay, reduces both parties exposure to price volatility, as the amount paid in bitcoin will be more accurate in fiat terms.
Units must be toggleable between bitcoin, satoshi and the users local currency. Ensure the unit being entered is clearly visible, to prevent entering the wrong unit amount. More on the Units & Symbols page.
Invoice expirations #
Single-use lightning invoices aren’t permanent; they expire over time. However, this expiration time can be modified, unlocking unique use cases and improving usability in some situations.
When denominating invoices in fiat, custom expiries should be used to prevent exposure to price volatility.
If requesting a specific amount denominated in fiat, use a shorter expiry and have the invoice refresh each time it expiries. For a wallet designed for in-person payments, a 30 - 60 second expiry works well.
If there is no amount defined on the invoice, the invoice is denominated in bitcoin, or the invoice needs to be shared in a message, then use a longer expiry, like 24 hours.
While it is good to allow users to define their own custom expiries, remember that only advanced users will do this. Choose a sensible default that makes sense for your user-base and how the wallet is intended to be used.
For some background on situations the user might encounter with different invoice expiries, see this blog post from designer Stephen DeLorme.
Using BOLT12 offers, invoice expirations will no longer be a point of user friction. Offers are not yet an accepted standard, or widely supported by wallets, so interoperability will be an issue if adopting it.
Address types #
For on-chain, there are several address types that can be used for single-use payment requests.
Each address type has unique benefits, such as SegWit saving on network fees and Taproot offering Lightning users increased privacy.
You should encourage users to use the latest, more feature rich address types. Having an option in the payment request settings to set which address type to be used by default is recommended.
Older address types should always be supported for backwards compatibility with older wallets.
A payment request with only standard data, like an amount and date, communicates little to both parties about purpose and context of the payment.
Users should have the option to attach a note for record-keeping and for the sender to read, tags, labels and any other metadata that may be relevant to give more context to the payment.
This metadata should also be able to be backed up in case the user loses access to their wallet and has to restore it.
Add a requester name with NameDesc #
You can convey the name of the user requesting the payment. Suppose the user is able to define their name in the settings of their wallet app. The app could then append the user’s name to the beginning of the description field in a BOLT11 invoice. For example, if Alice makes an invoice with a memo that says “For design work”, then the description in the BOLT11 invoice would become:
Alice: For design work
This description is human-readable, and wallets that support bLIP-0011 NameDesc will parse this as a name and a description.
Reusable payment requests #
Reusable payment requests offer an improved user experience, more flexibility, and enable unique use cases, as they don’t need to be re-generated every time the user wants to receive bitcoin.
Currently there are limited reusable payment request options available. However, several are being worked on or are in the early stages of adoption. For Lightning, there are BOLT12 offers and AMP invoices. For on-chain, reusable payment codes can be used to privately receive bitcoin in a reusable way on-chain. Learn more about these on our payment request formats page.
Lightning address #
Lightning addresses, which look like regular emails (firstname.lastname@example.org), are reusable ways users can receive Lightning payments. These are not native to the Lightning network itself, but rather offered by a trusted server often ran by the wallet provider.
Generating a Lightning address should be simple for users and done within a profile page or during the users first use. At a minimum, your wallet should support sending to Lightning addresses, so it’s interoperable with other wallets.
Node ID #
A users Lightning node ID, which every non-custodial Lightning wallet has, can be a reusable way to receive Lightning payments using Keysends.
If a sender supports Keysends they can make recurring payments with attached messages to a users node ID without an invoice.
Having the option to quickly generate a personalised QR code of your node ID from the home screen is recommended.
This form of reusable payment request is not widely supported but offer a unique, way for users to make payments, tip users, and send messages over the Lightning network.
Withdrawal request #
Another way a user can request bitcoin is from a withdrawal request. A withdrawal request is a payment request that lets the receiver withdraw bitcoin from another wallet. Unlike previously mentioned payment requests, withdrawal requests are generated by the sender. These can be useful for merchants providing refunds to customers.
We explore generating a withdrawal request in our sending bitcoin section. Wallets that do not support withdrawal requests should provide users with a human readable error if an attempt is made to use one. Our payments format page goes into more detail on withdrawal requests.
The more payment request formats a wallet supports generating and receiving to, the more interoperable it will be. Some wallets may not support sending to a particular format so having several options makes it easier to request bitcoin.
Sharing payment requests #
Once a user has generated or stored reusable payment request, the next action to take is sharing it with the sender. There are several ways in which this can be done. Supporting all methods of sharing across payment formats makes it easier for users to request bitcoin.
Contact card #
A users contact card is a great way to store and share reusable payment requests. Learn more about contacts on our contacts page.
Plaintext involves simply copying and sharing a payment request with a sender.
Payment link #
Payment links are hypertext that contain a bitcoin payment request. They often contain a URI,
bitcoin: for an on-chain and
lightning: for Lightning, so they can be identified by the device clicking them. Other data is also usually included in these payment links, alongside the request such as a note or label.
QR code #
QR can be used to encode and share any kind of payment request. Ensure QR codes generated in your wallet are large enough, and have high contrast with the application’s background, to be easily scanned.
Uppercase QR code data
Using uppercased payment requests in QR codes results in less complex, more easily scannable, QR codes.
Payment requests should be shareable via contactless share, also known as near field communication (NFC), with nearby physical devices.
Receiving a payment #
Once a request has been shared, the sender then needs to send bitcoin to the request. We cover the design considerations and user flows for sending bitcoin in our sending bitcoin page.
Receiving a payment is something that involves a lot of background complexity. How a wallet application manages this, has a major impact on the end user’s experience.
To receive a payment, the receiver needs a payment channel with inbound liquidity and also has to be online. Some wallets offer services that allow channels to be opened on-demand if a user has no inbound liquidity when receiving an incoming payment. They may also hold payments for a user until they are online to forward it to them. These services require a wallet to be solely connected to the peer that offers these services. We cover what services are commonly offered and how they work on our Lightning services page.
Without Lightning services, a user will need to obtain some inbound liquidity before receiving a payment. This can be done by opening a channel with a peer that offers inbound liquidity and/or sending payments moving outbound to inbound capacity. It is recommended to let users know if they do not have any inbound liquidity before they share a payment request to prevent a payment failure.
Receiving on-chain involves the sender broadcasting a transaction to the network for it to be confirmed.
As on-chain transaction confirmation times vary based on network congestion and fees being paid, it is uncertain exactly when a on-chain payment will be considered complete. Keep users informed of the state of their incoming transactions.
Wallet applications should clearly indicate once a payment has been received by the user.
Users should have the option to share a confirmation that the payment has been received with the sender. For on-chain, the confirmed transaction on a bitcoin block explorer can be shared. For Lightning, a preimage can be shared to show proof of payment.
For in-person payments, showing the confirmation screen to the sender will likely suffice.
Next, we go over the design considerations for sending bitcoin.