> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.wayex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Beneficiaries and payouts

> Save an AUD BSB/account recipient, supply optional identity evidence, and submit a prefunded payout.

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:

<Tabs>
  <Tab title="Individual">
    * 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
  </Tab>

  <Tab title="Business">
    * Legal business name - Business identifiers available to Transfer - BSB, account number, and
      account name - Downstream merchant or wallet-provider references when available - Optional
      Sumsub share token when available or required by policy
  </Tab>
</Tabs>

`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.

```bash theme={null}
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.

<Warning>
  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.
</Warning>

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:

```bash theme={null}
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:

```bash theme={null}
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

```text theme={null}
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](/api-reference/overview).