Disbursements
Send money to multiple recipients
In a nutshell
Prepare a transfers array, submit a bulk payload, monitor each payout, and handle failures safely.
Some business models require sending money to multiple customers at the same time. For example, a payroll management system requires sending salaries to all employees at a certain time of the month. Large disbursements such as this require careful orchestration to ensure that all customers get paid and your system doesn’t get overwhelmed.
The Bulk Transfer endpoint handles large disbursement orchestration, helping businesses focus on delivering value to their customers.
Before you begin!
To send money on Paystack, you need API keys to authenticate your transfers. You can find your keys on the Paystack Dashboard under Developers → API configuration.
Copy linkCreating recipients
A transfer recipient is a beneficiary on your integration that you can send money to. Before sending money to your customers, you need to collect their details first, then use their details to create a transfer recipient. The Recipients page lists the recipient types available in your market.
Once created, save the recipient_code to your DB and make it available for the transfer initiation. This is a one time process in the transfer lifecycle. Since you’d be sending money to multiple recipients at interval, you’d only be fetching the recipients from your DB for each transfer request.
Copy linkManaging batches
Before creating the transfer request, you need to break the requests into batches. A batch is a subset of your requests that makes it easier to manage and track your transfers. In code, a batch is an array of transfer objects:
{
"transfers": [
{
"amount": 20000,
"reference": "acv_2627bbfe-1a2a-4a1a-8d0e-9d2ee6c31496",
"reason": "Bonus for the week",
"recipient": "RCP_gd9vgag7n5lr5ix"
},
{
"amount": 35000,
"reference": "acv_1bd0c1f8-78c2-463b-8bd4-ed9eeb36be50",
"reason": "Bonus for the week",
"recipient": "RCP_zpk2tgagu6lgb4g"
},
{
"amount": 15000,
"reference": "acv_11bebfc3-18b3-40aa-a4df-c55068c93457",
"reason": "Bonus for the week",
"recipient": "RCP_dfznnod8rwxlwgn"
}
]
}
Generate transfer reference
You should always generate a unique transfer reference for each transfer object. The transfer reference will help you keep track and manage each transfer. You can check out the generating a transfer reference section to learn more.
Each object in the transfers array is the same parameters for a single request. A batch shouldn't contain more than 100 items and each batch should be sent every 5 seconds:
| Parameter | Config |
|---|---|
| Batch size | <= 100 |
| Duration | Every 5 seconds |
Merchants who have set up transfer approval via URL should ensure they can approve all transfers in each batch within a few seconds (ideally, microseconds), else they risk the possibility of ending up with transfers with blocked status. So while planning the batch size, you should factor in the time it takes to verify the authenticity of each transfer.
The duration is to avoid getting rate limited. Sending multiple requests at short intervals would lead to a 429 (Too many requests) error.
With your batch properly planned and implemented, you can now initiate the bulk transfer.
Copy linkInitiate bulk transfer
Disable OTP
Disable OTP before you use bulk transfers. If you still want an approval step, use an approval URL instead.
In addition to the array of transfers in your batch, you need to add the currency and source to make a request to the Bulk Transfer endpoint:
POSTapi.paystack.co/transfer/bulk
curl https://api.paystack.co/transfer/bulk \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "NGN",
"source": "balance",
"transfers": [
{
"amount": 20000,
"reference": "acv_2627bbfe-1a2a-4a1a-8d0e-9d2ee6c31496",
"reason": "Bonus for the week",
"recipient": "RCP_gd9vgag7n5lr5ix"
},
{
"amount": 35000,
"reference": "acv_1bd0c1f8-78c2-463b-8bd4-ed9eeb36be50",
"reason": "Bonus for the week",
"recipient": "RCP_zpk2tgagu6lgb4g"
},
{
"amount": 15000,
"reference": "acv_11bebfc3-18b3-40aa-a4df-c55068c93457",
"reason": "Bonus for the week",
"recipient": "RCP_dfznnod8rwxlwgn"
}
]
}' \
-X POSTconst https = require("https");
const params = JSON.stringify({
"currency": "NGN",
"source": "balance",
"transfers": [
{
"amount": 20000,
"reference": "acv_2627bbfe-1a2a-4a1a-8d0e-9d2ee6c31496",
"reason": "Bonus for the week",
"recipient": "RCP_gd9vgag7n5lr5ix"
},
{
"amount": 35000,
"reference": "acv_1bd0c1f8-78c2-463b-8bd4-ed9eeb36be50",
"reason": "Bonus for the week",
"recipient": "RCP_zpk2tgagu6lgb4g"
},
{
"amount": 15000,
"reference": "acv_11bebfc3-18b3-40aa-a4df-c55068c93457",
"reason": "Bonus for the week",
"recipient": "RCP_dfznnod8rwxlwgn"
}
]
});
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/transfer/bulk",
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PAYSTACK_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(res.statusCode, JSON.parse(data));
});
});
req.on("error", (error) => {
console.error(error);
});
req.write(params);
req.end();<?php
$fields = [
"currency" => "NGN",
"source" => "balance",
"transfers" => [
[
"amount" => 20000,
"reference" => "acv_2627bbfe-1a2a-4a1a-8d0e-9d2ee6c31496",
"reason" => "Bonus for the week",
"recipient" => "RCP_gd9vgag7n5lr5ix",
],
[
"amount" => 35000,
"reference" => "acv_1bd0c1f8-78c2-463b-8bd4-ed9eeb36be50",
"reason" => "Bonus for the week",
"recipient" => "RCP_zpk2tgagu6lgb4g",
],
[
"amount" => 15000,
"reference" => "acv_11bebfc3-18b3-40aa-a4df-c55068c93457",
"reason" => "Bonus for the week",
"recipient" => "RCP_dfznnod8rwxlwgn",
],
],
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.paystack.co/transfer/bulk",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode($fields),
CURLOPT_HTTPHEADER => array(
"Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
"Content-Type: application/json",
"Cache-Control: no-cache",
),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>Unlike single transfers, the data parameter in the response object returns an array of objects. Each object represent a transfer in your batch. It’s important to note that the transfer status works like the single transfer. You can take a look at how transfers work if you need a refresher on how a transfer status is updated.
Test transfers always return success, because there is no processing involved. Live transfers are queued while they're being processed so you need to set up a webhook URL to receive the updates on your request.
Copy linkVerify a transfer
Paystack sends one webhook event for each transfer in a batch, not one per batch. If a batch has 100 transfers, you receive 100 events. Verify each transfer by its reference the same way you verify a single transfer.