Payment requests

A payment request lets one party ask another for a specific payment and receive it without either side revealing their wallet address. The recipient generates a shareable request carrying a payment identifier, a public tag derived from it, and a per-request encryption key, then hands it to the payer over a secure channel. The payer pays through a relayer, and when the payment lands the recipient's client matches it to the request automatically.

How a payment request works

A request moves through four stages:

1. Generate. The recipient creates the request. It carries a payment identifier (paymentId) that names it, a public tag (a hash of that identifier) that will mark the payment on-chain, and a per-request key derived from the recipient's viewing key and the identifier.
2. Share. The recipient hands the request to the payer over a secure channel.
3. Pay. The payer sends an ordinary transfer encrypted to the per-request key, with the tag written as the Note event's public hint. Because it is encrypted to that key, only the holder of the original request can read it, and fulfillment relays like any other transfer (see Relaying).
4. Match. On the receive side, discovery compares incoming Note hints against the recipient's open requests, decrypts the matches with each request's key, and marks them fulfilled. The tag narrows the candidate set before any decryption, so matching stays cheap even against a long event history.

The protocol does not authenticate tags. Any sender who has seen a tag can stamp a payment with it, so a matched payment proves that money arrived against this request, not who sent it. Pair requests with an off-chain signature when you need non-repudiation.

In this group

• Create a payment request: generate and share the request artifact.
• Discover incoming payments by paymentId: how matching and fulfillment work in practice.
• Encrypt a note to a published viewing key: the encryption mechanism requests are built on.