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.

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

FieldValue
nThe network: mainnet, testnet or regtest.Always
pThe 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
kThe 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
aThe amount asked, in satoshis: a whole number from 1 to 2,100,000,000,000,000. 100,000,000 satoshis are 1 BSV.Optional
mA note for the payment, up to 100 characters. A longer note is cut.Optional
wThe payee's wallet to pay into: up to 64 letters, digits, _ or -. Without it, the payment goes into the payee's active wallet.Optional
wlThe name of that wallet, up to 40 characters, shown to the payer. Read only with w.Optional
rA payment reference.Optional
sThe 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
dYour 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:

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.

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": "…"
    }
  ]
}

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.

QR codes

Encode the whole link as text in the QR code. The SpiffyVault scanner and a phone's camera both read it.

What the payer sees

Rules