.png "Requesting bitcoin (1)")
Requesting bitcoin involves creating and sharing a payment request with a sender. A payment request is a piece of information that tells a sender where and how much bitcoin to send someone. This page covers design considerations when requesting bitcoin with a daily spending wallet.
Payment request formats
Payment requests come in many different formats. Each has unique properties and use cases. To learn more about these formats, see the payment request formats page.
- Requesting entry point
- Entering an amount
- Creating the request
- Metadata
- Fees
- Sharing the request
- QR code
- Plaintext
- Contactless
- Payment link
- Advanced options
- Invoice expirations
Requesting entry point #
The wallet described in this reference design is for daily spending. That means creating payments should be simple and fast. As a result, this wallet lets the user send bitcoin directly from the home screen.
Avoid showing the user’s balance on the home or requesting page. When requesting payments in person, this could reveal the user’s balance to nearby on-lookers, negatively affecting the user’s privacy. More on this here.
Entering an amount #
From the request page, the user inputs an amount. This wallet offers an easy toggle feature, allowing the user to switch between entering amounts in sats, bitcoin, or their local currency. However, if a user has already entered an amount and then changes the unit, the input field will clear. This precautionary measure prevents users from requesting an amount they didn’t initially intend. For more details on entering amounts, refer to our Units & Symbols page page.
Moreover, users have the option to skip entering an amount. This flexibility caters to situations where the user might want the sender to determine the amount. Zero-amount requests also reduce the exposure of both parties to price volatility. This is because the bitcoin price in fiat terms could fluctuate between the time of the request and the actual sending of payment.
Creating the request #
After entering an amount, the user taps the ‘Request’ button. The app then generates and presents a payment request.
This wallet defaults to a unified payment request. These combine a lightning invoice and an on-chain address into a single payment request using BIP21.
Unified requests eliminate the hassle for users of choosing between requesting payment via the lightning network or on-chain. This choice can often be confusing, particularly for newcomers.
This wallet utilizes ‘swap addresses’ for all on-chain transactions. These are used to facilitate the transfer of received Bitcoin into the user’s Lightning balance. Consequently, the wallet maintains a single Lightning balance, avoiding the need for a separate on-chain balance. This simplifies the user experience and is trust-minimized and non-custodial, courtesy of submarine swaps. We cover these more in our lightning services and receiving pages.
As unified requests aren’t widely supported yet, and users may want to request just from lightning or on-chain, they have options to share the lightning invoice or on-chain address independently.
Receiving payments to this wallet requires users to be online. This wallet notifies users that their wallet should remain open until the payment is received. We cover this more on our receiving and lighting services pages.
Metadata is additional information that is part of or can be added to a payment request. This can include an amount, note, or name for the sender. Or for the requester, labels, or assigning a contact.
Expiration times are something unique to lightning invoices. We cover modifying these here.
Ensure users can back up this metadata to prevent them from losing their transaction history.
Fees #
Any fees the user may incur should be communicated alongside payment requests so users will know in advance if they will be charged before receiving a payment. What these fees are for will vary from app to app but they a generally for opening channels. Below are common fee scenarios this wallet will face:
- A fee is charged if the user has no open channels and needs one opened on-demand when the payment is received.
- A fee may be charged when requesting a zero-amount invoice if the received amount is higher than their inbound liquidity, also known as their receive limit.
- A fee is charged if the user is requesting an amount higher than their receive limit.
- No fee is charged if the user is requesting an amount lower than their receive limit.
Sharing the request #
Once the request is created, the next action is to share it. Below are ways in which bitcoin requests are commonly shared.
QR code #
Quick response codes (QR) encode a payment request into a scannable graphic. QR codes should be large enough and have high contrast with your application’s background so they can be easily scanned.
Uppercasing bech32 strings in the payment request data will result in less complex, more easily scannable QR codes. Automatically increasing screen brightness when displaying the QR code further improves scannability.
Plaintext #
Plaintext involves copying and sharing a payment request in text form. These should be shared over secure communication channels.
Contactless #
Requests can be shared wirelessly over short distances using near-field communication (NFC). This is more commonly known as a “contactless payment.”
Payment link #
Payment links use a BIP21 URI bitcoin: which makes these readable by other bitcoin applications. These can be included as part of a button or hyperlink. Also see the wallet selector UI pattern.
Advanced options #
When requesting bitcoin, there are some options that can offer unique experiences but are more suited for advanced users who know what they are doing.
Invoice expirations #
Lightning invoices aren’t permanent; they expire over time. However, this expiration period can be adjusted, enabling unique use cases and enhancing usability in certain situations.
When denominating invoices in fiat currencies, it is advisable to use custom expiry durations to mitigate the risk of price volatility.
If you are requesting a specific amount denominated in a fiat currency, opt for a shorter expiry period, refreshing the invoice each time it expires. For a wallet intended for in-person payments, an expiry duration of 30 to 60 seconds is effective.
In cases where the invoice does not define an amount, the invoice is denominated in bitcoin, or the invoice needs to be shared in a message, it is more suitable to use a longer expiry duration, such as 24 hours.
Although it is beneficial to allow users to set their own custom expiry durations, bear in mind that only advanced users will likely utilize this feature. Select a default duration that best serves your user base and aligns with the intended use of the wallet.
For further insight into the scenarios users might face with different invoice expiry durations, refer to this blog post by designer Stephen DeLorme.
Next, we go over the design considerations for receiving bitcoin bitcoin.
