# PIP-0010 · Payment requests and checkout in the common vocabulary

Typed amounts, accepts bound to the payee's standing intent, fees and quotes per capability, and a request that names the receipts that settled it.

## Why

A payment request is a claim: what is owed, to whom, until when. In 0.3 its amount is a bare string beside `currency`, its `accepts` is free-form and independent of the payee's address, its `fees` is one block for every capability, and `paid` names no receipt. This PIP restates the request in the vocabulary of [PIP-0006](/pips/0006).

## The object

```json
{
  "type": "path.request",
  "reference": "7fk2m9pq3vx8",
  "issuer": "member-a",
  "payee": { "member": "member-a", "address": "path:4a91c2f7e8d3" },
  "amount": { "value": "5000", "asset_type": "fiat", "asset_code": "USD" },
  "accepts": [
    {
      "rail": "book",
      "asset_type": "fiat",
      "asset_code": "USD",
      "fees": []
    },
    {
      "rail": "blockchain",
      "chain": { "slug": "base", "caip2": "eip155:8453" },
      "asset_type": "token",
      "asset_code": "USDC",
      "standard": "erc20",
      "contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "quote": {
        "amount": { "value": "7.62", "asset_type": "token", "asset_code": "USDC" },
        "rate": "0.001524",
        "source": "operator_quote",
        "expires_at": "2026-10-04T18:05:00Z"
      },
      "fees": [
        {
          "kind": "network",
          "amount": { "value": "0.01", "asset_type": "token", "asset_code": "USDC" },
          "paid_by": "payer"
        }
      ]
    }
  ],
  "intent_version": 4,
  "order_reference": "ord_10482",
  "status": "created",
  "settled_by": [],
  "expires_at": "2026-10-10T10:00:00Z",
  "grammar": 2
}
```

## Rules

| Field | Rule |
|---|---|
| `payee` | Present. `payee.address` is present when the request is issued against an address. |
| `amount` | An Amount, or `null` when the payer chooses. `currency` is not part of this grammar. |
| `accepts[]` | Capabilities, frozen at issue. When `payee.address` is present, each entry exists in the standing intent named by `intent_version`. Otherwise each entry is checked against the registers ([PIP-0007](/pips/0007)). |
| `accepts[].fees` | Fees on this capability, as Fee objects. The request-level `fees` is not part of this grammar. |
| `accepts[].quote` | Required when the capability's asset differs from `amount`'s. States what the payer sends on this capability, at what rate, until `expires_at`. Without a valid quote, a wallet does not show an amount for that capability. |
| `status` | `created`, `paid`, `expired`, `revoked`. Unchanged. |
| `settled_by` | References of receipts in `settled` that cover this request. `paid` requires at least one. |

A request carries no title, description or memo. The issuer's verified name comes from the member register.

## Amounts received

Partial payments remain reserved. Until a PIP specifies them:

- The amounts of receipts in `settled_by` are compared in the asset of `amount`, using each receipt's `received`.
- A request moves to `paid` when the receipts it lists cover `amount`. Below that, it stays `created`, and `settled_by` lists what arrived.
- An amount above `amount` moves the request to `paid`. Refund of the excess is reserved.
- A request with `amount: null` moves to `paid` on its first settled receipt.

## Checkout sessions

A session carries the request's `amount` and `accepts` in this grammar.

| Change | From | To |
|---|---|---|
| Withdrawn by the merchant | `cancelled` | `revoked` |
| Attempts | a counter and the last `payer_member` | one record per attempt: member, time, capability chosen, instruction obtained |

`completed` still means the wallet handed the payer back. It is not `paid`, and it does not move the request.

## Payment

A wallet that pays a request obtains a [payment instruction](/pips/0009) for one entry of `accepts`, sends, and receives or retrieves the receipt. The request lists that receipt in `settled_by`.

## Compatibility

Breaking for readers of `amount`, `currency`, `accepts` and `fees` on `path.request` and `path.checkout`, and for readers of checkout `cancelled`. Requests signed in the 0.3 shape are served as signed.