# Send and receive BSV payments: every rule Every do and don't the guide states on the pages behind this skill. The costly ones come first; the full list follows, grouped by page. Quote them; do not paraphrase them. 100 rules: 18 that can cost money, 16 that can cost trust, 66 standard. ## Start here - **DO** _(Costs money)_ Resolve the handle and show the profile name and avatar before the confirm button. Paying "Anna Keller" is checkable; paying anna@example.com is only spellable. See Paying by handle. - **DON'T** _(Costs money)_ Let a typed handle go straight to a confirm screen with no resolution step. The resolution is the check. - **DO** _(Costs money)_ Warn on every pasted address that money sent to an address on another network is very hard to recover, and offer the user's contacts or a handle instead. - **DON'T** _(Costs money)_ Offer "Try again" on a payment until you know the first attempt did not go out. - **DO** _(Costs money)_ Tell the user once when their wallet is retrying for them: "Your wallet will keep trying to send this. You don't need to pay again." - **DO** _(Costs money)_ Show on the review screen the same sats amount the wallet's prompt will show, and if the rate moves before Anna presses the button, update the figure on this screen first rather than letting the wallet show a different number. - **DON'T** _(Costs money)_ Add a booking fee or any other charge after the review screen. If the product charges one, it is part of the price shown here. - **DO** _(Costs money)_ Show the profile name and avatar the handle resolved to, before the confirm button. Paying "Anna Keller" is checkable; paying anna@examplebank.com is only spellable. - **DO** _(Costs money)_ Say when the key behind a saved contact has changed since last time, and make the user acknowledge it. A silently rotated key is how a handle gets hijacked. - **DO** _(Costs money)_ Make the handle the default and the address the fallback. Every payment that uses a handle is a payment that cannot go to the wrong network. - **DO** _(Costs money)_ Put the network name next to the address field, always, not only on error. "BSV address" is three words and it is the whole defence. - **DO** _(Costs money)_ Warn on every pasted address rather than trying to detect a bad one. You cannot detect it, and a warning that only fires sometimes teaches people it means something specific. - **DON'T** _(Costs money)_ Use "bitcoin address" as the field label. That is the word that cannot distinguish the networks, on the screen where the distinction is the whole point. - **DO** _(Costs money)_ Put the network on the confirmation, beside the recipient, in the same weight as the amount. - **DO** _(Costs money)_ Say plainly what cannot be undone, before the button: "Sent to the wrong network, this usually cannot be recovered." - **DO** _(Costs money)_ Offer a test payment for a first-time address above a threshold you choose, and ask the user to check with the recipient that it arrived. It costs a fraction of a penny and it is the only defence that proves the address is right. - **DO** _(Costs money)_ Make the network selection impossible to leave at a default, and restate the chosen network on the confirmation. - **DO** _(Costs money)_ Warn before any payment to a contact whose key has changed, and require acknowledgement: "Anna's wallet key has changed since you last paid her. If you weren't expecting this, check with her another way first." - **DO** _(Costs trust)_ Show the running total against the allowance somewhere the user passes regularly, and make every agent or app payment visible in activity, marked as such. See Permissions and allowances. - **DO** _(Costs trust)_ Require the device's authentication to confirm, above whatever threshold the user set. - **DO** _(Costs trust)_ Say first whether money left the wallet. - **DO** _(Costs trust)_ Make sure this works without your servers, any Pass, or any vendor service. It is the user's guaranteed way out if everything else in the stack fails. See Backups. - **DO** _(Costs trust)_ Say whether money moved in every message that follows a payment attempt, including when the answer is that nothing left the wallet. - **DON'T** _(Costs trust)_ Ask for a spending allowance "to make the next purchase faster". A site people pay a few times a year should ask each time. - **DON'T** _(Costs trust)_ Keep a fee picker because the design system already has one. It asks the user a question with no wrong answer, which teaches them that your questions are decorative. - **DO** _(Costs trust)_ Leave the fee off the review screen entirely for ordinary payments, and put it in the transaction details afterwards for anyone who looks. - **DON'T** _(Costs trust)_ Put anything personal in a note by default. It is shared with the payer and may end up in their records. See Wallet privacy. - **DO** _(Costs trust)_ 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. - **DO** _(Costs trust)_ Always show the user what they're paying for, and the running total against their allowance. Small, frequent payments add up, and users should never be surprised by them. - **DO** _(Costs trust)_ Warn plainly when a handle does not resolve, naming what failed: no such handle, domain unreachable, certificate invalid. "Couldn't find that" sends people to try again rather than to look harder at what they typed. - **DON'T** _(Costs trust)_ Fall back silently to a plain-address payment when a handle resolves but does not support the peer-to-peer flow. Say so, because the confirmation the user gets is weaker. See Legacy compatibility. - **DO** _(Costs trust)_ Say what happened in plain words: which network it went to, that the money is not lost from the chain but is out of reach from here, and what recovery would require. - **DON'T** _(Costs trust)_ Promise recovery you cannot deliver. If it needs the other party's cooperation, say that is what it needs. - **DO** _(Costs trust)_ Name what is lost in the confirmation: the saved key, and therefore the warning if it changes. Payment history stays. ## Every rule, by page ### Sending https://www.bitcoinsv.design/guide/daily-spending-wallet/sending/ - **DO** Autocomplete from contacts before accepting free text, and make saving a new recipient the obvious next step after a first payment. The second payment to someone should never involve typing. - **DO** _(Costs money)_ Resolve the handle and show the profile name and avatar before the confirm button. Paying "Anna Keller" is checkable; paying anna@example.com is only spellable. See Paying by handle. - **DON'T** _(Costs money)_ Let a typed handle go straight to a confirm screen with no resolution step. The resolution is the check. - **DO** Default to the unit the user set, and let them switch between it and their local currency in one tap. See Amounts and units. - **DO** Allow very small amounts without complaint. A payment of 50 satoshis is ordinary, and a minimum blocks it for no reason. - **DON'T** Show a "max" button that empties the wallet without saying so. Label it with the resulting amount. - **DO** _(Costs trust)_ Show the running total against the allowance somewhere the user passes regularly, and make every agent or app payment visible in activity, marked as such. See Permissions and allowances. - **DON'T** Prompt for every per-use payment. An article that costs 20 satoshis cannot carry a confirmation dialog, and a wallet that insists makes the whole category unusable. - **DO** Make the recipient the largest thing on the screen. The amount is usually right; the recipient is what gets checked too quickly. - **DO** _(Costs trust)_ Require the device's authentication to confirm, above whatever threshold the user set. - **DON'T** Put an "advanced" disclosure on the review screen. If something matters enough to show, show it; if it does not, it belongs in the transaction's details afterwards. - **DO** Label every wait with the step and, where there is one, the person. "Handing payment to Anna's wallet…" tells the user what is happening and to whom. - **DON'T** Show a spinner with no words, or a full-screen loader for a step that takes a second. Both make an ordinary pause look like a fault. - **DO** _(Costs trust)_ Say first whether money left the wallet. - **DON'T** Show an error code as the headline. Put it in the details for support, with plain words on top. - **DO** _(Costs money)_ Warn on every pasted address that money sent to an address on another network is very hard to recover, and offer the user's contacts or a handle instead. - **DO** _(Costs trust)_ Make sure this works without your servers, any Pass, or any vendor service. It is the user's guaranteed way out if everything else in the stack fails. See Backups. - **DO** Show "Paid" on acceptance and stop there for everyday amounts. A spinner that waits for a block makes the user wait for nothing. See Transactions. ### Errors and failed payments https://www.bitcoinsv.design/guide/patterns/errors-and-failed-payments/ - **DO** _(Costs trust)_ Say whether money moved in every message that follows a payment attempt, including when the answer is that nothing left the wallet. - **DO** End every error with one thing the user can do, as a button where there is one. - **DO** Put the error code and technical detail in an expandable details area with a copy button, so support can ask for it. - **DO** Keep what the user entered. Return them to where they were with the amount, recipient and note still filled in. - **DON'T** Write "Something went wrong" on its own. If you truly do not know what happened, say what you do know and whether money moved. - **DO** Explain a failure in the app when it is about the app's task, such as an article not unlocking, and in the wallet when it is about the user's money or permissions. - **DON'T** _(Costs money)_ Offer "Try again" on a payment until you know the first attempt did not go out. - **DO** _(Costs money)_ Tell the user once when their wallet is retrying for them: "Your wallet will keep trying to send this. You don't need to pay again." - **DON'T** Show a refusal or an unanswered wallet prompt in an error style. Both are the user's choice, and red tells them they did something wrong. ### Buying a ticket https://www.bitcoinsv.design/guide/connected-web-app/buying-a-ticket/ - **DO** _(Costs money)_ Show on the review screen the same sats amount the wallet's prompt will show, and if the rate moves before Anna presses the button, update the figure on this screen first rather than letting the wallet show a different number. - **DO** Name who receives the money and who the ticket is for in one line. Anna is paying the ticket site, for a venue, and both names belong on the screen. - **DO** Say on the review screen what Anna can do with the ticket afterwards, give it away or not, refund it or not, before she pays rather than in the terms. - **DON'T** _(Costs money)_ Add a booking fee or any other charge after the review screen. If the product charges one, it is part of the price shown here. - **DO** Ask for the tickets basket in the first purchase's prompt, as a separate item Anna can decline, and never at sign-in. - **DON'T** _(Costs trust)_ Ask for a spending allowance "to make the next purchase faster". A site people pay a few times a year should ask each time. - **DO** Tell Anna where the ticket is, in her wallet, on the confirmation, so she does not wait for an email that is not coming. - **DO** Write the gig name, venue, date and what the holder may do with the ticket into the token when it is issued, so any wallet can show it without asking the site. - **DON'T** Let a picture of the ticket be enough to get in. The picture is the part anybody can copy; the door has to check that the person in front of it holds the ticket now. ### Send fees https://www.bitcoinsv.design/guide/daily-spending-wallet/sending/send-fees/ - **DON'T** _(Costs trust)_ Keep a fee picker because the design system already has one. It asks the user a question with no wrong answer, which teaches them that your questions are decorative. - **DO** _(Costs trust)_ Leave the fee off the review screen entirely for ordinary payments, and put it in the transaction details afterwards for anyone who looks. - **DO** In the payment's details, show the fee in local currency as one small line: "Fee: less than 1p". A figure in satoshis invites arithmetic nobody wanted to do. - **DON'T** Explain the fee model. A user who wanted to know about satoshis per byte will find it in the transaction details. - **DO** Pay the fee on the user's behalf where the product can, and do not mention it. We suggest a shop absorb it as a cost of sale and an app fold it into its price. It is a real option because the fee is smaller than any price the user will see. ### Requesting https://www.bitcoinsv.design/guide/daily-spending-wallet/requesting/ - **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. - **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. - **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. - **DO** Prefill it where you can. A request made from a shared bill can say what the bill was. - **DON'T** _(Costs trust)_ Put anything personal in a note by default. It is shared with the payer and may end up in their records. See Wallet privacy. - **DO** Offer copy and share as distinct actions, and confirm in place rather than with a toast the user is not looking at. - **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. - **DO** _(Costs trust)_ 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. ### Receiving https://www.bitcoinsv.design/guide/daily-spending-wallet/requesting/receiving/ - **DO** Show who paid, how much, and the note. When the payer's wallet shares a profile name and avatar, an entry can read "Anna Keller, for lunch"; otherwise show their handle. - **DO** Make it noticeable. A received payment is one of the few genuinely good moments in a finance app, and a silent list entry wastes it. - **DON'T** Show a confirmation counter. It was verified on arrival, and counting blocks afterwards tells the user that your "Received" was provisional. See Transactions. - **DO** Collect anything waiting on launch, verify it, and show what arrived while the user was away as a group rather than a burst of separate notifications. - **DO** Say on the receive screen's help, or in Settings › Services, that payments wait in a message box when the wallet is closed. It is the one real cost of the peer-to-peer model. See Payments. - **DO** Reject it, and tell the user in plain words that a payment arrived and could not be verified, so it was not accepted. Do not add it to the balance. - **DON'T** Show a cryptographic error. "Merkle proof invalid" tells the user nothing they can act on. - **DO** Use a different state for these: "Incoming" until it is mined, then "Received". It is genuinely less certain than a peer-to-peer payment and the interface should not pretend otherwise. See Legacy compatibility. - **DO** Show it with whatever the sender provided, and let the user add their own note. An unexplained entry is the one they will be puzzling over in six months. - **DON'T** Build a returns flow into a consumer wallet. Sending it back is just a payment, and the sender's handle is already there to pay. - **DO** Because step 4 happens, the payer can be shown "Paid" at the same moment the recipient is shown "Received". Design both ends of that: the two people are often standing next to each other. ### Payments https://www.bitcoinsv.design/guide/how-it-works/payments/ - **DO** Show "Paid" or "Received" as soon as the recipient's wallet replies "accepted". Do not wait for the payment to be mined. - **DO** Don't show derived payment addresses in the main interface. Show the person, handle or app the payment relates to. Keep raw transaction details in an advanced view. - **DO** _(Costs trust)_ Always show the user what they're paying for, and the running total against their allowance. Small, frequent payments add up, and users should never be surprised by them. ### Paying by handle https://www.bitcoinsv.design/guide/patterns/paying-by-handle/ - **DO** Accept both forms in any field that takes a handle. A user pasting anna@example.com into a wallet using the newer scheme should simply work. - **DO** _(Costs money)_ Show the profile name and avatar the handle resolved to, before the confirm button. Paying "Anna Keller" is checkable; paying anna@examplebank.com is only spellable. - **DO** _(Costs money)_ Say when the key behind a saved contact has changed since last time, and make the user acknowledge it. A silently rotated key is how a handle gets hijacked. - **DO** Make saving a resolved handle as a contact the obvious next step. The second payment to someone should never involve typing. - **DON'T** Show the derived address anywhere in the main flow. It is a one-time internal value and putting it on screen invites comparison nobody can perform. - **DO** Offer matches from saved contacts as the user types a handle, before accepting free text. - **DON'T** Show a handle on the review screen without the profile name it resolved to. On its own, a one-character difference is invisible. - **DO** _(Costs trust)_ Warn plainly when a handle does not resolve, naming what failed: no such handle, domain unreachable, certificate invalid. "Couldn't find that" sends people to try again rather than to look harder at what they typed. - **DON'T** _(Costs trust)_ Fall back silently to a plain-address payment when a handle resolves but does not support the peer-to-peer flow. Say so, because the confirmation the user gets is weaker. See Legacy compatibility. ### Wrong-network payments https://www.bitcoinsv.design/guide/patterns/wrong-network-payments/ - **DO** _(Costs money)_ Make the handle the default and the address the fallback. Every payment that uses a handle is a payment that cannot go to the wrong network. - **DO** _(Costs money)_ Put the network name next to the address field, always, not only on error. "BSV address" is three words and it is the whole defence. - **DO** _(Costs money)_ Warn on every pasted address rather than trying to detect a bad one. You cannot detect it, and a warning that only fires sometimes teaches people it means something specific. - **DON'T** _(Costs money)_ Use "bitcoin address" as the field label. That is the word that cannot distinguish the networks, on the screen where the distinction is the whole point. - **DO** _(Costs money)_ Put the network on the confirmation, beside the recipient, in the same weight as the amount. - **DO** _(Costs money)_ Say plainly what cannot be undone, before the button: "Sent to the wrong network, this usually cannot be recovered." - **DO** _(Costs money)_ Offer a test payment for a first-time address above a threshold you choose, and ask the user to check with the recipient that it arrived. It costs a fraction of a penny and it is the only defence that proves the address is right. - **DO** _(Costs trust)_ Say what happened in plain words: which network it went to, that the money is not lost from the chain but is out of reach from here, and what recovery would require. - **DO** Give them the transaction reference and the output, so somebody technical can help. - **DON'T** Say "transaction failed". It did not fail. It succeeded somewhere else, and telling somebody it failed sends them looking for a refund that is not coming. - **DON'T** _(Costs trust)_ Promise recovery you cannot deliver. If it needs the other party's cooperation, say that is what it needs. - **DO** _(Costs money)_ Make the network selection impossible to leave at a default, and restate the chosen network on the confirmation. - **DO** Treat a first withdrawal to a new address as a different flow from a repeat one. ### Contacts https://www.bitcoinsv.design/guide/daily-spending-wallet/contacts/ - **DO** Let the user rename a contact to whatever they call that person. "Mum" beats the profile name the handle returned, and it is what they will search for. - **DO** Offer "save as contact" in the success state of a first payment. One tap at the moment the information is in front of the user beats a form they have to go and find. - **DON'T** Ask for a name before resolving the handle. The resolution usually supplies one, and asking first makes the user invent a label for someone the wallet is about to identify. - **DO** _(Costs money)_ Warn before any payment to a contact whose key has changed, and require acknowledgement: "Anna's wallet key has changed since you last paid her. If you weren't expecting this, check with her another way first." - **DO** Record when the key last changed on the contact, so a user who is unsure can see whether this is the third change this month. - **DO** Show a Pass as what it proves and who vouched for it, not as a generic tick. "Business name verified by Example Registry" is checkable; a blue badge is not. - **DON'T** Imply a Pass means the person is trustworthy. It means an issuer attested to one attribute, which is a much smaller claim. - **DO** Search across the name, the handle and the note. Users search for how they think of someone, which is rarely the exact stored name. - **DO** Order by recently paid rather than alphabetically. A wallet's contact list is short and heavily weighted to a handful of people. - **DON'T** Import the phone's address book by default. It is a large privacy ask for a feature most users do not need on day one, and it takes names out of the wallet's control. - **DO** _(Costs trust)_ Name what is lost in the confirmation: the saved key, and therefore the warning if it changes. Payment history stays. - **DON'T** Remove payment history when a contact is deleted. The money moved; that is a fact about the user's finances, not about the contact. - **DO** Keep them in separate lists but make them feel related. What a user does with a person is pay them; what they do with an app is review and revoke what it may do. Those are different enough that one combined list serves neither. See Security.