Developers · Payment links
Payment links and QR codes
Every SpiffyVault user has a payment link. Put it on your page, in an invoice or in a QR code, with an amount and a note if you want, and a SpiffyVault user can pay it in two taps. You need no server and no API key.
The link
https://spiffyvault.net/pay?n=testnet&p=12D3KooW…&k=02…&a=25000&m=Order%201042
The payee gets their link from the app: Get paid shows it as a QR code for Who will scan it? › SpiffyVault, and Share link sends it as text. The app signs the links it makes (s), so use a link from the app as it is. To set your own amount, see Ask for an amount.
The app also reads the same query with the spiffyvault://pay?… scheme. Use the https form: it opens the app where SpiffyVault is installed, and a page that explains what to do where it is not.
Fields
| Field | Value | |
|---|---|---|
n | The network: mainnet, testnet or regtest. | Always |
p | The payee's peer ID (12D3KooW…). The payer's app pays it directly, with proof, and leaves the payment in the payee's mailbox when they are offline. | At least one of p and k |
k | The payee's BRC-100 payment key: 66 hex characters, starting with 02 or 03. Used when the direct payment fails, and by wallets that have only the key. | At least one of p and k |
a | The amount asked, in satoshis: a whole number from 1 to 2,100,000,000,000,000. 100,000,000 satoshis are 1 BSV. | Optional |
m | A note for the payment, up to 100 characters. A longer note is cut. | Optional |
w | The payee's wallet to pay into: up to 64 letters, digits, _ or -. Without it, the payment goes into the payee's active wallet. | Optional |
wl | The name of that wallet, up to 40 characters, shown to the payer. Read only with w. | Optional |
r | A payment reference. | Optional |
s | The payee's signature over all the other fields. The app adds it to the links it makes. Leave it out of a link you change. | Optional |
d | Your website's domain, such as shop.example: a host name only, in lower case, with no https://, port or path. The payer's app pays only if your website lists the payee. | Optional |
Encode each value as a URL query value: a space is %20, and so on.
Ask for an amount
With a, the payer sees the amount and cannot change it. Without a, the payer types an amount. The note from m fills in the payment's note, and the payer can change it.
Use a signed link, so that a payer's app refuses the link if anyone changes the amount or the payee. There are three ways to get one:
- In the app, with Get paid › Ask for an amount.
- From an AI agent, with
request_payment. - From a server that holds the payee's key, with
signPaymentLink()in@spiffyvault/payments. This is how a shop sets its own prices.
import { formatPaymentLink, signPaymentLink } from '@spiffyvault/payments';
const link = formatPaymentLink(await signPaymentLink({
network: 'testnet',
peerId: '12D3KooW…', // the payee's peer ID
paymentKey: '02…', // and payment key
amountSats: 25000,
memo: 'Order 1042',
domain: 'shop.example', // if your website vouches for the payee
}, peerKey)); // the libp2p Ed25519 key of that peer ID
Without the payee's key, you can still write the link yourself. Copy n, p, k and, if present, w, wl and d from the payee's link, leave out s, and add your own a and m. Such a link has no signature, so the payer's app cannot tell that it was changed. Add d, so that at least a changed payee is refused.
Payment references
A payment request has a reference: 8 characters from 0123456789ABCDEFGHJKMNPQRSTVWXYZ, for example K7Q2M9XD. With r=K7Q2M9XD in the link, the payer's app puts ref K7Q2M9XD in the payment's note. The payee's SpiffyVault uses the reference to send the payment into the request's wallet and to mark the request as paid.
- Use only a reference that the payee's SpiffyVault made. An AI agent makes one with
request_payment, and gets the full link back. - A link with
rdoes not needw: the payee's app knows which wallet each reference belongs to. - Only the reference counts. A payment of the same amount without the reference does not pay the request.
Link your website
Anyone who can change a link can change who it pays. With d, your website vouches for the payee: the payer's app reads a file from your website and refuses to pay unless the file lists the link's payee. Payers then see your domain on the payment screen.
The payee makes the file in SpiffyVault, in Your website › Link a website. On a phone, Your website is under your picture at the top of the home screen, in Identity & keys. On a computer, it is in Identities. Type the domain and, if you want, the name payers see. Then copy the file, put it on your website, and tap Check my website. When the check passes, every payment link the app makes names your domain.
Serve the file at https://<domain>/.well-known/spiffyvault.json, over HTTPS, with status 200 and no redirect. It must be at most 16 KiB. For web wallets that check it in a browser, also send Access-Control-Allow-Origin: *.
{
"version": 1,
"payees": [
{
"peerId": "12D3KooW…",
"paymentKey": "02…",
"networks": ["mainnet"],
"name": "Corner Shop",
"sig": "…"
}
]
}
- List one entry for each payee your website vouches for.
paymentKeyandnameare optional;nameis cut to 60 characters. sigis the payee's Ed25519 signature, in hex, made with the key in their peer ID, over the UTF-8 textspiffyvault-domain/1 <domain> <peerId> <paymentKey or -> <networks, joined with ,>. The payment key is in lower case, and the networks aremainnet,testnetorregtest.- The signature names the domain, so an entry copied to another website does not check, and an edited entry does not check. Only the payee can make their entry.
- From a server, make the file with
domainEntry()in@spiffyvault/payments. It writes the same entry as the app for the same key.
The payer's app refuses the link when the file is missing or cannot be read, when the payee is not listed, when the link's payment key is not the listed one, when the payee is listed for another network, or when the entry's signature does not check. When your website cannot be reached, the app offers to try again; it does not pay without the check. spiffyvault.net/pay shows the same answer to a payer who opens the link in a browser.
Signed links
The links SpiffyVault makes carry s, the payee's signature over every other field, amount and note included. The payer's app checks it. If anyone changed the link after the payee made it, the app refuses to pay and says the link was changed. spiffyvault.net/pay shows the same warning.
- A signature shows that the link was not changed, not who the payee is. Someone can sign a link to themselves. The payer knows the payee from their contacts, or from your website.
- A link without
sis still paid, but the payer's app pays only the peer ID inp. It offers the payment key inkas the way to pay when the direct payment fails only for a signed link, since only the signature ties the key to the peer ID. sis an Ed25519 signature, by the key in the peer ID, in base64url without padding (86 characters). It signs the UTF-8 textspiffyvault-link/1followed by one line for each field, in the ordern,p,k,a,m,w,wl,r,d, written asn=mainnetand so on, with an empty value for a field the link does not have. The lines are joined with a line feed, and the values are as the app reads them: the network asmainnet,testnetorregtest, the key in lower case, the note and wallet name without control characters or invisible format characters (such as right-to-left overrides and zero-width spaces), with runs of spaces made one, and cut to length.- From a server that holds the payee's key, sign a link with
signPaymentLink()in@spiffyvault/payments. It makes the same signature as the app. - A signed link does not expire. Anyone who has it can pay it again, at its amount, for as long as the payee's key is the same. If you set prices, give each order its own link with a payment reference in
r, and on your server check that the payment for that reference has the amount you expect before you hand over the goods.
QR codes
Encode the whole link as text in the QR code. The SpiffyVault scanner and a phone's camera both read it.
- Error correction level M is enough. A link with a long note and a wallet name can be up to about 400 characters, so test the size you print.
- Leave a quiet zone of four modules around the code, and show dark modules on a light background.
- Under the code, show the amount and who is paid, in words. The payer checks them in the app, too.
What the payer sees
- With SpiffyVault: the link opens the app at the payment screen, with the payee, the amount, the note and, with
wl, the wallet name. Withd, it shows whether your website confirms the payee. The payer taps to pay. - Without SpiffyVault: the link opens spiffyvault.net/pay, which explains how to get the app and pay, and with
dchecks your website too.
Rules
- SpiffyVault refuses a link with an unknown network, a bad peer ID or payment key, or an amount that is not a whole positive number of satoshis. It does not try to guess.
- A wallet on one network refuses a link for another network. Make testnet links for testing, and mainnet links only for real payments.
- A link is not secret: it holds only public keys. But anyone who changes it can send the payment to themselves, so serve your page over HTTPS, and link your website so a changed link is refused.
- A link with a
dthat is not a plain domain is refused as broken, and so is ansthat is not 86 characters or comes withoutp. - A signed link whose signature does not match its fields is refused: it was changed.