Bulk Transfers

Easily send money to multiple recipients with our bulk transfer option.

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.

Node.js

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

You’ll get a response like this:

200 OK

{
  "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.

Sample request

axios.get('https://api.flutterwave.com/v3/transfers', {
  params: { batch_id: 9145 },  // Passing the batch_id as a query parameter
  headers: {
    Authorization: `Bearer ${process.env.FLW_SECRET_KEY}`,
  },
})
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response?.data));

The batch_id is the data.id returned from the create bulk transfer response:

Sample Response (200 OK)

{
  "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").

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.

Sample Response(400 Error)

{
    "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": []
}