UDA endpoints — payments

How to call the payment routes. The formal schema is the OpenAPI specification (openapi/source/connector/payments/); 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). The payment body is ISO-20022 (pain.001) shaped.

Method	Path	Code	Purpose
GET	/v1/payments/bpay/biller/{billerCode}	200	Get one BPAY biller
POST	/v1/payments/bpay/biller	200	Search BPAY billers ({ query })
GET	/v1/payments/bsb/{bsb}	200	Look up BSB details
POST	/v1/payments/payid/alias-lookup	200	Resolve a PayID alias
POST	/v1/payments/schemes	200	Resolve eligible NPP schemes for an issuer
POST	/v1/payments/validate	200	Validate a payment (dry run)
POST	/v1/payments	200	Initiate a payment (commits)

Notes for callers

• Validate then initiate. POST /v1/payments/validate is a dry run; POST /v1/payments commits. Both require paymentIdentification.instructionIdentification — it's the key linking the two phases, so send the same value to both (missing → 400). The validate call must run first and succeed, or initiate has no stored token (see the implementation notes).
• Payment type is inferred from the ISO-20022 hints you send (service level NURG + creditor-agent proprietary AUBSB→BSB transfer or AU_BPAY_BILLER_CODE→BPAY; instructionPriority: HIGH→NPP). A request that matches none is rejected 422.
• Execution date. A past requestedExecutionDate is rejected (412); a future date creates a scheduled payment; today is immediate. Immediate payments are balance-checked (412 on insufficient funds); scheduled ones are not.
• PayID alias lookup returns only the registered legal name of the resolved party plus the eligible payment services — never the underlying account number/BSB (see the implementation notes).
• Search BPAY returns [] when nothing matches (not a 404). GET biller / BSB return 404 when the specific code isn't found.

Errors

HTTP	Code	When
400	GEN000000	request body/params fail schema validation
400	PAY000005	missing instructionIdentification
400	PAY000007	invalid CRN for recurring payment (INVALID_CRN_FOR_RECURRING_PAYMENT)
403	PAY003001	the debtor account isn't owned by the caller (CUSTOMER_NOT_AUTHORIZED)
404	PAR004001	no party mapping for the caller (ClientAuthManager.getClientKey → PARTY_NOT_FOUND)
404	PAY004001	BSB not found
404	PAY004002	BPAY biller not found
404	PAY004003	PayID alias not found (PAYID_ALIAS_NOT_FOUND)
404	PAY004004	debtor account has no local mapping
404	PAY004008	PayID issuer not found (ISSUER_NOT_FOUND)
412	PAY012001 / PAY012002	execution date in the past / insufficient funds
422	PAY022002	initiate / validate: no stored payment token for the instructionIdentification (PAYMENT_TOKEN_NOT_FOUND)
422	PAY022004 / PAY022005 / PAY022006	missing BPAY / BBAN / NPP details for the inferred type
422	PAY022007	the request doesn't match a supported payment type (UNSUPPORTED_PAYMENT_TYPE)
422	PAY022001	scheduled initiate: ULTRACS returned no payment number
500	GEN100001	an unmapped ULTRACS fault (immediate payment calls have no error map at all; handleUltracsError falls back to DOWNSTREAM_CONNECTOR_ERROR)