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.
Updated 10 months ago