Creating a beneficiary

Beneficiaries are the foundation of Waza's B2B global payment APIs and this guide would inform you on how to use our API to create beneficiaries on your account.

This guide provides information on how to create a beneficiary using the POST endpoint /beneficiaries. Beneficiaries are business or individuals who are recipients of B2B payments made on Waza. This guide covers the request object structure, and example requests.

Request Object Parameters

Here's a table listing all the necessary parameters required to make an API call to the Beneficiary API.

Param	Required?	Description
type	Yes	The type of beneficiary. It can be Individual or Business.
country	Yes	The country code of the beneficiary is obtained from the corridor API. You can find the list of corridors supported by Waza in our section of the documentation containing the Corridors information or our corridors API reference.
address	Yes	Address of your beneficiary.
business_name	Yes	The business name of your beneficiary.
phone	No	The phone number of your beneficiary
bank	Yes	An object containing the bank code, bank name, bank account number, and bank address.
bank.code	Yes	This is the SWIFT Code of the beneficiary's bank.
bank.name	Yes	This is the name attached to the bank account.
bank.account_number	Yes	This is the account number of your beneficiary.
bank.address	Yes	This is the address of the beneficiary's bank.
intermediary_bank	No (but should be provided if available)	This is an object containing details on the intermediary bank code, name, account number, and bank address.
intermediary_bank.code	No (but should be provided if available)	This is the SWIFT Code of the intermediary bank.
intermediary_bank.name	No (but should be provided if available)	This is the name attached to the intermediary bank account.
intermediary_bank.account_number	No (but should be provided if available)	This is the account number of your intermediary bank.
intermediary_bank.address	No (but should be provided if available)	This is the address of the intermediary bank.
client_reference	Yes	This is your unique identifier for the transaction.
currency	Yes	The currency code of the currency the beneficiary is receiving.
email	No	The email address of the beneficiary.
tag	No	Any tag you want to associate with this beneficiary.

Sample Request

curl --location 'http://api.sandbox.waza.co/v2/beneficiaries' \
--header 'WAZA-X-KEY: {{API_KEY}}' \
--data-raw '{
    "type": "business",
    "country": "GB",
    "address": "Barking Wharf Square",
    "business_name": "My good business",
    "phone": "+44455545455",
    "bank": {
        "code": "044",
        "name": "Test Bank",
        "account_number": "00413686094",
        "address": "Bank Address"
    },
    "intermediary_bank":{   
    		"code": "000",
        "name": "Test Intermediary Bank",
        "account_number": "0123456782",
        "address": "Intermediary Bank Address"
    },
    "client_reference": "478884739488",
    "currency": "GBP",
    "email": "[email protected]",
    "tag": "sample"
}'

Sample Response

A successful beneficiary creation API call should return a similar response structure as seen below:

{
  "data": {
    "id": "clh9me25a0052qgvostk4m648",
    "type": "business",
    "country": "GB",
    "currency": "GBP",
    "phone": "+447432267533",
    "address": "Barking Wharf Square",
    "email": "[email protected]",
    "business_name": "My good business",
    "first_name": null,
    "last_name": null,
    "created_date": "2023-05-04T21:09:08.830Z",
    "updated_date": "2023-05-04T21:09:08.830Z",
    "client_reference": "4788d84739488",
    "bank": {
      "name": "Test Bank",
      "account_number": "0041d3686094",
      "address": "Bank Address",
      "code": "044"
    },
    "tag": "sample"
  }
}