PAYEE CHECK

Step 3 of reachability — verify a name, or display it masked, before sending. Answered by the holder, behind a payment context or a member credential.

LIVE — PIP-0013. PATH-FINDER.PayeeCheck is declared in discovery.

Answers is this destination the person I think. Served by the holding member, at its base URL. The network never sees the name.

Requires a payment context. A member credential (see Authentication), or the reference of a payment request or payment instruction issued for the key.

`POST /payee-check`

POST /api/path/v1/payee-check
Path-Version: 2026-10-04.genesis

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

Field	Required	Notes
`key`	yes	A PATH address issued by the holder
`mode`	yes	`verify` or `display`
`name`	with `verify`	The name the payer expects
`context`	without a credential	`{ "request": … }` or `{ "instruction": … }`, issued for `key`
`nonce`	yes	Bound into the signed answer

Response

{
  "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`	`display_name`
`match`	Omitted
`close_match`	The masked registered name
`no_match`	Omitted
`unavailable`	Omitted. Not checked — never wrong
`shown`	The masked registered name (`display` mode)

requester is the authenticated member's slug, or request:<reference> / instruction:<reference> when the call was carried by a context. It is inside the signature.

A context must name an open request or instruction issued for key: not paid, not revoked, not expired. Any other reference is refused.

Matching

The holder's rules, stated here for this implementation:

Proposed vs registered	Result
The same words, in any order, ignoring case, accents, punctuation and courtesy titles	`match`
Every proposed word stands for a registered one — an initial, one typo on a word of four letters or more, a missing middle name — with at least two words agreeing	`close_match`
Anything else	`no_match`

For a legal entity, legal forms (S.A., Ltd, GmbH, …) are ignored. The masked name is the first given name and the family-name initial for a person, the registered name for an entity.

Each requester holds an allowance: per day with a member credential, over its life with a payment context. The number of different names submitted for one address is limited; resubmitting the same name does not count again. Check a name when a payment is being prepared.

What it never returns

Any other identifier of the subject, account details, a KYC level, a balance.

Errors

Code	Status	Meaning
`path.auth.unauthenticated`	401	No valid credential and no `context`
`path.core.not_found`	404	No such address at this holder
`path.address.revoked`	410	The address was revoked
`path.finder.budget_exhausted`	429	Payee-check allowance spent

`PUT /subjects/{id}/payee-record`

Sets the name the payee check reads. Member credential, local member only.

{ "registered_name": "Alice Marie Martin", "payee_check": "enabled" }

Kept apart from the subject, which carries no personal data. In production this is the member's own system; the reference implementation stores it in payee_records. payee_check: "disabled" makes every check on the subject's addresses answer unavailable. The name is not echoed back in the response.