Bulk Transfers
Easily send money to multiple recipients with our bulk transfer option.
Getting Started
We recommend checking out the introductory section to understand the basics of making transfers first.
You can send money to multiple recipients in one go using the bulk transfer endpoint.
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, or mobile money 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: "1234567832",
amount: 690000,
currency: "NGN",
narration: "Salary payment for April",
},
{
bank_code: "044",
account_number: "1234567834",
amount: 500000,
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" => "1234567832",
"amount" => 690000,
"currency" => "NGN",
"narration" => "Salary payment for April",
],
[
"bank_code" => "044",
"account_number" => "1234567834",
"amount" => 500000,
"currency" => "NGN",
"narration" => "Salary payment for April",
]
]
];
$response = $transferService->bulkTransfer($details);
details = {
title: "Staff salary for April",
bulk_data: [
{
bank_code: "044",
account_number: "1234567832",
amount: 690000,
currency: "NGN",
narration: "Salary payment for April",
},
{
bank_code: "044",
account_number: "1234567834",
amount: 500000,
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": "1234567832",
"amount": 690000,
"currency": "NGN",
"narration": "Salary payment for April",
},
{
"bank_code": "044",
"account_number": "1234567834",
"amount": 500000,
"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": "1234567832",
"Amount": 690000,
"Currency": "NGN",
"Narration": "Salary payment for April",
},
{
"Bank": "044",
"Account Number": "1234567834",
"Amount": 500000,
"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": "1234567832",
"amount": 690000,
"currency": "NGN",
"narration": "Salary payment for April"
},
{
"bank_code": "044",
"account_number": "1234567834",
"amount": 500000,
"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 bulk transfer endpoint with a batch_id query parameter.
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);
The batch_id is the data.id returned from the create bulk transfer response:
{
"status": "success",
"message": "Transfers fetched",
"meta": {
"page_info": {
"total": 2,
"current_page": 1,
"total_pages": 1
}
},
"data": [
{
"id": 190828,
"account_number": "1234567834",
"bank_code": "044",
"full_name": "Ade Bond",
"created_at": "2021-04-28T12:20:19.000Z",
"currency": "NGN",
"debit_currency": null,
"amount": 500000,
"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": "1234567832",
"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 more descriptive message ("Transaction is currently being processed", "Account resolve failed", "Successful").
Approval Process
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": []
}
Updated about 1 month ago