Bulk transfers
You can send money to multiple recipients in one go using the bulk transfer endpoint.
Hey👋. We recommend checking out Transfers: Overview to understand the basics of transfers first. This guide assumes you've read that.
Making a bulk transfer
To do this, you'll provide an array of objects called bulk_data. Each item in this array contains details for one transfer—the same details you specify when making a single transfer. Bulk transfers can be to either bank accounts, mobile money accounts, or Barter accounts.
You can also specify a title for the transfer. This is helpful so you can easily identify what a set of payments was for.
const details = {
title: "Staff salary for April",
bulk_data: [
{
bank_code: "044",
account_number: "0690000032",
amount: 690000,
currency: "NGN",
narration: "Salary payment for April",
},
{
bank_code: "044",
account_number: "0690000034",
amount: 420000,
currency: "NGN",
narration: "Salary payment for April",
}
]
};
const response = await flw.Transfer.bulk(details);
$details = [
"title" => "Staff salary for April",
"bulk_data" => [
[
"bank_code" => "044",
"account_number" => "0690000032",
"amount" => 690000,
"currency" => "NGN",
"narration" => "Salary payment for April",
],
[
"bank_code" => "044",
"account_number" => "0690000034",
"amount" => 420000,
"currency" => "NGN",
"narration" => "Salary payment for April",
]
]
];
$response = $transferService->bulkTransfer($details);
details = {
title: "Staff salary for April",
bulk_data: [
{
bank_code: "044",
account_number: "0690000032",
amount: 690000,
currency: "NGN",
narration: "Salary payment for April",
},
{
bank_code: "044",
account_number: "0690000034",
amount: 420000,
currency: "NGN",
narration: "Salary payment for April",
}
]
}
response = transfer.initiate_bulk_transfer details
details = {
"title": "Staff salary for April",
"bulk_data": [
{
"bank_code": "044",
"account_number": "0690000032",
"amount": 690000,
"currency": "NGN",
"narration": "Salary payment for April",
},
{
"bank_code": "044",
"account_number": "0690000034",
"amount": 420000,
"currency": "NGN",
"narration": "Salary payment for April",
}
]
}
res = rave.Transfer.bulk(details)
details := rave.BulkPaymentData {
Title: "Staff salary for April",
AccountBank: "044",
BulkData: []map[string]string{
{
"Bank": "044",
"Account Number": "0690000032",
"Amount": 690000,
"Currency": "NGN",
"Narration": "Salary payment for April",
},
{
"Bank": "044",
"Account Number": "0690000034",
"Amount": 420000,
"Currency": "NGN",
"Narration": "Salary payment for April",
},
},
}
err, response := transfer.InitiateBulkTransfer(details)
curl --location --request POST 'https://api.flutterwave.com/v3/bulk-transfers/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
"title": "Staff salary for April",
"bulk_data": [
{
"bank_code": "044",
"account_number": "0690000032",
"amount": 690000,
"currency": "NGN",
"narration": "Salary payment for April"
},
{
"bank_code": "044",
"account_number": "0690000034",
"amount": 420000,
"currency": "NGN",
"narration": "Salary payment for April"
}
]
}'
You'll get a response like this:
{
"status": "success",
"message": "Bulk transfer queued",
"data": {
"id": 9145,
"created_at": "2021-04-28T12:20:13.000Z",
"approver": "N/A"
}
}
The transfers will be queued for processing, which usually take between a few seconds and a few minutes.
Checking the status
If you have webhooks enabled, we'll send you a notification for each transfer in the batch as it gets completed (succeeds or fails).
You can also check the status of a bulk transfer manually using the get all transfers endpoint with a batch_id query parameter. The batch_id is the data.id returned from the create bulk transfer response:
const got = require('got');
got.get("https://api.flutterwave.com/v3/transfers?batch_id=9145", {
headers: {
Authorization: `Bearer ${process.env.FLW_SECRET_KEY}`,
},
}).json().then(console.log);
{
"status": "success",
"message": "Transfers fetched",
"meta": {
"page_info": {
"total": 2,
"current_page": 1,
"total_pages": 1
}
},
"data": [
{
"id": 190828,
"account_number": "0690000034",
"bank_code": "044",
"full_name": "Ade Bond",
"created_at": "2021-04-28T12:20:19.000Z",
"currency": "NGN",
"debit_currency": null,
"amount": 420000,
"fee": 53.75,
"status": "SUCCESSFUL",
"reference": "96ac8239321e4c2d_PMCKDU_5",
"meta": [
null
],
"narration": "Salary payment for August",
"approver": null,
"complete_message": "Successful",
"requires_approval": 0,
"is_approved": 1,
"bank_name": "ACCESS BANK NIGERIA"
},
{
"id": 190827,
"account_number": "0690000032",
"bank_code": "044",
"full_name": "Pastor Bright",
"created_at": "2021-04-28T12:20:16.000Z",
"currency": "NGN",
"debit_currency": null,
"amount": 690000,
"fee": 53.75,
"status": "SUCCESSFUL",
"reference": "9d82206d1b3322c7_PMCKDU_5",
"meta": [
null
],
"narration": "Salary payment for August",
"approver": null,
"complete_message": "Successful",
"requires_approval": 0,
"is_approved": 1,
"bank_name": "ACCESS BANK NIGERIA"
}
]
}
As usual, the status field indicates the status of each transfer ("NEW", "PENDING", "FAILED", "SUCCESSFUL"), while the complete_message gives a fuller description ("Transaction is currently being processed", "Account resolve failed", "Successful").
When making bulk transfers from your dashboard, you'll need to specify an approver. When doing it via API, no approver is needed.
You can also access details about unsuccessful transfers within your bulk transaction attempt. To achieve this, include the error_reporting flag in your initial bulk request. For bulk transfers that are initiated with the "error_reporting" flag enabled, we will return all errors with relevant information when you query their status.
{
"status": "success",
"message": "Transfers fetched",
"meta": {
"page_info": {
"total": 0,
"current_page": 0,
"total_pages": 0
},
"errors": [
{
"reference": "bulk_Transfers_0019_PMCK",
"item": 1,
"message": "Payout with this ref already exists"
},
{
"reference": "bulk_Transfers_0020_PMCK",
"item": 2,
"message": "Payout with this ref already exists"
},
{
"reference": "bulk_Transfers_0021_PMCK",
"item": 3,
"message": "Payout with this ref already exists"
},
{
"reference": "bulk_Transfers_0022_PMCK",
"item": 4,
"message": "Payout with this ref already exists"
}
]
},
"data": []
}