Legacy compatibility
Older payment and wallet methods a BSV product may still meet, how they differ from the recommended approach, and how to design for each.
Some exchanges, older wallets and printed QR codes still use older ways to pay. A BSV product has to work with them, and this page says how to design for each without building new flows around them.
Not the recommended approach
This guide recommends the Wallet Application Interface and peer-to-peer payments as the default. The methods on this page are documented because real products meet them: exchanges, older wallets, existing integrations and users' own exit routes. Support them where needed, but don't design new flows around them.
Plain addresses (P2PKH)
What it is. The recipient shows an address or QR code. The sender broadcasts a transaction to it. The recipient's wallet finds the payment by watching the blockchain.
Where you'll meet it. Exchange deposits and withdrawals, older wallets, donation pages, printed QR codes.
Design implications:
- Detection is slower and less certain. The recipient only knows about a payment once it shows up on the network. Use "Incoming" or "Settling" rather than an instant "Paid".
- Address reuse leaks privacy. A static address groups every payment made to it. Generate a new receiving address for each request where you can, and explain why a donation address is public.
- Wrong-network risk is high. BSV and BTC legacy addresses look the same, since both start with "1".
Do
Show the network on every receive screen that shows a plain address, and warn on send when an address is pasted rather than picked.
Recommendation
Every consumer wallet should still be able to send to a plain address. It's the user's guaranteed exit if anything else in the stack fails. Label it clearly, for example Send to external wallet, and make sure it works without any vendor service.
Seed-only wallets (BIP-39, BIP-32, BIP-44)
What it is. Wallets that derive all keys from 12 or 24 recovery words in a fixed sequence. The words alone restore everything by scanning the chain. BSV uses coin type 236 in the BIP-44 path. Some early BSV wallets used coin type 0, which BTC also uses.
Where you'll meet it. Older BSV wallets, hardware devices, imports from other tools.
Design implications:
- Imports can look empty. Words from a coin-type-0 wallet entered into a coin-type-236 wallet, or the reverse, find nothing.
- Words are not portable between wallet families. Words from a seed-only wallet and BSV recovery words (BRC-75) look identical but derive different keys. Never imply a user can move words between the two.
- Migration is a payment. Moving funds into a modern BSV wallet means sending them, not importing the words.
Do
When an import of recovery words finds nothing, check the other derivation path before telling the user the wallet is empty.
Do
Move funds out of a seed-only wallet by sending them, not by importing its words.
Address-only Paymail
What it is. A Paymail handle that returns an address to pay, or accepts a raw transaction, without the full peer-to-peer exchange.
Where you'll meet it. Older Paymail providers and services that have not adopted the peer-to-peer flow.
Design implications. Handles still give users a readable name, but the confirmation is weaker than the peer-to-peer flow's acceptance reply. Show "Sent" rather than "Received by Anna" unless the service confirms receipt.
Direct Payment Protocol (DPP)
What it is. A protocol for payment requests from merchant to wallet: the merchant's server sends payment terms and the wallet returns the transaction.
Where you'll meet it. Some merchant and point-of-sale integrations.
Design implications. Treat it like an invoice. Show the merchant's name as the payment request states it, the amount and the expiry, and keep it consistent with your other checkout screens.
Supporting several methods
A wallet or merchant that supports more than one payment method shows the same review screen whichever method is used, and notes the method only in the transaction details, for support.
Do
Pick the payment method automatically, in this order: peer-to-peer, then address-only Paymail, then a plain address.
Don't
Ask the user to choose a payment protocol.
Open questions
- What, in a DPP request, can a wallet verify about the merchant?
Related
Written from: BSV protocol, BRC-151 §5, ts-stack Paymail package.
Checklist
The rules on this page, in a form you can work through.
6 rules