An AUD payout debits the current tenant account’s prefunded AUD wallet and pays one saved beneficiary
through their BSB/account details. The beneficiary, fees, limits, and evidence policy all belong
to that same isolated account.
Before you create a beneficiary
Collect the recipient information required for the party type:
- First and last name - Date of birth - Residential address - The payout destination: a bank
account (BSB, account number, and account name) or a PayID (email, phone, or ABN, with an
account name) - Downstream merchant or wallet-provider references when available - Optional
Sumsub share token when available or required by policy
- Legal business name - Business identifiers you hold for the recipient (ABN, registration
number, and similar), supplied in the optional
businessIdentity map - The payout destination:
a bank account (BSB, account number, and account name) or a PayID (email, phone, or ABN,
with an account name) - Downstream merchant or wallet-provider references when available -
Optional Sumsub share token when available or required by policy
externalReference is optional. Supply a stable identifier only when you already use one to match
the recipient in your system; otherwise Wayex generates and returns one. Do not put secrets or
unnecessary personal information in reference, purpose, or metadata fields.
The free-form maps on these requests — partyContext, businessIdentity, and glMapping — accept
your own key names with one exception: @@wxtype (and any @@wxtype.esc… variant) is reserved by
Wayex, and a map containing it is refused with 400 invalid_request. See
Reserved metadata key.
Create a beneficiary
This individual example uses BSB/account details. The API key binds the request to the correct tenant
account and its settings, so no business-line selector is needed.
Omit sumsub when no token is available and the account policy does not require it. You may also
supply an optional externalReference or sumsub.externalReference when your system already has a
stable reconciliation identifier; Wayex generates the missing references.
Use GET /v1/treasury/beneficiaries/{id} before payout review when you need the current status.
Deactivate a beneficiary with POST /v1/treasury/beneficiaries/{id}/deactivate when it should no
longer receive new payouts. Historical payouts keep the beneficiary snapshot they used.
Pay a PayID instead of a bank account
A beneficiary’s AUD payout destination can be a PayID rather than a bank account. Set
destination.type to payid and supply the payId, its payIdType (email, phone, or abn),
and an accountName. Everything else — party details, optional evidence, references — is unchanged.
Choose one destination type per beneficiary. To move an existing recipient from a bank account to a
PayID (or the reverse), create a new beneficiary with the new destination and deactivate the old one;
destinations are not edited in place.
Optional Sumsub evidence
The single-use Sumsub share token is optional unless the tenant account’s effective policy requires
it. Submit the token when creating the beneficiary. Wayex validates it, stores only the reusable
evidence result, and associates that result with the saved beneficiary. Payouts use the beneficiary’s
newest accepted, unexpired evidence automatically, or an explicit evidenceId when you need to
select a prior result.
Evidence expires. To refresh it for an existing beneficiary — for example after the previous result
expires — submit a new single-use token with POST /v1/treasury/sumsub-evidence, passing the
beneficiaryId, the shareToken, and an externalReference. The newest accepted, unexpired result
is then selected automatically for payouts. You do not need to recreate the beneficiary.
A Sumsub share token is input-only and single-use. Wayex sends it once for validation and never
stores, returns, or logs it. Keep it out of your database, analytics, webhook payloads, and
support notes.
Preview, review, and submit a payout
Preview the exact payout intent before asking the user to confirm it:
Show the returned principal, fee, sourceDebit, canProceed, and holdReason on the review
screen. Previewing does not reserve or send money. It can check an existing evidenceId, but it does
not accept a Sumsub share token. Tokens are submitted at beneficiary creation or to the evidence
endpoint — never on the payout request.
After confirmation, submit the logical payout with a different stable idempotency key:
The create request repeats all policy, balance, screening, and provider checks before it reserves
money. A successful preview does not guarantee that a later create will still be accepted.
Money you send is a bare decimal string (for example "250.00"). In payout and preview responses,
each money field is an object carrying a decimal-string amount and an explicit currency — for
example "fee": {"amount": "2.50", "currency": "AUD"}. The accepted operation response records the
authoritative:
- requested payout
amount;
fee;- total
sourceDebit reserved from the AUD wallet.
Payout remitter
Every AUD payout carries a remitter — the name the beneficiary sees as the payer on their bank
statement. Your tenant account has a default, and each payout may override it.
Read and set the account-wide default through the settings resource:
payoutRemitter accepts exactly two values — never free text:
GET /v1/treasury/settings returns the current payoutRemitter, the tenantRemitterName the
tenant option resolves to, and updatedAt. The onboarded company name itself comes from your
account profile and cannot be changed through this endpoint.
To override the default for a single payout, send an optional remitter (wayex or tenant) on the
create request. A new default applies only to payouts created after it is set — a payout’s recorded
remitter never changes retroactively, so the value stored on a payout can differ from the current
default.
What happens to the balance
Wayex returns accepted only after the full source debit is durably reserved. It can no longer back
another payout, conversion, or withdrawal. A later bank return follows the tenant account’s configured
return-loss and recovery policy and creates explicit wallet movements.
Payout states
Webhooks and safe retries
Subscribe to treasury.payout.updated. On each event, deduplicate by eventId and fetch the payout by
ID. Events can arrive more than once or out of order.
If the create response is lost, retry the identical body with the same Idempotency-Key. Do not use a
new key, change the external reference, or send another payout while the result is unknown. Fetch the
payout by its Wayex ID or stable external reference before taking another action.
Browse every beneficiary, evidence, and payout operation in the API reference. 
