-{% include picture.html
- image = "/assets/images/guide/payments/request/Home.png"
- retina = "/assets/images/guide/payments/request/Home@2x.png"
- layout = "shadow"
- caption = "Home screens can provide quick access to entering request flows."
- alt-text = "Screen showing home screen number pad entry."
- width = 250
- height = 541
-%}
-
{% include picture.html
image = "/assets/images/guide/payments/request/single-use-payment-request.png"
retina = "/assets/images/guide/payments/request/single-use-payment-request@2x.png"
layout = "shadow"
- caption = "Single-use payment requests are useful for in-person payments."
+ caption = "Single-use payment requests are useful for one-time, or in-person payments."
alt-text = "Screen showing single-use invoice."
width = 250
height = 541
@@ -60,7 +48,7 @@ Below is an overview of these various entry points:
image = "/assets/images/guide/payments/request/my-profile.png"
retina = "/assets/images/guide/payments/request/my-profile@2x.png"
layout = "shadow"
- caption = "Reusable payment requests, like Lightning addresses, are useful for receiving recurring payments."
+ caption = "Reusable payment requests, like lightning addresses, are useful for receiving recurring payments."
alt-text = "Screen showing reusable Lightning address."
width = 250
height = 541
@@ -70,7 +58,7 @@ Below is an overview of these various entry points:
image = "/assets/images/guide/payments/request/withdraw-request.png"
retina = "/assets/images/guide/payments/request/withdraw-request@2x.png"
layout = "shadow"
- caption = "A withdraw request is another way a user can receive bitcoin."
+ caption = "A withdraw request is a unique way a user can receive bitcoin over lightning."
alt-text = "Screen showing withdraw request UI."
width = 250
height = 541
@@ -80,33 +68,17 @@ Below is an overview of these various entry points:
## Single-use payment requests
-The most common way bitcoin is requested today is in the form of single-use payment requests. For Lightning, a standard [BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) invoice is used. For on-chain, [addresses of various types]({{ "/guide/glossary/address/" | relative_url }}) are used. Addresses can be reused though this is not advised due to [privacy concerns]({{ "/guide/payments/privacy/#generate-a-new-address-for-each-on-chain-payment" | relative_url }}). Single-use invoices and addresses need to be easily and conveniently generated within a wallet application.
-
-### Amount
+The most common way bitcoin is requested is in the form of single-use payment requests. Lightning payments use [BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) invoices. On-chain uses [BIP21](https://bips.xyz/21) and [addresses of various types]({{ "/guide/glossary/address/" | relative_url }}). A BOLT11 invoice can be [embedded into a BIP21 URI](https://github.com/sbddesign/bip21-site) 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.
-When generating a single-use payment request, the receiver may want to add an amount to be paid. Entering an amount from the home screen can speed up the requesting flow. Alternatively, users can add an amount to an already generated payment request. Entering an amount needs to be clear to prevent users entering incorrect amounts.
-
-Amount units need to be toggleable between bitcoin, satoshi and local currency values as senders may request in a set unit. Ensure the unit being entered is prominent to prevent entering of the wrong unit amount. More on the [Units & Symbols page]({{ "/guide/payments/units-and-symbols/" | relative_url }}).
-
-### Address types
-
-There are several address types that can be used for on-chain payment requests. Each address type has unique benefits, such as SegWit saving on network fees. It's recommended to encourage users to use the latest - more feature rich address types. However, older address types should be supported for seamless backwards compatibility. More on the [address types]({{ "/guide/glossary/address/" | relative_url }}) page.
-
-### Meta data
-
-A payment request with only standard data like an amount and date communicates little to both parties about the payment. Users should have the option to attach a note for record-keeping and for the sender to read. Adding tags, labels and any other metadata that may be relevant to give more context to the payment is also beneficial.
-
-#### Invoice expirations
-
-A piece of meta data unique to invoices is an expiration time. This is how long until a single-use invoice expires. By default this is 60 minutes. When an invoice is generated an expiration timer needs to be shown to users alongside the payment request. For more custom use cases, allow users to adjust this expiration time manually.
+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.
{% include picture.html
- image = "/assets/images/guide/payments/request/Home.png"
- retina = "/assets/images/guide/payments/request/Home@2x.png"
+ image = "/assets/images/guide/payments/request/home.png"
+ retina = "/assets/images/guide/payments/request/home@2x.png"
layout = "shadow"
- caption = "Home screens can speed up the generating of a single-use payment request."
+ caption = "Hiding the balance and making it easy to generate a single-use payment request from the home page is recommended."
alt-text = "Screen showing home screen number pad entry."
width = 250
height = 541
@@ -116,82 +88,114 @@ A piece of meta data unique to invoices is an expiration time. This is how long
image = "/assets/images/guide/payments/request/single-use-payment-request.png"
retina = "/assets/images/guide/payments/request/single-use-payment-request@2x.png"
layout = "shadow"
- caption = "A newly generated single-use Lightning payment request."
+ caption = "A newly generated single-use payment request containing both an invoice and a on-chain address."
alt-text = "Screen showing single-use payment request."
width = 250
height = 541
%}
+
+
+### Amounts
+
+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 dollars.
+
+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]({{ "/guide/payments/units-and-symbols/" | relative_url }}).
+
+### Invoice expirations
+
+Single-use lightning invoices aren't permanent; [they expire over time]({{ "/guide/glossary/#lightning-invoice" | relative_url }}). However, this expiration time can be modified, unlocking unique use cases and improving usability in some situations.
+
+
+
{% include picture.html
image = "/assets/images/guide/payments/request/single-use-payment-request-settings.png"
retina = "/assets/images/guide/payments/request/single-use-payment-request-settings@2x.png"
- layout = "shadow"
- caption = "Let users configure the settings of single-use Lightning payment requests."
- alt-text = "Screen showing single-use payment request settings."
+ layout = "float-left-desktop -background -shadow"
+ caption = "Invoice expiries should be adjusted for the users use case."
+ alt-text = "Screen showing single payment request settings."
width = 250
height = 541
%}
-{% include picture.html
- image = "/assets/images/guide/payments/request/single-use-transaction-request.png"
- retina = "/assets/images/guide/payments/request/single-use-transaction-request@2x.png"
- layout = "shadow"
- caption = "A newly generated single-use on-chain payment request."
- alt-text = "Screen showing newly generated single-use on-chain payment request."
- width = 250
- height = 541
-%}
+When denominating invoices in fiat, custom expiries should be used to prevent exposure to price volatility.
-{% include picture.html
- image = "/assets/images/guide/payments/request/single-use-transaction-request-settings.png"
- retina = "/assets/images/guide/payments/request/single-use-transaction-request-settings@2x.png"
- layout = "shadow"
- caption = "Let users configure the settings of the single-use on-chain payment request."
- alt-text = "Screen showing newly generated single-use on-chain payment settings."
- width = 250
- height = 541
-%}
+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](https://d.elor.me/2022/01/lightning-invoice-expiration-ux-considerations/) from designer Stephen DeLorme.
+
+Using [BOLT12](https://bolt12.org/) 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.
+
+
{% include picture.html
- image = "/assets/images/guide/payments/request/single-use-address-type.png"
- retina = "/assets/images/guide/payments/request/single-use-address-type@2x.png"
- layout = "shadow"
+ image = "/assets/images/guide/payments/request/single-use-payment-request-settings-address.png"
+ retina = "/assets/images/guide/payments/request/single-use-payment-request-settings-address@2x.png"
+ layout = "float-right-desktop -background -shadow"
caption = "Supporting every address type benefits users and makes your wallet more interoperable."
alt-text = "Screen showing different address types."
width = 250
height = 541
%}
-
+Each address type has unique benefits, such as SegWit saving on network fees and Taproot offering Lightning users increased privacy.
-## Reusable payment requests
-
-Reusable payment requests aren’t as widely adopted or used as their single-use counterparts. For some use cases, reusable payment requests offer an improved user experience, more flexibility, and enable unique use cases compared to single-use payment requests. Reusable payment requests avoids users from having to manually initiate a payment request each time they need to receive bitcoin, greatly simplifying payment flows.
+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.
-Reusable payment requests are common when making Lightning payments as they are made more frequently. So manually generating a Lightning payment request for each payment adds a lot of friction.
+Older address types should always be supported for backwards compatibility with older wallets.
-[Lightning addresses](https://lightningaddress.com/), which look like regular emails (jane@domain.com), are a popular reusable way in which users can request Lightning payments. Receiving to a Lightning address requires users to generate their own unique Lightning address that can be shared with senders. These are not native to the Lightning network itself but rather use a third party server, often ran by the wallet provider, to provide this service. Generating a Lightning address is often done within the users profile or during onboarding.
+More on the [address types]({{ "/guide/glossary/address/" | relative_url }}) and [interoperability]({{ "/guide/designing-products/wallet-interoperability/" | relative_url }}) page.
-Reusable payment requests are not common when conducting transactions. This is due to them being conducted less frequently so the burden of generating a new payment request for each on-chain payment is not as large. On-chain addresses are reusable, though as previously mentioned this has privacy implications so this practice is not recommended.
-
-Several, not widely supported, reusable payments request formats also exist. For Lightning, there are BOLT 12 offers, AMP invoices and Keysends, which require just a node ID. For on-chain, there are reusable payment codes [BIP 47](https://bips.xyz/47) and [xpubs]({{ "/guide/glossary/#extended-public-key-xpub-ypub-zpub" | relative_url }}), which can be used to generate addresses for receiving bitcoin on-chain. Learn more about these on our [payment request formats]({{ "/guide/payments/request/payment-request-formats/" | relative_url }}) page.
+
+
{% include picture.html
- image = "/assets/images/guide/payments/request/Home.png"
- retina = "/assets/images/guide/payments/request/Home@2x.png"
- layout = "shadow"
- caption = "Users should be able to access their profile via the home page."
- alt-text = "Screen showing home screen number pad entry."
+ image = "/assets/images/guide/payments/request/single-use-payment-request-settings.png"
+ retina = "/assets/images/guide/payments/request/single-use-payment-request-settings@2x.png"
+ layout = "float-left-desktop -background -shadow"
+ caption = "Let users attach payment meta data to single-use payment requests."
+ alt-text = "Screen showing single payment request settings."
width = 250
height = 541
%}
+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 meta data should also be able to be [backed up]({{ "/guide/onboarding/backing-up-a-wallet/" | relative_url }}) in case the user loses access to their wallet and has to restore it.
+
+
+
+## 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](https://bolt12.org/) and AMP invoices. For on-chain, [reusable payment codes](https://bips.xyz/47) can be used to privately receive bitcoin in a reusable way on-chain. Learn more about these on our [payment request formats]({{ "/guide/payments/request/payment-request-formats/" | relative_url }}) page.
+
+### Lightning address
+
+[Lightning addresses](https://lightningaddress.com/), which look like regular emails (jane@domain.com), 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 [onboarding]({{ "/guide/onboarding/introduction/" | relative_url }}). At a minimum, your wallet should support sending to Lightning addresses, so it's interoperable with other wallets.
+
+
+
{% include picture.html
image = "/assets/images/guide/payments/request/my-profile-empty.png"
retina = "/assets/images/guide/payments/request/my-profile-empty@2x.png"
@@ -222,26 +226,30 @@ Contact cards are a great way to store, manage and share reusable payment reque
height = 541
%}
-{% include picture.html
- image = "/assets/images/guide/payments/request/contact-list.png"
- retina = "/assets/images/guide/payments/request/contact-list@2x.png"
- layout = "shadow"
- caption = "Contact lists are great for storing and managing reusable payment requests."
- alt-text = "Screen showing contact list."
- width = 250
- height = 541
-%}
+
+
+### 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](https://bitcoinops.org/en/topics/spontaneous-payments/).
+
+
{% include picture.html
- image = "/assets/images/guide/payments/request/contact-card.png"
- retina = "/assets/images/guide/payments/request/contact-card@2x.png"
- layout = "shadow"
- caption = "Contact cards can store reusable payment requests of other users too."
- alt-text = "Screen showing another users contact card."
+ image = "/assets/images/guide/payments/request/node-id.png"
+ retina = "/assets/images/guide/payments/request/node-id@2x.png"
+ layout = "float-left-desktop -background -shadow"
+ caption = "Node ID's are a convenient, reusable way to receive Keysend payments."
+ alt-text = "Screen showing single payment request settings."
width = 250
height = 541
%}
+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
@@ -278,21 +286,23 @@ The more payment request formats a wallet supports generating and receiving to,
## Sharing payment requests
-Once a user has generated a 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.
+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.
-### Plaintext
+#### Contact card
-Sharing a payment request as plaintext involves simply copying and sharing it with a sender. It is typical for bitcoin wallets to provide a share button that allows receivers to share a payment request in this manner conveniently. Both reusable and single-use requests should be shareable as plaintext.
+A users contact card is a great way to store and share reusable payment requests. Learn more about contacts on our contacts page.
-### Payment link
+#### Plaintext
-Bitcoin 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.
+Plaintext involves simply copying and sharing a payment request with a sender.
-### QR code
+#### Payment link
-QR codes are a common way to present payment requests to senders. Any type of payment request can be converted into a QR for sharing with a sender. When generating QR codes in a wallet application, ensure they are large enough and have high contrast with the application's background to be easily scanned.
+Payment links are hypertext that contain a bitcoin payment request. They often contain a [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier), `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.
-Typically, QR codes are downloadable. For single-use requests, this makes them easier to share over various mediums. For reusable requests, these QR codes can be displayed in places where payments must be regularly sent, like a website's donation page.
+#### 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.
{% include /tip/open.html label="Uppercase QR code data" icon="info" color="blue" %}
@@ -300,27 +310,18 @@ Using uppercased payment requests in QR codes results in less complex, more easi
{% include /tip/close.html %}
-### Contactless
+#### Contactless
-A contactless share uses near field communication (NFC) technology to share a payment request with a nearby physical device. This is a convenient way to share a payment request in-person.
+Payment requests should be shareable via contactless share, also known as near field communication (NFC), with nearby physical devices.
-{% include picture.html
- image = "/assets/images/guide/payments/request/plaintext-single-use.png"
- retina = "/assets/images/guide/payments/request/plaintext-single-use@2x.png"
- layout = "shadow"
- caption = "Single-use payment requests are often shared in plaintext."
- alt-text = "Screen showing plaintext share."
- width = 250
- height = 541
-%}
{% include picture.html
image = "/assets/images/guide/payments/request/reusable-share.png"
retina = "/assets/images/guide/payments/request/reusable-share@2x.png"
layout = "shadow"
- caption = "Reusable payment requests, like Lightning addresses, should be easily shareable in plaintext."
+ caption = "Plantext is a convenient way to share payment requests."
alt-text = "Screen showing plaintext share."
width = 250
height = 541
@@ -330,22 +331,12 @@ A contactless share uses near field communication (NFC) technology to share a pa
image = "/assets/images/guide/payments/request/single-use-payment-request.png"
retina = "/assets/images/guide/payments/request/single-use-payment-request@2x.png"
layout = "shadow"
- caption = "QR codes are convenient for sharing single-use payment requests in person."
+ caption = "A QR code can encode any type of payment request."
alt-text = "Screen showing QR code share."
width = 250
height = 541
%}
-{% include picture.html
- image = "/assets/images/guide/payments/request/reusable-QR.png"
- retina = "/assets/images/guide/payments/request/reusable-QR@2x.png"
- layout = "shadow"
- caption = "Reusable payment request QR codes can be used in places that regularly receive payments like a donations page."
- alt-text = "Screen showing reusable QR code."
- width = 250
- height = 541
-%}
-
{% include picture.html
image = "/assets/images/guide/payments/request/payment-link.png"
retina = "/assets/images/guide/payments/request/payment-link@2x.png"
@@ -360,7 +351,7 @@ A contactless share uses near field communication (NFC) technology to share a pa
image = "/assets/images/guide/payments/request/contactless.png"
retina = "/assets/images/guide/payments/request/contactless@2x.png"
layout = "shadow"
- caption = "Sharing a payment request contactless is a quick way to request a payment in-person."
+ caption = "Sharing a payment request contactlessly is a quick way to request a payment in-person."
alt-text = "Screen showing contactless UI."
width = 250
height = 541