Create beneficiary

The standard beneficiary creation endpoint. You must provide either person OR company details, but not both.

Exactly one of person or company must be provided (never both); requests violating this are rejected with 400 only one of person or company should be present.

Not idempotent. This endpoint does not honour Idempotency-Key. Sending the header is not an error and has no effect: the request executes every time, and a retry creates a second record. Deduplication is the caller's responsibility. Account-number beneficiaries are not de-duplicated at all, so creating the same one twice silently produces two records (a pay_id is unique platform-wide, which is the asymmetry that catches people).

Non-AUD destinations. bank_code_type also accepts IBAN, SORT_CODE, ABA and SWIFT, and bank_country any ISO alpha-3 code. Outside AUS an address is required at creation. The identifier types a payout rail accepts are checked when the payout is created. Destination fields are immutable after creation; address, relationship, status and metadata can be changed with PATCH.

application/json

Bodyapplication/json

Example

{
    "id": "e232ba4c-9322-4fac-8aa5-ceaf9a1c1c44",
    "account_number": "123456789",
    "bank_code": "062000",
    "bank_code_type": "BSB",
    "bank_country": "AUS",
    "bank_name": "Commonwealth Bank",
    "pay_id": null,
    "pay_id_type": null,
    "pay_id_name": null,
    "pay_id_status": null,
    "pay_id_registered_at": null,
    "created_at": "2026-01-21T06:08:25.452Z",
    "updated_at": "2026-01-21T06:08:25.452Z",
    "status": "ACTIVE",
    "person": null,
    "company": {
        "name": "Acme Corporation Pty Ltd"
    },
    "metadata": {}
}

Create beneficiary

Request

Request Code Samples

Responses