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:

  1. Direct bank beneficiary
  2. Swift bank beneficiary
  3. 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

ParamRequired?Description
typeYesThe type of beneficiary. Can be Individual or Business
businessNameYesName of your beneficiary.
routeYesInforms Waza of the kind of account operated by this beneficiary. Should be bank_account for bank beneficiaries
emailAddressYesEmail address of your beneficiary
countryYesThe country of the beneficiary. You can find the list of countries supported by Waza in our countries guide
addressYesAddress of your beneficiary
bankYesAn object containing the bank code, bank account number, and the bank name.
bank.codeYesThis is the code of the bank of the beneficiary and can be gotten by following our channels guide
bank.accountNumberYesThis is the account number of your beneficiary
bank.nameNoThis is the name attached to the bank account
bank.swiftBicNoThis is the swift / bic number of the benefiricary's bank if they have one.
bank.cityNoThis is the city of the beneficiary's bank
bank.intermediaryAddressNoThis is the intermediary bank address of the beneficiary's bank if they have one.
bank.intermediarySwiftBicNoThis is the intermediary swift / bic number of the beneficiary's bank if they have one.
bank.intermediaryNameNoThis is the intermediary name of the beneficiary's bank if they have one.
tagNoAny 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

ParamRequired?Description
typeYesThe type of beneficiary. Can be Individual or Business
businessNameYes?Name of your beneficiary. (Required for business beneficiary types)
firstNameYes?First name of your beneficiary. (Required for Individual beneficiary types)
lastNameYes?Last name of your beneficiary. (Required for Individual beneficiary types)
routeYesInforms Waza of the kind of account operated by this beneficiary. Should be mobile_account for mobile money beneficiaries
emailAddressYesEmail address of your beneficiary
countryYesThe country of the beneficiary. You can find the list of countries supported by Waza in our countries guide
addressYesAddress of your beneficiary
mobileYesAn object containing the mobile code, mobile network, and mobile phone number.
mobile.codeYesThis is the code of the mobile account of the beneficiary and can be gotten by following our channels guide
mobile.networkNoThis is the network of the mobile account of the beneficiary
mobile.phoneNumberYesThis is the mobile phone number of your beneficiary
tagNoAny 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.