Skip to main content
POST
Create a Treasury beneficiary

What this endpoint does

Creates a reusable individual or business recipient whose AUD payout destination is either a bank account (BSB and account number) or a PayID (email, phone, or ABN) — each carries an account name — and can validate optional Sumsub evidence in the same request.

When to use it

Create the beneficiary before the first payout. Choose the destination.type your recipient uses (bank_account or payid). Supply externalReference only when your system already has a stable recipient identifier; otherwise Wayex generates one.

Before you call

Use a secret API key with treasury:write. Supply the required recipient and destination data. If a fresh end-client Sumsub share token is available or required by policy, send it in the input-only, single-use sumsub.shareToken field on this request. The free-form maps on this request — partyContext, businessIdentity, and glMapping — reserve one key name, @@wxtype (and any @@wxtype.esc… variant): a map containing it is refused with 400 invalid_request and nothing is written.

Money and balance effect

This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money.

States and completion

Creation does not guarantee a payout will pass current policy. Evidence, screening, limits, and balance are checked when the payout is submitted.

Safe retries

Send a unique Idempotency-Key for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read Beneficiaries and payouts 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
destination
object
required
type
enum<string>
required
Available options:
individual
firstName
string
required
Minimum string length: 1
lastName
string
required
Minimum string length: 1
dateOfBirth
string
required
address
string
required
Minimum string length: 1
partyContext
object

Optional free-form key/value metadata about the beneficiary party (e.g. your internal tags or travel-rule party context). Stored and returned; Wayex does not interpret the keys.

externalReference
string
Required string length: 1 - 512
sumsub
object

Response

201 - application/json
id
string
required
Minimum string length: 1
clientId
string
required
Minimum string length: 1
externalReference
string
required

Your own reference for this beneficiary, echoed back for correlation. Wayex generates one when you do not supply it at creation.

Minimum string length: 1
destination
object
required
status
enum<string>
required
Available options:
active,
inactive
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
type
enum<string>
required
Available options:
individual
firstName
string
required
Minimum string length: 1
lastName
string
required
Minimum string length: 1
dateOfBirth
string
required
address
string
required
Minimum string length: 1
partyContext
object

Optional free-form key/value metadata about the beneficiary party (e.g. your internal tags or travel-rule party context). Stored and returned; Wayex does not interpret the keys.

deactivatedAt
string<date-time>