💸
Cash Transfer
You can transfer money in four easy steps:
- 1.Verify the account number
- 2.Create a transfer recipient
- 3.Initiate a transfer
- 4.Listen for transfer status
Good to know: To send money on Dunia, you need API keys to authenticate your transfers. You can find your keys on the Dunia Dashboard under Settings → API Keys & Webhooks.
You need to collect the customer's account details and confirm that it’s valid before sending money. This is to ensure you don’t send money to the wrong or invalid account. Kindly check out the Verify Account Number page to learn about how to verify account details in different regions.
When creating a transfer recipient, you need the bank or telco details of the customer. The List BankAPI can be used to get all supported banks and telcos in a country.
To fetch a list of banks in a country, make a
GET request passing the currency in the query parameter:const https = require('https')
const options = {
hostname: 'api.dunia.co',
port: 443,
path: '/bank?currency=NGN',
method: 'GET',
headers: {
Authorization: 'Bearer SECRET_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)
})
To fetch a list of supported telcos for mobile money, you can add
currency and type in the query parameters for the List BankAPI:const https = require('https')
const options = {
hostname: 'api.dunia.co',
port: 443,
path: '/bank?currency=GHS&type=mobile_money',
method: 'GET',
headers: {
Authorization: 'Bearer SECRET_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)
})
Before sending money to an account, you need to create a transfer recipient with the customer’s account details.
The recipient type can take the following values based on country:
Type | Currency | Description |
|---|---|---|
nuban | NGN | This means the Nigerian Uniform Bank Account Number. It represents bank accounts in Nigeria. |
mobile_money | GHS | Mobile Money or MoMo is an account tied to a mobile number |
basa | ZAR | This means the Banking Association South Africa. It represents bank accounts in South Africa |
authorization | All | This is a unique code that represents a customer’s card. We return an authorization code after a user makes a payment with their card. |
bank_account | XOF | This represents bank accounts in the ECOWAS zone. |
To create the transfer recipient, make a
POST request to the Transfer RecipientAPI passing one of the following customer’s detail:- 1.Bank account
- 2.Mobile money
- 3.Authorization code
Here, you specify the
type based on your integration currency, then pass the customer’s details:const https = require('https')
const params = JSON.stringify({
"type":"nuban",
"name" : "John Doe",
"account_number": "0001234567",
"bank_code": "058",
"currency": "NGN"
})
const options = {
hostname: 'api.dunia.co',
port: 443,
path: '/transferrecipient',
method: 'POST',
headers: {
Authorization: 'Bearer SECRET_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()
With mobile money, the
bank_code takes the telco code as its value and the mobile number is passed to the account_number parameter:const https = require('https')
const params = JSON.stringify({
"type":"mobile_money",
"name" : "Abina Nana",
"account_number": "0551234987",
"bank_code": "MTN",
"currency": "GHS"
})
const options = {
hostname: 'api.dunia.co',
port: 443,
path: '/transferrecipient',
method: 'POST',
headers: {
Authorization: 'Bearer SECRET_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()
An authorization code is returned after a successful card payment by a customer. Combining the authorization code with the email address used for payment, you can create a transfer recipient:
const https = require('https')
const params = JSON.stringify({
"type":"authorization",
"name" : "Revs Ore",
"email": "[email protected]",
"authorization_code": "AUTH_ncx8hews93"
})
const options = {
hostname: 'api.dunia.co',
port: 443,
path: '/transferrecipient',
method: 'POST',
headers: {
Authorization: 'Bearer SECRET_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()
The
recipient_code from the data object is the unique identifier for this user and would be used to make transfers to the specified account. This code should be saved with the customer's records in your database.A transfer reference is a unique identifier that lets you track, manage and reconcile each transfer request made on your integration. Transfer references allow you to prevent double crediting as you can retry a non-conclusive transfer rather than initiate a new request.
In order to take advantage of a transfer reference, you need to generate and provide it for every request. When you don’t provide a transfer reference, Dunia generates one for you but this defeats the purpose of the transfer reference.
We recommend generating a v4 UUID reference of no more than 100 characters. However, if you prefer implementing your own logic, you should ensure your reference contains at least 16 alphanumeric characters.
{
"source": "balance",
"reason": "Savings",
"amount": 30000,
"reference": "your-unique-reference",
"recipient": "RCP_1a25w1h3n0xctjg"
}
To send money to a customer, you make a
POST request to the Initate TransferAPI, passing the reference and recipient_code previously created.When you send this request, if there are no errors, the response comes back with a pending status, while the transfer is being processed.
Retrying a transfer If there is an error with the transfer request, kindly retry the transaction with the same reference in order to avoid double crediting. If a new reference is used, the transfer would be treated as a new request.
Test transfers always return success, because there is no processing involved. The live transfers processing usually take between a few seconds and a few minutes. When it's done processing, a notification is sent to your webhook URL.
const https = require('https')
const params = JSON.stringify({
"source": "balance",
"amount": 37800,
"reference": "your-unique-reference",
"recipient": "RCP_t0ya41mp35flk40",
"reason": "Holiday Flexing"
})
const options = {
hostname: 'api.dunia.co',
port: 443,
path: '/transfer',
method: 'POST',
headers: {
Authorization: 'Bearer SECRET_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()
When a transfer is initiated, it could take a few seconds or minutes to be processed. This is why we recommend relying on webhooks for verification as opposed to polling.
Receiving Notifications
In order to receive notifications, you need to implement a webhook URL and set the webhook URL on your Dunia Dashboard.
Once a transfer is processed, we send the final status of the transfer as a
POST request to your webhook URL.Event | Description |
|---|---|
transfer.success | This is sent when the transfer is successful |
transfer.failed | This is sent when the transfer fails |
transfer.reversed | This is sent when we refund a previously debited amount for a transfer that couldn’t be completed |
The response for a transfer also contains a unique transfer code to identify this transfer. You can use this code to call the Fetch TransferAPI endpoint to fetch status and details of the transfer anytime you want.
Last modified 6mo ago