Beneficiaries and payouts

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:

Individual
Business

First and last name - Date of birth - Residential address - BSB, account number, and 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.

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.

curl -X POST https://api.sandbox.wayex.com/v1/treasury/beneficiaries \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: beneficiary-transfer-aud-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "destination": {
      "type": "bank_account",
      "bsb": "062000",
      "accountNumber": "12345678",
      "accountName": "Ava Williams"
    },
    "firstName": "Ava",
    "lastName": "Williams",
    "dateOfBirth": "1991-05-14",
    "address": "100 Market Street, Sydney NSW 2000",
    "sumsub": {
      "shareToken": "<single-use-share-token>"
    },
    "partyContext": {
      "downstreamMerchantReference": "merchant-7842"
    }
}'

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.

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.

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.

If you provide a token, Wayex validates it and matches it to the beneficiary. Invalid, expired, mismatched, rejected, or temporarily unverifiable evidence is never silently ignored. If you omit it when policy allows omission, normal screening still applies.

Preview, review, and submit a payout

Preview the exact payout intent before asking the user to confirm it:

curl -X POST https://api.sandbox.wayex.com/v1/treasury/payouts/preview \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: payout-review-transfer-aud-001" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryId": "ben_123",
    "amount": "250.00",
    "currency": "AUD",
    "externalReference": "payout-9172",
    "purpose": "Customer withdrawal",
    "walletProviderReference": "transfer-wallet-au-01",
    "downstreamMerchantReference": "merchant-7842"
  }'

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 belong to beneficiary creation, not the payout request. After confirmation, submit the logical payout with a different stable idempotency key:

curl -X POST https://api.sandbox.wayex.com/v1/treasury/payouts \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: payout-submit-transfer-aud-001" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryId": "ben_123",
    "amount": "250.00",
    "currency": "AUD",
    "externalReference": "payout-9172",
    "purpose": "Customer withdrawal",
    "walletProviderReference": "transfer-wallet-au-01",
    "downstreamMerchantReference": "merchant-7842"
  }'

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. All money values are decimal strings. The accepted operation response records the authoritative:

requested payout amount;
fee;
total sourceDebit reserved from the AUD wallet.

What happens to the balance

available AUD --accept--> reserved AUD --settle--> captured
                                  \--proven non-execution--> released

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

State	Meaning	Your next action
`accepted`	Checks passed and source debit is reserved.	Wait for submission; do not pay again.
`held`	Policy or screening requires review.	Read the reason and next action.
`submitted`	The instruction reached the AUD rail.	Wait for authoritative settlement.
`settled`	The downstream payout completed.	Reconcile the capture and references.
`failed`	The payout did not complete.	Confirm reservation disposition before retrying a new payout.
`returned`	A submitted or settled payout came back.	Reconcile the return credit/loss and recovery record.

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.

​Before you create a beneficiary

​Create a beneficiary

​Optional Sumsub evidence

​Preview, review, and submit a payout

​What happens to the balance

​Payout states

​Webhooks and safe retries

Before you create a beneficiary

Create a beneficiary

Optional Sumsub evidence

Preview, review, and submit a payout

What happens to the balance

Payout states

Webhooks and safe retries