Alpha's Beneficiaries APIs allow you to create individual or company beneficiaries to ensure agility each time you want to make a payment. Optimise time and resources by removing the need to create a beneficiary for every payment.

The API provides you with the ability to pre-validate a beneficiary before submitting a create beneficiary request, which greatly reduces the chances of validation failure during payment creation. Additionally, retrieve the details of an existing beneficiary.

Validate a new beneficiary

Before creating a new beneficiary, you will have the ability to check the beneficiary details are correct, using the POST Validate Beneficiary endpoint.

This step is not mandatory in the beneficiary creation process.

You will need to specify the AccountID, Name of the beneficiary, Address, BankCountryCode and CountryCode in your request.

💭 To ensure successful validation, you will need to pass all the relevant fields for the recipients' country. While these are not mandatory fields in the request, to ensure the validation is accurate we recommend you pass all the applicable fields.

Please see the table here for necessary field guidelines per country.

Create a new beneficiary

To create and submit a payment on Alpha, you must first create a beneficiary using the POST Beneficiary endpoint.

Beneficiaries can be either individuals or companies, first-party or third-party.

You will need to specify the AccountID, Name of the beneficiary, Address, BankCountryCode and CountryCode in your request.

Retrieve a beneficiary

Once a beneficiary has been created successfully, you can retrieve the details of a beneficiary using the GET Beneficiary endpoint.

To retrieve the beneficiary details, you must include the Beneficiary ID in the request. The Beneficiary ID will be returned in the response to the successful creation of a new beneficiary.

Retrieve all beneficiaries

To retrieve all beneficiaries associated with an entity, you will need pass in the EntityID in the request using the GET Beneficiaries endpoint.

The response will contain a list of all active beneficiaries created by the specified entity. You will be able to filter the beneficiaries returned by specifying the Currency and Country of the beneficiary.

Update beneficiary address

Should the address of one of your beneficiaries change, you will be able to update it using the PUT Beneficiary endpoint.

You will need to specify the new address in the request body.

Delete a beneficiary

To delete a beneficiary, you will need to use the DELETE Beneficiary endpoint. In the request, you will need to include the EntityID and the BeneficiaryID of the beneficiary you would like to delete.

Once a beneficiary has been deleted, you will no longer be able to retrieve the beneficiary details via the GET Beneficiary and GET Beneficiaries endpoint.

If a payment has been made to a deleted beneficiary, you will still be able to retrieve the beneficiary details as part of the response through GET payment or GET payments endpoints.

For the technical implementation details, please see the Beneficiaries API reference