Requesting
Asking to be paid on BSV: the handle, the QR code, the amount, and why there is no invoice to expire.
Being paid is the shortest flow in this wallet, and the easiest to overbuild.
The core of it is one line: the user has a handle, and sharing it is the request.
The two ways to be paid
Share a handle. Permanent, readable, theirs. It works in a message, read aloud over the phone, or printed on a card. Nothing to generate and nothing to expire.
Share a request with an amount. A handle plus an amount and a note, as a link or a QR code, for when the payer should not have to type the figure.
Do
Make the handle the primary thing on the receive screen, and the amount optional. Most of the time the payer knows what they owe.
Don't
Generate a new address for each request and show it. On BSV a fresh key is derived per payment automatically, so the privacy reason for showing a new address has already been handled. See Payments.
What is not here
Each absence removes a screen:
| Not in this flow | Why |
|---|---|
| An expiry | A handle is permanent |
| A choice of payment method | There is one |
| A minimum or maximum | Neither is needed |
| A fee to receive | There is none |
| Watching for arrival | The payer's wallet tells this one |
Don't
Add an expiry to a request. Nothing in a handle and an amount goes stale, so an expiry is a deadline with nothing behind it.
Entering an amount
Do
Let the amount be entered in local currency and converted, which is how people think about being owed money.
Do
Allow an empty amount. "Pay me what you like" is a real case: tips, donations, splitting a bill the payer can see.
The note
A short note travels with the request and appears in both parties' activity. It is the most valuable field on this screen, because it makes an activity list readable six months later.
Do
Prefill it where you can. A request made from a shared bill can say what the bill was.
Don't
Put anything personal in a note by default. It is shared with the payer and may end up in their records. See Wallet privacy.
Sharing it
Three contexts, three answers:
- In person: a QR code, large, high contrast, legible across a counter.
- In a message: a link, with the amount and note already in it.
- Out loud or in writing: the handle itself, which is the only form a person can repeat.
Do
Offer copy and share as distinct actions, and confirm in place rather than with a toast the user is not looking at.
When the payment arrives
A peer-to-peer payment is handed over, not broadcast, so the recipient's wallet learns of it directly, verifies it against block headers, and replies accepted or rejected. What the wallet does next, including payments that fail to verify, is on Receiving.
Do
Show it immediately and clearly: who paid, how much, and the note. A received payment is a good moment and the interface can say so.
Being paid by an app
An app paying out does not go through a request, and repeated small amounts from it are grouped in activity. See Receiving from an app.
Advanced
Behind a disclosure, for people who need it:
- A plain address, for payers whose wallet or exchange cannot do anything else. Say that confirmation will be weaker. See Legacy compatibility.
- A reusable payment link, for a donation page or a profile.
Recommendation
A public donation handle is permanently linked to everything paid to it. Suggest a separate handle for it. A tag such as @maya+donations@example.com sorts the payments but still resolves to Maya. See Paying by handle.
Open questions
- Do payers trust a handle alone, or do they expect a request with an amount?
- Should a request link show the recipient's profile before the payer's wallet resolves it?
Related
Written from: BRC-29, BRC-42, BRC-121, BRC-169.
Checklist
The rules on this page, in a form you can work through.
10 rules