UDA endpoints — payees

How to call the payee routes. The formal schema is the OpenAPI specification (openapi/source/connector/payees/); this page is the call contract. Internal processing is in the architecture reference; caveats in the implementation notes.

All routes require a bearer token and party context (partyId). payeeId in the path is the Ark payee id.

Method	Path	Code	Purpose
GET	/v1/payees	200	List the party's payees
GET	/v1/payees/{payeeId}	200	Payee detail
POST	/v1/payees	201	Register a payee
DELETE	/v1/payees/{payeeId}	204	Remove a payee

Notes for callers

• Register (POST /v1/payees) supports type DOMESTIC (an account or a payId) and BILLER (BPAY). INTERNATIONAL and DIGITAL_WALLET are not implemented and fail with 500 (see the implementation notes). A duplicate of an existing payee (same type + identifier) is rejected with 409.
• PayID format: for EMAIL and TELEPHONE PayIDs the identifier is format-validated (400 on a bad value); ABN/ORG_IDENTIFIER are not. The connector does not verify that a PayID resolves to a real account, nor that a biller's CRN format is valid, at registration time (see the implementation notes).
• creationDate in a payee detail/list response is the date the connector first recorded the payee locally, not necessarily when it was created in the core system (see the implementation notes).
• Transfer payees without a BSB from the core system are reported with a default BSB of 923000 (see the implementation notes).
• Delete removes the payee from both the local store and the core system atomically.

Errors

HTTP	Code	When
400	GEN000000	request body/params fail schema validation
400	PAE400003	invalid PayID identifier format (EMAIL/TELEPHONE)
400	PAE100003	ULTRACS reports the payee number was not found
403	PAE003001	the payee isn't owned by the caller (PAYEE_UNAUTHORIZED)
404	PAR004001	no party mapping for the caller (ClientAuthManager.getClientKey → PARTY_NOT_FOUND)
404	PAE004001	no payee mapping for payeeId
409	PAE009001	register: a matching payee already exists
500	PAE100001	unsupported payee type, or an unmappable ULTRACS payee shape
500	GEN100001	an unmapped ULTRACS fault (handleUltracsError falls back to DOWNSTREAM_CONNECTOR_ERROR)