# Payment requests

> Issue an invoice-style request and have incoming private payments match themselves to it.

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

```mermaid
sequenceDiagram
    participant Recipient
    participant Payer
    participant PoolVault

    Note over Recipient: generates the request(paymentId, tag, paymentPubKey)
    Recipient->>Payer: payment request (secure channel)
    Note over Payer: builds a transfer encrypted topaymentPubKey, hint set to the tag
    Payer->>PoolVault: transact
    PoolVault-->>Recipient: Note event (hint = tag)
    Note over Recipient: tag matches an open request:decrypts and marks it fulfilled
```

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](/concepts/keys) 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](/operations/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](relaying)).
4.  **Match.** On the receive side, [discovery](/operations/manage-notes) 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](../operations/create-payment-request): generate and share the request artifact.
-   [Discover incoming payments by paymentId](../operations/discover-by-paymentid): how matching and fulfillment work in practice.
-   [Encrypt a note to a published viewing key](../operations/encrypt-to-pubkey): the encryption mechanism requests are built on.