> ## 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. # Create a Treasury beneficiary > 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. ## 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](/treasury/beneficiaries-and-payouts) for the complete workflow. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/treasury/beneficiaries openapi: 3.0.0 info: title: Wayex API description: >- Wayex APIs for direct customer payment routes and isolated, prefunded Treasury accounts. Each API key is bound to one tenant account and its own wallet, settings, webhooks, and reporting. version: 1.0.0 contact: {} servers: - url: https://api.sandbox.rails.wayex.com description: Sandbox — fully simulated providers, no real funds move - url: https://api.rails.wayex.com description: Production — live rails, real funds move security: - Bearer: [] - ApiKey: [] tags: - name: Treasury description: >- Prefunded AUD and stablecoin wallets for one isolated tenant account. Fund, pay, convert, withdraw, track, and reconcile without selecting another account. - name: Customers description: >- Onboard end customers, run verification, and manage each customer's entitlements. - name: Payment routes description: >- Standing deposit instructions per customer. When a customer funds a route, Wayex auto-converts at the live rate and pays out/sends — no quote, no lock. - name: Transfers description: >- Read the conversion records produced when customers fund payment routes — the live activity feed and per-conversion lifecycle timeline. - name: Rates description: >- The live indicative AUD↔stablecoin rate right now — the all-in rate Wayex quotes. Indicative only; the binding price is struck when a route's funds land. - name: Revenue description: Your developer-fee revenue over time. - name: Invoices description: >- Your monthly invoices — Wayex platform fees due, net of your accrued developer-fee credit. - name: Webhooks description: Subscribe to HMAC-signed event webhooks and inspect deliveries. - name: API keys description: Create, list, and rotate API keys for programmatic access. - name: Fees description: >- Configure your developer fee — the markup withheld from each conversion and credited against your monthly invoice. - name: Invitations description: Accept a team invitation and activate your account. - name: Team description: Manage your own team — list members and send console invitations. - name: Notification settings description: >- Manage whether Wayex sends customer-facing notification emails on your behalf. paths: /v1/treasury/beneficiaries: post: tags: - Treasury summary: Create a Treasury beneficiary description: >- 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. 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. operationId: TreasuryController2_createBeneficiary_v1 parameters: - name: Idempotency-Key in: header required: true description: >- A unique key for this logical action. Reuse the same key and identical payload when retrying after an unknown response. schema: type: string minLength: 8 maxLength: 255 example: 13bda8d7-87bd-4fa4-b7d5-e740725f9bd2 requestBody: required: true content: application/json: schema: oneOf: - type: object properties: destination: oneOf: - type: object properties: type: type: string enum: - payid payId: type: string minLength: 1 payIdType: type: string enum: - email - phone - abn accountName: type: string minLength: 2 required: - type - payId - payIdType - accountName - type: object properties: type: type: string enum: - bank_account bsb: type: string pattern: ^\d{6}$ accountNumber: type: string pattern: ^\d{1,9}$ accountName: type: string minLength: 2 required: - type - bsb - accountNumber - accountName partyContext: description: >- 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. type: object additionalProperties: type: string type: type: string enum: - individual firstName: type: string minLength: 1 lastName: type: string minLength: 1 dateOfBirth: type: string address: type: string minLength: 1 externalReference: type: string minLength: 1 maxLength: 512 sumsub: type: object properties: shareToken: type: string minLength: 1 maxLength: 1024 externalReference: description: >- Optional. Your own reference for this beneficiary, echoed back for correlation. Wayex generates one when omitted. type: string minLength: 1 maxLength: 512 levelName: type: string minLength: 1 maxLength: 256 required: - shareToken required: - destination - type - firstName - lastName - dateOfBirth - address - type: object properties: destination: oneOf: - type: object properties: type: type: string enum: - payid payId: type: string minLength: 1 payIdType: type: string enum: - email - phone - abn accountName: type: string minLength: 2 required: - type - payId - payIdType - accountName - type: object properties: type: type: string enum: - bank_account bsb: type: string pattern: ^\d{6}$ accountNumber: type: string pattern: ^\d{1,9}$ accountName: type: string minLength: 2 required: - type - bsb - accountNumber - accountName partyContext: description: >- 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. type: object additionalProperties: type: string type: type: string enum: - business businessName: type: string minLength: 1 businessIdentity: type: object additionalProperties: type: string externalReference: type: string minLength: 1 maxLength: 512 sumsub: type: object properties: shareToken: type: string minLength: 1 maxLength: 1024 externalReference: description: >- Optional. Your own reference for this beneficiary, echoed back for correlation. Wayex generates one when omitted. type: string minLength: 1 maxLength: 512 levelName: type: string minLength: 1 maxLength: 256 required: - shareToken required: - destination - type - businessName responses: '201': description: '' content: application/json: schema: oneOf: - type: object properties: id: type: string minLength: 1 clientId: type: string minLength: 1 externalReference: description: >- Your own reference for this beneficiary, echoed back for correlation. Wayex generates one when you do not supply it at creation. type: string minLength: 1 destination: oneOf: - type: object properties: type: type: string enum: - payid payId: type: string minLength: 1 payIdType: type: string enum: - email - phone - abn accountName: type: string minLength: 2 required: - type - payId - payIdType - accountName - type: object properties: type: type: string enum: - bank_account bsb: type: string pattern: ^\d{6}$ accountNumber: type: string pattern: ^\d{1,9}$ accountName: type: string minLength: 2 required: - type - bsb - accountNumber - accountName partyContext: description: >- 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. type: object additionalProperties: type: string status: type: string enum: - active - inactive createdAt: type: string format: date-time updatedAt: type: string format: date-time deactivatedAt: type: string format: date-time type: type: string enum: - individual firstName: type: string minLength: 1 lastName: type: string minLength: 1 dateOfBirth: type: string address: type: string minLength: 1 required: - id - clientId - externalReference - destination - status - createdAt - updatedAt - type - firstName - lastName - dateOfBirth - address - type: object properties: id: type: string minLength: 1 clientId: type: string minLength: 1 externalReference: description: >- Your own reference for this beneficiary, echoed back for correlation. Wayex generates one when you do not supply it at creation. type: string minLength: 1 destination: oneOf: - type: object properties: type: type: string enum: - payid payId: type: string minLength: 1 payIdType: type: string enum: - email - phone - abn accountName: type: string minLength: 2 required: - type - payId - payIdType - accountName - type: object properties: type: type: string enum: - bank_account bsb: type: string pattern: ^\d{6}$ accountNumber: type: string pattern: ^\d{1,9}$ accountName: type: string minLength: 2 required: - type - bsb - accountNumber - accountName partyContext: description: >- 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. type: object additionalProperties: type: string status: type: string enum: - active - inactive createdAt: type: string format: date-time updatedAt: type: string format: date-time deactivatedAt: type: string format: date-time type: type: string enum: - business businessName: type: string minLength: 1 businessIdentity: type: object additionalProperties: type: string required: - id - clientId - externalReference - destination - status - createdAt - updatedAt - type - businessName security: - Bearer: [] - ApiKey: [] components: securitySchemes: Bearer: type: http scheme: bearer bearerFormat: Wayex API key description: 'Send the same Wayex API key as `Authorization: Bearer `.' ApiKey: type: apiKey in: header name: X-Api-Key description: >- A Wayex API key. Use a secret key (`sk_…`) — it works on every endpoint. Publishable keys (`pk_…`) are accepted only on a small set of read endpoints: `GET /v1/rates`, `GET /v1/activity`, `GET /v1/developer-fees`, `GET /v1/revenue`, and `GET /v1/reports/revenue`. ````