Basic

Payment links

A payment link asks a wallet for a payment. ZIP 321 sets the format. The link holds the address, the amount and a memo. A QR code of the link lets a phone wallet read it.

Use

• a checkout page of a shop;
• an invoice;
• a donation button.

Put the order number in the memo. When the payment arrives, the shop reads the memo and finds the order.

Mechanism

zcash:address?amount=ZEC&memo=base64url&label=text&message=text

address

The address of the recipient. Use a shielded address.

amount

The value in ZEC, with 8 decimal places or fewer. For example, 0.25.

memo

The memo bytes in base64url, 512 bytes or fewer. Only a shielded address can receive a memo.

label

A name for the recipient. The wallet shows it to the payer.

message

A note for the payer. The wallet shows it to the payer.

The label and the message stay in the wallet of the payer. The memo goes on the chain, in the note ciphertext. The URI encodes the label and the message with percent escapes.

A shop uses this sequence:

1. The shop makes an address for the order. See Address per customer.
2. The shop writes the URI with the amount and the order number in the memo.
3. The shop shows the URI as a link and as a QR code.
4. The wallet of the payer shows the address, the amount and the memo. The payer approves the payment.
5. The shop finds the payment with its viewing key. See Watch-only keys.

A request can hold more than one payment. Each added payment puts an index on its names, for example amount.1.

Limits

• Amounts. The amount is a request. Some wallets let the payer change it. The shop must compare the value of the note with the order.
• Memos. Some wallets change binary memos and control characters. Use one line of printable ASCII.
• Many payments. Some wallets refuse a request with a second payment or a zero amount. Use one payment in each request.
• Privacy. The URI is plain text. A person who sees the link or the QR code sees the address, the amount and the memo.
• Phishing. Anyone can make a link to a different address. Show links only on pages that you control.

Wallet-native orders uses payment links to send app orders.

Demo: a shop link

The demo uses the zip321 crate, compiled to WebAssembly. It writes the URI and draws the QR code. The address is address 0 of the demo shop on the other basics pages.