Beneficiary Management

A beneficiary is an account a client pays. Beneficiaries come in two types— business and personal—each with its own endpoints. As a Program Manager you manage beneficiaries for the Clients within your Tenant.

Ownership is bound to a client

Every beneficiary belongs to a specific client, set with clientId at creation:

• Provide the clientId of the client the beneficiary belongs to.
• clientId is accepted only at creation—it is not part of the update payload, so ownership cannot be changed afterward.

info

This is a strong, explicit binding: unlike the Client API (where clientId is optional and defaults to the caller's own account), a Program Manager must always name the owning Client up front so the beneficiary is unambiguously scoped to it.

How to identify the account

Provide either of the following (one is required):

• bankAccount — full bank details (account number, routing information), or
• uniquePayId — the beneficiary's CAPAY FastID, if they are also a CAPAY client. Paying by uniquePayId enables fee-free internal (Inner) transfers.

Create a beneficiary

curl -X POST "https://api.sandbox.capay.com.au/beneficiaries/business" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: unique-key-12345" \
  -d '{
    "clientId": "401f4647-8372-495f-8de0-aafb3e1eaf93",
    "countryCode": "AU",
    "name": "ABC Pty Ltd",
    "nickName": "ABC",
    "bankAccount": { "accountNumber": "123456", "routingNumber": "012999" }
  }'

Business beneficiaries require countryCode and name. Personal beneficiaries (POST /beneficiaries/personals) require countryCode, firstName, and lastName. Include the owning clientId, plus optional referenceId, contact details, and address.

Validation and Confirmation of Payee (optional)

Neither validation step is required before creating a beneficiary — you can call POST /beneficiaries/business (or /personals) directly. However, running validation first is strongly recommended to catch errors before they affect a payment.

There are two validation endpoints:

• Standard validation (POST /beneficiaries/business/validate / .../personals/validate) — checks the creation data for blocking errors and returns an empty 200 if valid. No COP check is performed.

• Confirmation of Payee (POST /v2/beneficiaries/business/validate / .../personals/validate) — performs the same checks, and additionally runs a COP name-match for Local AUD beneficiaries. COP is not applicable to SWIFT or other non-AUD payment types.

  COP result code	Meaning
  COP MATCHED	Name matches the account
  COP CLOSE MATCHED	Near match — check matchScore (0–100) and suggested name
  COP NOT MATCHED	Name does not match
  COP ACC NOT FOUND	Account could not be found
  COP OPTIONAL OUT / COP OTHERS	COP not applicable or other outcome

tip

For Local AUD beneficiaries, run the v2 validate endpoint (Confirmation of Payee) before creating the beneficiary to reduce the risk of misdirected funds.

Retrieve, update, and delete

Action	Business	Personal
List	GET /beneficiaries/businesses	GET /beneficiaries/personals
Get by ID	GET /beneficiaries/business/{id}	GET /beneficiaries/personals/{id}
Update	PUT /beneficiaries/business/{id}	PUT /beneficiaries/personals/{id}
Delete	DELETE /beneficiaries/business/{id}	DELETE /beneficiaries/personals/{id}

List endpoints support filters such as countryCode, currencyCode, clientId, and name. Filter by clientId to see the beneficiaries of a specific client.

caution

A beneficiary with an in-progress payment cannot be updated or deleted.

Duplicate detection

A beneficiary is considered a duplicate within the same owning client (clientId) when either matches:

1. clientId + uniquePayId, or
2. clientId + bank details (routing number + account number + account name + currency code).

Reuse the existing beneficiary, or change the identifying details.