# PIP-0013 · Payee check

A third FINDER question, asked of the holder when a payment is prepared — verify a name or display it masked. Never reveal the subject behind a key.

## Why

SONAR says which member holds a key. RESOLVER says what the destination accepts. A payer about to send still has a question neither answers: *is this the person I mean to pay?*

Instant-payment schemes all answer it. Pix shows the registered name before confirmation. SEPA Verification of Payee and UK Confirmation of Payee return *match*, *close match* or *no match* on a name the payer supplies. PATH answers nothing, by design: a routing answer never carries a name ([Privacy](/learn/privacy)). This PIP adds the check without putting the name in a routing answer.

## Three questions, two allowed

| Question | Example | |
|---|---|---|
| Verify | *Is this Alice Martin?* → `match` | Allowed |
| Display | *The holder is Alice M.* | Allowed, masked |
| Reveal | *Alice Martin, +33…, alice@…* | Never |

No mode of this PIP returns another identifier of the subject.

## The call

Served by the holding member, at its base URL. Never by the network.

```http
POST /api/path/v1/payee-check
```

```json
{
  "key": "path:4a91c2f7e8d3",
  "mode": "verify",
  "name": "Alice Martin",
  "context": { "request": "7fk2m9pq3vx8" },
  "nonce": "9f2c41a8b7e3"
}
```

| Field | Required | Rule |
|---|---|---|
| `key` | yes | A PATH address issued by the holder |
| `mode` | yes | `verify` or `display` |
| `name` | with `verify` | The name the payer expects. Absent with `display` |
| `context` | without a member credential | `request` or `instruction`: the reference of a payment request or payment instruction issued for `key` |
| `nonce` | yes | Bound into the signed answer |

A caller presents a member credential, or a `context` that shows it was handed something by the receiver. The resolver stays public. The payee check is not, and that is the reason the name lives here and not in the resolver.

## The answer

```json
{
  "kind": "payee_check",
  "key": "path:4a91c2f7e8d3",
  "requester": "member-a",
  "mode": "verify",
  "result": "close_match",
  "display_name": "Alice M.",
  "subject_type": "natural_person",
  "nonce": "9f2c41a8b7e3",
  "signed_at": "2026-10-05T10:00:00Z",
  "kid": "op_member_b_2026_01",
  "signature": "…"
}
```

| `result` | Meaning | `display_name` |
|---|---|---|
| `match` | The name matches the holder's record | Omitted |
| `close_match` | It nearly matches | The masked registered name |
| `no_match` | It does not match | Omitted |
| `unavailable` | The holder does not answer for this key | Omitted |
| `shown` | `display` mode | The masked registered name |

Matching rules — accents, order of names, abbreviations — are the holder's, stated in its rulebook. PATH fixes the answer, not the algorithm.

**Masking.** For a natural person, the first given name and the initial of the family name. For a legal entity, the registered name. A holder may mask more. It may not mask less.

**`unavailable` is a valid answer.** The subject may have opted out, the jurisdiction may forbid it, the holder may not offer the check. It is never an inference, and a payer reads it as *not checked*, not as *wrong*.

## Rules

- The answer is signed by the holder. It binds `key`, `requester`, `mode`, `result` and `nonce`. It is replay-safe and opposable in a dispute: *the holder told us `match`*.
- The network never sees the name and never relays the check.
- Calls are budgeted per requester and logged with the key hashed, as for SONAR. The number of different names a requester may submit for one key is limited.
- The check is made when a payment is prepared. Never when an address book is imported.
- No other identifier, no account details, no KYC level, no balance, in any mode.

## Profile

`PATH-FINDER.PayeeCheck` is added to the conformance register: serve the call above, honour both modes, sign every answer, never return another identifier.

## External networks

The same two modes apply to external registries through [Crossway](/docs/crossway#payee-check) ([PIP-0014](/pips/0014)). An external scheme that offers less is reported as less.

## Compatibility

Additive. Resolver answers are unchanged and still never carry a name. A member that does not serve the call is not in breach of any existing profile.

## Implementation

The reference implementation serves `POST /payee-check` and declares `PATH-FINDER.PayeeCheck`. The registered name is read from `payee_records`, kept apart from the subject and set with `PUT /subjects/{id}/payee-record`. Every check is journaled against its requester, with the proposed name hashed, never in the clear. For a call carried by a context, `requester` is `request:<reference>` or `instruction:<reference>`. Matching rules and budgets are in the [API reference](/api-reference/transverse/finder/payee-check).