Beneficiaries

A beneficiary is an account you pay. Beneficiaries come in two types—business and personal—each with its own endpoints. Once created, a beneficiary can be reused across many payments.

Who owns a beneficiary

When you create a beneficiary you decide who it belongs to, using the optional clientId field:

clientId at creation	Owner
Omitted	You (your own account)
Provided	The underlying customer with that clientId

Ownership is set once

clientId is only accepted at creation—it is not part of the update payload, so ownership cannot be changed afterward. Also note that a beneficiary is bound to an entity (you or an underlying customer), not to a specific House or Sub-Account. The link between a beneficiary and the account that funds a payment is resolved when you create the payment.

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 '{
    "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. Both accept an optional clientId, 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.

caution

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

Duplicate detection

A beneficiary is considered a duplicate within the same owner (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.