Create beneficiary

POST

/customers/v1/beneficiaries

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

Request

Header Params

Body Params application/json

Examples

with company detailswith person details

{
    "account_number": "123456789",
    "bank_code": "062000",
    "bank_code_type": "BSB",
    "bank_country": "AUS",
    "bank_name": "Commonwealth Bank",
    "company": {
        "name": "Acme Corporation Pty Ltd"
    },
    "metadata": {}
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

cURL

with company detailswith person details

curl --location '/customers/v1/beneficiaries' \
--header 'x-client-id;' \
--header 'Content-Type: application/json' \
--data '{
    "account_number": "123456789",
    "bank_code": "062000",
    "bank_code_type": "BSB",
    "bank_country": "AUS",
    "bank_name": "Commonwealth Bank",
    "company": {
        "name": "Acme Corporation Pty Ltd"
    },
    "metadata": {}
}'

Responses

🟢201Created

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": {}
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

Modified at 2026-09-15 01:24:19

Get beneficiary by ID

Create Payid beneficiary