Creating a beneficiary

You are able to create Beneficiaries with bank accounts or mobile money accounts through our APIs.

Account verification

We verify the account details of beneficiaries before they get added into your account. This is to ensure you don’t send money to the wrong or invalid account. You can check out the account validations page to learn about how you can also verify account details in different regions before attempting to create a beneficiary.

Fetching countries

When creating a beneficiary, you need the country of the beneficiary. The List Countries API can be used to get all countries supported by Waza.

To fetch a list of countries, make a GET request as seen below:

curl https://api.waza.co/api/countries
-H "waza-x-key: YOUR_API_KEY"
-X GET

const https = require('https')

const options = {
  hostname: 'api.waza.co',
  port: 443,
  path: '/api/countries',
  method: 'GET',
  headers: {
    'waza-x-key': 'YOUR_API_KEY'
  }
}

https.request(options, res => {
  let data = ''

  res.on('data', (chunk) => {
    data += chunk
  });

  res.on('end', () => {
    console.log(JSON.parse(data))
  })
}).on('error', error => {
  console.error(error)
})

Create beneficiary

To create the bank beneficiary, make a POST request to the Create Beneficiary API passing details specific to your need for creating:

Direct bank beneficiary
Swift bank beneficiary
Mobile account beneficiary

Direct bank beneficiary

Here, you specify the route as bank_account, add a bank field which contains the customer’s bank account details as seen below:

Beneficiary information

Param	Required?	Description
type	Yes	The type of beneficiary. Can be Individual or Business
businessName	Yes	Name of your beneficiary.
route	Yes	Informs Waza of the kind of account operated by this beneficiary. Should be `bank_account` for bank beneficiaries
emailAddress	Yes	Email address of your beneficiary
country	Yes	The country of the beneficiary. You can find the list of countries supported by Waza in our countries guide
address	Yes	Address of your beneficiary
bank	Yes	An object containing the bank code, bank account number, and the bank name.
bank.code	Yes	This is the code of the bank of the beneficiary and can be gotten by following our channels guide
bank.accountNumber	Yes	This is the account number of your beneficiary
bank.name	No	This is the name attached to the bank account
bank.swiftBic	No	This is the swift / bic number of the benefiricary's bank if they have one.
bank.city	No	This is the city of the beneficiary's bank
bank.intermediaryAddress	No	This is the intermediary bank address of the beneficiary's bank if they have one.
bank.intermediarySwiftBic	No	This is the intermediary swift / bic number of the beneficiary's bank if they have one.
bank.intermediaryName	No	This is the intermediary name of the beneficiary's bank if they have one.
tag	No	Any tag you want to associate with this beneficiary

Create beneficiary

After collecting the beneficiary's details, you are ready to initiate the creation of your beneficiary by hitting our beneficiaries API as seen below:

curl --request POST \
     --url https://api.waza.co/api/beneficiaries \
     --header 'waza-x-key: YOUR-API-KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "type": "Business",
     "businessName": "Sample Business",
     "route": "bank_account",
     "emailAddress": "[email protected]",
     "bank": {
          "code": "valid-bank-code",
          "accountNumber": "valid-bank-account",
          "name": "account-name",
          "swiftBic": "WZ-112233",
          "city": "Sample City",
          "intermediaryAddress": "Sample Address",
        	"intermediarySwiftBic": "SampleBic",
        	"intermediaryName": "Sample name",
     },
     "country": "NGA",
     "address": "Sample address",
     "tag": "Sample tag"
}
'

const https = require('https')

const params = JSON.stringify({
    "type": "Business",
    "bank": {
        "code": "044",
        "name": "bank-name",
        "accountNumber": "valid-bank-account",
    },
    "country": "NGA",
    "route": "bank_account",
    "address": "Sample address",
    "tag": "Sample tag",
    "businessName": "Sample Business",
    "emailAddress": "[email protected]"
})

const options = {
  hostname: 'api.waza.co',
  port: 443,
  path: '/api/beneficiaries',
  method: 'POST',
  headers: {
    x-waza-key: 'YOUR-API-KEY',
    'Content-Type': 'application/json'
  }
}

const req = https.request(options, res => {
  let data = ''

  res.on('data', (chunk) => {
    data += chunk
  });

  res.on('end', () => {
    console.log(JSON.parse(data))
  })
}).on('error', error => {
  console.error(error)
})

req.write(params)
req.end()

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

{
    "status": "success",
    "message": "Beneficiary created successfully.",
    "data": {
        "id": 1,
        "reference": "cla1eez8x0207ddps18k1icmo",
        "wazaRef": "BN-414160",
        "dateCreated": "2022-11-03T18:25:49.041Z",
        "beneficiaryType": "BUSINESS",
        "beneficiaryName": "SampleBusiness",
        "preferredName": "Doe,
        "emailAddress": "[email protected]",
        "routeName": "BANK",
        "bank": {
            "name": "Access Bank",
            "code": "044",
            "accountNumber": "valid-bank-account",
			      "swiftBic": "WZ-112233",
      			"city": "Sample City",
			      "intermediaryAddress": "Sample Address",
            "intermediaryName": "Sample Name",
            "intermediarySwiftBic": "SampleBic",
            "isVerified": true,
            "verifiedName": "SampleBusiness"
        },
        "mobile": null,
        "tag": "sample-tag",
        "address": "Sample address",
        "country": "NGA",
        "currency": "NGN"
    }
}

Mobile beneficiary

Here, you specify the route as mobile_account, add a mobile field which contains the customer’s bank account details as seen below:

Beneficiary information

Param	Required?	Description
type	Yes	The type of beneficiary. Can be `Individual` or `Business`
businessName	Yes?	Name of your beneficiary. (Required for business beneficiary types)
firstName	Yes?	First name of your beneficiary. (Required for Individual beneficiary types)
lastName	Yes?	Last name of your beneficiary. (Required for Individual beneficiary types)
route	Yes	Informs Waza of the kind of account operated by this beneficiary. Should be `mobile_account` for mobile money beneficiaries
emailAddress	Yes	Email address of your beneficiary
country	Yes	The country of the beneficiary. You can find the list of countries supported by Waza in our countries guide
address	Yes	Address of your beneficiary
mobile	Yes	An object containing the mobile code, mobile network, and mobile phone number.
mobile.code	Yes	This is the code of the mobile account of the beneficiary and can be gotten by following our channels guide
mobile.network	No	This is the network of the mobile account of the beneficiary
mobile.phoneNumber	Yes	This is the mobile phone number of your beneficiary
tag	No	Any tag you want to associate with this beneficiary

Create beneficiary

After collecting the beneficiary's details, you are ready to initiate the creation of your beneficiary by hitting our beneficiaries API as seen below:

curl --request POST \
     --url https://api.waza.co/api/beneficiaries \
     --header 'waza-x-key: YOUR-API-KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "type": "Business",
     "mobile": {
          "code": "MTN",
          "network": "MTN",
          "phoneNumber": "233123456789"
     },
     "route": "mobile_account",
     "country": "GHA",
     "address": "Sample address",
     "tag": "Sample tag",
     "businessName": "Sample Business",
     "emailAddress": "[email protected]"
}
'

const https = require('https')

const params = JSON.stringify({
     "type": "Business",
     "mobile": {
          "code": "MTN",
          "network": "MTN",
          "phoneNumber": "233123456789"
     },
     "route": "mobile_account",
     "country": "GHA",
     "address": "Sample address",
     "tag": "Sample tag",
     "businessName": "Sample Business",
     "emailAddress": "[email protected]"
})

const options = {
  hostname: 'api.waza.co',
  port: 443,
  path: '/api/beneficiaries',
  method: 'POST',
  headers: {
    x-waza-key: 'YOUR-API-KEY',
    'Content-Type': 'application/json'
  }
}

const req = https.request(options, res => {
  let data = ''

  res.on('data', (chunk) => {
    data += chunk
  });

  res.on('end', () => {
    console.log(JSON.parse(data))
  })
}).on('error', error => {
  console.error(error)
})

req.write(params)
req.end()

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

{
    "status": "success",
    "message": "Beneficiary created successfully.",
    "data": {
        "id": 2,
        "reference": "clatsi5bm0434xjps6nnscovq",
        "wazaRef": "BN-437196",
        "dateCreated": "2022-11-23T15:17:44.434Z",
        "beneficiaryType": "BUSINESS",
        "beneficiaryName": "SampleBusiness",
        "preferredName": "Doe,
        "emailAddress": "[email protected]",
        "routeName": "MOBILE",
        "bank": null,
        "mobile": {
            "network": "MTN",
            "code": "MTN",
            "phoneNumber": "23312345678",
            "isVerified": true,
            "verifiedName": "John Doe"
        },
        "tag": "Sample tag",
        "address": "Sample address",
        "country": "GHA",
        "currency": "GHS"
    }
}

🚧
Account validation
If you enter an invalid account detail, we return a response with a message: We could not validate this account, please confirm your entry.
If you get this error, kindly request the confirm the customer’s account details and try again.