Beneficiary management

Beneficiaries identify the bank account or payment destination used for an outbound payment.

All beneficiary requests require a bearer token and the relevant AccountId header.

Create a beneficiary

Send a POST request to /v1/beneficiaries with a beneficiary request body. See Create beneficiary.

If the account number already exists, the API returns 409 Conflict. Find or update the existing beneficiary instead of creating a duplicate.

Update a beneficiary

Send a PUT request to /v1/beneficiaries/{id}. An update creates a new beneficiary identifier, so replace the previous ID in your system. See Update beneficiary.

Retrieve beneficiaries

• Get beneficiary retrieves one beneficiary by ID
• List beneficiaries returns the account's beneficiaries
• Find beneficiaries searches by external ID

Store your own stable external reference so beneficiary records can be reconciled after an update.