💸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.

Verify the account number

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.

List banks and telcos

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)
})

Create a transfer recipient

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

Bank account

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()

Mobile money

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()

Authorization code

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": "[e-mail]",
  "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.

Generate a transfer reference

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"
}

Initiate a transfer

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()

Verify a transfer

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.