Platform endpoints — payments
How to call the payments routes. The formal schema is the OpenAPI specification
(openapi/source/platform/payments/payments.yml); this page is the call
contract. The payment journeys are in payment lifecycle.
All routes require a bearer token (B2B JWT) with CLIENT role and an ACTIVE party.
Global /v1 prefix applies.
Route summary
| Method | Path | Code | Purpose |
|---|---|---|---|
GET | /v1/payments/bpay/biller/:billerCode | 200 | Look up a BPAY biller by code |
POST | /v1/payments/bpay/biller | 200 | Search BPAY billers by criteria |
GET | /v1/payments/bsb/:bsb | 200 | Look up a BSB |
POST | /v1/payments/payid/alias-lookup | 200 | Resolve a PayID alias |
POST | /v1/payments/schemes | 200 | Resolve supported payment schemes for a financial institution |
POST | /v1/payments/validate | 200 | Validate a payment without persisting it |
POST | /v1/payments | 201 | Initiate a payment |
Route details
GET /v1/payments/bpay/biller/:billerCode — BPAY biller lookup
Looks up a biller by its code across the configured providers — the biller directory is distributed, so the platform tries each provider before giving up.
Path parameter: billerCode (string).
Errors:
| HTTP | Code | When |
|---|---|---|
404 | PAY004002 | Biller not found at any provider |
500 | PAY100003 | Core banking unavailable |
POST /v1/payments/bpay/biller — BPAY biller search
Searches billers by name or other criteria. Same across-providers search as the lookup variant.
Body: SearchBpayBillerBody — see OAS for fields.
GET /v1/payments/bsb/:bsb — BSB lookup
Returns financial institution details for a BSB. A 4xx response (e.g. BSB not
found) is authoritative and returned as-is; only transient transport failures are
retried before the request fails.
Path parameter: bsb (string, BSB number).
Errors:
| HTTP | Code | When |
|---|---|---|
404 | PAY004001 | BSB not found |
POST /v1/payments/payid/alias-lookup — PayID alias lookup
Resolves a PayID alias to its account holder. A 4xx is authoritative; only
transient transport failures are retried. The platform forwards the provider's
response unchanged, including party.name (the alias account name).
Body: AliasLookupBody — alias type + value; see OAS.
Errors:
| HTTP | Code | When |
|---|---|---|
404 | PAY004003 | PayID alias not found |
POST /v1/payments/schemes — resolve payment schemes
Validates a financial institution identifier and returns the payment schemes
supported for a BSB/account combination (NPP, OSKO, DE, etc.). Required
pre-flight before initiating a domestic transfer. A 4xx is authoritative; only
transient transport failures are retried.
Body: IssuerValidationBody — financial institution identifier; see OAS.
POST /v1/payments/validate — validate payment
Validates payment details before initiation. Persists nothing. Validate and
initiate must carry the same accountArkId in the body so both are handled by the
same backing provider — a provider may hold pre-flight session state from validate
that initiate relies on.
The debtor account Ark id is read from
paymentInformation[0].debtorAccount.identification.other.identification.
Absent → 400 before the provider is consulted.
A 4xx is authoritative; only transient transport failures are retried.
Body: ISO 20022 payment body — see OAS for the full BPAY / DE / NPP variant table.
Errors:
| HTTP | Code | When |
|---|---|---|
400 | — | Missing debtorAccount account id in body |
400 | GEN000000 | Body fails schema validation |
404 | PAY004004 | Account not found |
412 | PAY012001 | Invalid execution date |
412 | PAY012002 | Insufficient funds |
500 | PAY100003 | Core banking unavailable |
POST /v1/payments — initiate payment (201)
Initiates the payment. The platform reads accountArkId from the body so initiate
is handled by the same backing provider as validate (which may hold session state
from the validate call).
Missing instructionIdentification → 400. Note this is validated after the payment is
initiated at the provider (the field is optional in the request schema), so omitting it can leave
a payment initiated at the provider that the platform cannot correlate afterwards — always send it.
The response is PaymentResponsePlatformApi enriched with vendorId
(= instructionIdentification).
Scheduled payments are created via this same endpoint using a future
requestedExecutionDate — there is no separate schedule endpoint on the
platform.
Body: ISO 20022 payment body (same shape as validate); see OAS.
Errors:
| HTTP | Code | When |
|---|---|---|
400 | — | Missing debtorAccount or instructionIdentification in body |
400 | GEN000000 | Body fails schema validation |
404 | PAY004004 | Account not found |
412 | PAY012001 | Invalid execution date |
412 | PAY012002 | Insufficient funds |
500 | PAY100003 | Core banking unavailable |
Auth
All routes: bearer token (B2B JWT) with CLIENT role; party must be ACTIVE.