Before we dive into using the bulk transfer feature, let’s consider a scenario:

Picture this: you're a developer at a bank, and your job is to make salary payments easier for corporate clients. With Flutterwave’s Bulk Transfer API, you can help businesses send salaries directly to their employees' accounts smoothly and on a large scale.

Here’s how to use the Bulk Transfer API for salary disbursement:

Create a Bulk Payout Request: To initiate a bulk payout, use the bulk transfer endpoint to specify the recipients’ details and amounts to be transferred.

curl --location 'http://api.flutterwave.com/developersandbox/bulk-transfers'  
--header 'X-Trace-Id: {{REPLACE_WITH_UNIQUE_IDENTIFIER}}'  
--header 'Content-Type: application/json'  
--header 'Authorization: Bearer {{REPLACE_WITH_API_ACCESS_TOKEN}}'  
--data '{  
   "action":"instant",  
   "type":"bank",  
   "bulk_reference":"{{REPLACE_WITH_API_UNIQUE_REFERENCE}}",  
   "source_currency":"NGN",  
   "destination_currency":"NGN",  
   "bulk_data":[  
      {  
         "amount":{  
            "value":100,  
            "applies_to":"source_currency"  
         },  
         "recipient":{  
            "name":{  
               "first":"Mary",  
               "middle":"Japa",  
               "last":"Han"  
            },  
            "type": "bank",  
            "currency":"NGN",  
            "bank":{  
               "account_number":"0690000031",  
               "code":"044",  
               "account_type":"checking"  
            }  
         },  
         "sender":{  
            "address":{  
               "city":"Lagos",  
               "country":"NG",  
               "line1":"123 Main Street",  
               "postal_code":"10001",  
               "state":"Lagos"  
            }  
         }  
      },  
      {  
         "amount":{  
            "value":100,  
            "applies_to":"source_currency"  
         },  
         "recipient":{  
            "currency":"NGN",  
            "type": "bank",  
            "bank":{  
               "account_number":"0690000032",  
               "code":"044",  
               "account_type":"checking"  
            }  
         },  
         "sender":{  
            "address":{  
               "city":"Lagos",  
               "country":"NG",  
               "line1":"123 Main Street",  
               "postal_code":"10001",  
               "state":"Lagos"  
            }  
         }  
      }  
   ]  
}'

The key aspects to consider when using the Bulk Transfer API are the action and the payment_instruction parameters.

action: This defines when Flutterwave processes your transfer request. In your case, you’ve chosen an instant transfer. Alternatively, you can defer the transfer or schedule it for a later time.
payement_instruction defines how Flutterwave should handle your transfer request. In your case, you’ve instructed Flutterwave to pay your customer in NGN (destination_currency) from your NGN Flutterwave account (source_currency). You can also process international transfers by specifying the currency while Flutterwave manages the conversion and other operational overheads.

You’ll get a response similar to this:

{
    "status": "success",
    "message": "Bulk transfer created",
    "data": {
        "id": "btr_kz5sSNP8IrnRWQ",
        "type": "bank",
        "action": "instant",
        "status": "NEW",
        "created_datetime": "2025-01-23T11:09:44.193969884Z"
    }
}

Monitor the Transfer Status: If you need to check the status of the transfers, you can use any of the following methods:

Retrieve Transfer Endpoint: Query the endpoint directly to get the status of the transfers.
Webhook (Recommended): Set up a webhook to receive real-time updates on the transfer status.
Callback URL: Use a callback URL, if available, to handle status updates.

Next Steps

To learn more about implementing the bulk transfer API and other edge cases you can handle with it, check out the Bulk Transfer API documentation.