> ## 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 - 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
  </Tab>

  <Tab title="Business">
    * 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
  </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.

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](/errors#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.

```bash theme={null}
curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/beneficiaries \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: beneficiary-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.

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

```bash theme={null}
curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/beneficiaries \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: beneficiary-payid-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "destination": {
      "type": "payid",
      "payId": "ava.williams@example.com",
      "payIdType": "email",
      "accountName": "Ava Williams"
    },
    "firstName": "Ava",
    "lastName": "Williams",
    "dateOfBirth": "1991-05-14",
    "address": "100 Market Street, Sydney NSW 2000"
}'
```

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.

<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.rails.wayex.com/v1/treasury/payouts/preview \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: payout-review-aud-001" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryId": "ben_123",
    "amount": "250.00",
    "currency": "AUD",
    "externalReference": "payout-9172",
    "purpose": "Customer withdrawal",
    "walletProviderReference": "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 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:

```bash theme={null}
curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/payouts \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: payout-submit-aud-001" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryId": "ben_123",
    "amount": "250.00",
    "currency": "AUD",
    "externalReference": "payout-9172",
    "purpose": "Customer withdrawal",
    "walletProviderReference": "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.

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:

```bash theme={null}
# Read the current default
curl https://api.sandbox.rails.wayex.com/v1/treasury/settings \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY"

# Set the default (requires treasury:write)
curl -X PUT https://api.sandbox.rails.wayex.com/v1/treasury/settings \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: treasury-settings-001" \
  -H "Content-Type: application/json" \
  -d '{ "payoutRemitter": "wayex" }'
```

`payoutRemitter` accepts exactly two values — never free text:

| Value    | Remitter shown on the payout                                                    |
| -------- | ------------------------------------------------------------------------------- |
| `wayex`  | `Wayex` (the default).                                                          |
| `tenant` | Your onboarded company name (returned as `tenantRemitterName` on the settings). |

`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

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