# PIP-0009 · Payment instructions

A signed, short-lived object from the payee's member that gives the concrete destination for one payment on one capability.

## Why

ADDRESS answers *where to send, on what standing terms*. A standing intent and a resolver answer state what is accepted. Neither states the destination itself: an account, a wallet address, a remittance reference. A payer needs that to execute.

This PIP adds the object that does. It belongs to PATH ADDRESS. It is not a claim (PATH REQUEST) and not a proof (PATH SETTLEMENT).

| Object | States | Lifetime |
|---|---|---|
| Standing intent | What this address accepts | Permanent, versioned |
| Payment instruction | Where to send this payment, on this capability | Minutes to hours |
| Payment request | What is owed | Until paid, expired or revoked |
| Receipt | What happened | Permanent, chained |

## The object

```json
{
  "type": "path.instruction",
  "reference": "k3v9n2x8p4q7r1s6t0w5yz",
  "issuer": "member-a",
  "payee": { "member": "member-a", "address": "path:4a91c2f7e8d3" },
  "request": "7fk2m9pq3vx8",
  "intent_version": 4,
  "via": {
    "rail": "blockchain",
    "chain": { "slug": "base", "caip2": "eip155:8453" },
    "asset_type": "token",
    "asset_code": "USDC",
    "standard": "erc20",
    "contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
  },
  "beneficiary": { "format": "chain_address", "value": "0x…" },
  "payment_reference": null,
  "amount": { "value": "7.62", "asset_type": "token", "asset_code": "USDC" },
  "single_use": true,
  "status": "open",
  "expires_at": "2026-10-04T18:10:00Z",
  "grammar": 2
}
```

| Field | Rule |
|---|---|
| `payee` | The receiving party ([PIP-0006](/pips/0006)) |
| `request` | The request this instruction serves, or `null` |
| `intent_version` | The standing intent version `via` was taken from, or `null` when `via` was taken from a request |
| `via` | One capability, copied unchanged from the `accepts` in force: the address's standing intent, or the request's |
| `beneficiary` | `format` is one of the rail's `beneficiary_formats` ([PIP-0007](/pips/0007)). Further members are set by the rail's profile. |
| `payment_reference` | Required when the capability has `reference_required`. Otherwise `null` or a value the payer should attach. |
| `amount` | The amount to send when a request or a quote fixes it, otherwise `null` |
| `single_use` | `true` when the destination is dedicated to this payment |
| `status` | `open`, `used`, `expired`, `revoked` |
| `expires_at` | Required |

The object is signed like every PATH object. It is linkable at `/path/<reference>`.

## Obtaining one

```http
POST /api/path/v1/instructions
```

```json
{ "request": "7fk2m9pq3vx8", "via": { "…": "one entry of the request's accepts" } }
```

```json
{ "address": "path:4a91c2f7e8d3", "via": { "…": "one entry of the standing intent's accepts" } }
```

Served by the payee's member.

- For a **request**, no credential is required. The request's issuer has stated it accepts payment from whoever holds the request.
- For an **address** alone, a member credential is required. Each issuance is recorded by the payee's member.
- `via` must match an entry of the `accepts` in force. Otherwise the call fails with `path.instruction.capability_not_accepted`.
- The payee's member must hold a receive target serving `via`, on a rail with a beneficiary format ([PIP-0007](/pips/0007)). Otherwise the call fails with 409 `path.instruction.destination_unavailable`.

An instruction is never returned inside a resolver answer.

## Lifecycle

`open` → `used` when a receipt in `settled` cites it. `open` → `expired` at `expires_at`. `open` → `revoked` by its issuer. A `single_use` instruction that is `used` does not accept a second payment; a payment made after expiry is handled by the payee's member and recorded on its receipt.

Reading an instruction that is no longer `open` returns 410 with `path.instruction.expired`, `path.instruction.used` or `path.instruction.revoked`.

## Link to settlement

A receipt names the instruction it settles in `instruction` ([PIP-0011](/pips/0011)). Two receipts about one payment, one from each side, are matched by that reference and by `rail_references`.

## Conformance

`PATH-ADDR.Instruction`: issue, serve and expire instructions, enforce `via` against the `accepts` in force, require a credential for address-only issuance.

## Compatibility

Additive. A new object type, a new route, a new profile and five error codes.