Skip to main content
POST
Check a payee name

What this endpoint does

Checks the name you hold for an AUD bank account against the name the receiving bank has registered (type: bank_account), or resolves a PayID to the name it is registered to (type: payid).

When to use it

Call it before you save an AUD payout destination, or use the payeeCheck field on off-ramp route and Treasury beneficiary creation to run the check in the same request. Pass the returned id as payeeCheck.checkId there to reuse this check instead of paying for a second one.

Before you call

Use a secret API key with payees:write. Confirmation of Payee must be enabled for your account by Wayex; otherwise the request is refused with 403 confirmation_of_payee_not_enabled. A name with fewer than two printable characters, or details that fail validation, are refused with 400 before anything is checked.

Money and balance effect

This moves no money. Each answered check — any result, including no_match and not_found — is billed per your fee schedule on your monthly invoice (default AUD 0.40 per check, plus GST if your account is charged GST); fee.amount is what this check was charged. Refused and failed checks (400, 403, 422 payee_details_invalid, 429 payee_check_limit_reached, 502, 503 payee_check_unavailable) are not billed.

States and completion

The check is complete when it is returned; there is no later update or webhook. A non-match is still an answer: branch on result and confirmed (true for match and close_match), and show message as returned. For a PayID, displayName is the name it is registered to; the linked bank account is never returned.

Safe retries

Send a unique Idempotency-Key per check. If the response is lost, or you receive 502, retry the same payload with the same key: a retry returns the original check and never bills twice. A new key runs, and bills, a new check. Read Confirm payee for the complete workflow.

Authorizations

Authorization
string
header
required

Send the same Wayex API key as Authorization: Bearer <key>.

Headers

Idempotency-Key
string
required

A unique key for this logical action. Reuse the same key and identical payload when retrying after an unknown response.

Required string length: 8 - 255

Body

application/json
type
enum<string>
required

Check the name on an AUD bank account.

Available options:
bank_account
bsb
string
required

The 6-digit BSB of the account to check (NNNNNN or NNN-NNN).

Pattern: ^\d{3}-?\d{3}$
accountNumber
string
required

The account number to check (1-9 digits).

Pattern: ^\d{1,9}$
accountName
string
required

The account holder name to check against the registered name (2-140 characters).

Required string length: 2 - 140

Response

The check result.

id
string
required

The payee check id (pchk_ + 32 hex characters).

Pattern: ^pchk_[0-9a-f]{32}$
type
enum<string>
required

What is checked: an AUD bank account (BSB + account number + name) or a PayID.

Available options:
bank_account,
payid
result
enum<string>
required

The outcome of the check: match (the name matches), close_match (the name is close to the registered name), no_match (the name does not match), not_found (no such account or PayID) or closed (the account is closed). A resolved PayID is match.

Available options:
match,
close_match,
no_match,
not_found,
closed
message
string
required

The result message to show the user, as supplied. Show it as is.

Minimum string length: 1
confirmed
boolean
required

True when result is match or close_match. An unconfirmed check needs acceptMismatch: true to be used on a payment route or beneficiary.

fee
object
required

The fee charged for this check, billed on your monthly invoice.

createdAt
string<date-time>
required

When the check was run.

bankAccount
object

The bank account checked. Present when type is bank_account.

payId
object

The PayID resolved. Present when type is payid.

indicator
enum<string>

The icon to show with the result: tick (confirmed), warning (close match), cross (not confirmed) or dash (no answer about the name).

Available options:
tick,
warning,
cross,
dash
displayName
string

The registered name, when the receiving institution permits it to be shown (for a PayID, the name it is registered to).

Minimum string length: 1