Atlas DocumentationBulk Payout
Send payments to multiple recipients in a single batch using Atlas bulk payouts.
Bulk payouts allow you to transfer funds from your Atlas business account to multiple recipients in a single API call. The batch is processed asynchronously, making it well-suited for payroll runs, mass vendor disbursements, and any scenario where you need to pay many recipients at once.
Initiating a bulk payout
Initiating a bulk payout is a two-step process, first you have to validate all recipient accounts, then you queue the batch via the Atlas API. The request body takes a top-level source_reference to identify the batch, and a transfers array containing one object per recipient. Each transfer object specifies the recipient's bank details, the amount, a narration, and the currency.
Note
A bulk payout batch must contain at least 2 transfers.
Validating recipient accounts
Before sending the batch, validate all recipient accounts using the Run Bulk Account Name Enquiry endpoint. Pass an array of account numbers and bank codes:
curl -X POST "https://atlas.tryduplo.com/api/v1/banking/bulk-name-enquiry" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"accounts": [
{ "accountNumber": "0123456789", "bankCode": "099858" },
{ "accountNumber": "2233445566", "bankCode": "057" },
{ "accountNumber": "9876543210", "bankCode": "011" }
]
}'A successful response returns the resolved account name for each entry:
{
"requestId": "d3a1f200-84bc-4c21-a6f2-cc7e90d14b11",
"requestTimestamp": "2026-03-21 10:00:00.000",
"message": "Bulk name enquiry successful.",
"statusCode": 200,
"data": [
{
"accountNumber": "0123456789",
"bankCode": "099858",
"accountName": "John Doe",
"status": "success"
},
{
"accountNumber": "2233445566",
"bankCode": "057",
"accountName": "Adaeze Okafor",
"status": "success"
},
{
"accountNumber": "9876543210",
"bankCode": "011",
"accountName": "Fatima Bello",
"status": "success"
}
]
}Use the returned accountName values as the account_name for each transfer in the batch.
Sending the batch
With recipient accounts validated, use the Initiate Bulk Bank Payout endpoint to queue the batch.
Ensure sufficient balance
Before initiating a bulk payout, ensure you have sufficient balance in your Atlas business account to cover all transfers and their fees.
curl -X POST "https://atlas.tryduplo.com/api/v1/payout/bank-transfer/bulk" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"source_reference": "BULK_PAYOUT_001",
"transfers": [
{
"account_number": "0123456789",
"bank_code": "099858",
"bank_name": "Kuda Microfinance Bank",
"account_name": "John Doe",
"amount": 50000,
"narration": "Salary - March 2026",
"type": "bank_transfer",
"currency": "NGN"
},
{
"account_number": "2233445566",
"bank_code": "057",
"bank_name": "Zenith Bank",
"account_name": "Adaeze Okafor",
"amount": 180000,
"narration": "Salary - March 2026",
"type": "bank_transfer",
"currency": "NGN"
},
{
"account_number": "9876543210",
"bank_code": "011",
"bank_name": "First Bank of Nigeria",
"account_name": "Fatima Bello",
"amount": 12500,
"narration": "Salary - March 2026",
"type": "bank_transfer",
"currency": "NGN"
}
]
}'On a successful request, you'll receive a response confirming the batch has been queued, along with a reference you can use to track its status:
{
"requestId": "7f3a1b22-c4d8-4e91-b2a0-5e6f7c8d9e0f",
"requestTimestamp": "2026-03-21 12:00:00.000",
"message": "Bulk payout queued successfully.",
"statusCode": 200,
"data": {
"reference": "BULK_TRN_ABCDEF123456",
"sourceReference": "BULK_PAYOUT_001",
"totalTransfers": 3,
"totalAmount": {
"value": 242500,
"currency": "NGN",
"formatted": "NGN2425"
},
"status": "Pending"
}
}Checking bulk payout status
Because bulk payouts are processed asynchronously, you can poll for the batch status using either the Atlas reference or your source_reference.
By Atlas reference
Use the Get Bulk Payout Status endpoint:
curl -X GET "https://atlas.tryduplo.com/api/v1/payout/bulk/BULK_TRN_ABCDEF123456/status" \
-H "Authorization: Bearer your_api_key" \
-H "Accept: application/json"By source reference
If you'd prefer to look up the batch using your own source_reference, use the Get Bulk Payout Status By Source Reference endpoint:
curl -X GET "https://atlas.tryduplo.com/api/v1/payout/bulk-by-source-reference/BULK_PAYOUT_001/status" \
-H "Authorization: Bearer your_api_key" \
-H "Accept: application/json"Both status endpoints return the same response shape, showing the overall batch status and a breakdown of each individual transfer:
{
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"requestTimestamp": "2026-03-21 12:05:00.000",
"message": "Bulk payout status fetched successfully.",
"statusCode": 200,
"data": {
"reference": "BULK_TRN_ABCDEF123456",
"sourceReference": "BULK_PAYOUT_001",
"status": "Completed",
"totalTransfers": 3,
"successful": 3,
"failed": 0,
"transfers": [
{
"reference": "TRN_XYZABC000001",
"recipientAccountName": "John Doe",
"recipientAccountNumber": "0123456789",
"recipientBankName": "Kuda Microfinance Bank",
"amount": { "value": 50000, "currency": "NGN", "formatted": "NGN500" },
"narration": "Salary - March 2026",
"status": "Success"
},
{
"reference": "TRN_XYZABC000002",
"recipientAccountName": "Adaeze Okafor",
"recipientAccountNumber": "2233445566",
"recipientBankName": "Zenith Bank",
"amount": { "value": 180000, "currency": "NGN", "formatted": "NGN1800" },
"narration": "Salary - March 2026",
"status": "Success"
},
{
"reference": "TRN_XYZABC000003",
"recipientAccountName": "Fatima Bello",
"recipientAccountNumber": "9876543210",
"recipientBankName": "First Bank of Nigeria",
"amount": { "value": 12500, "currency": "NGN", "formatted": "NGN125" },
"narration": "Salary - March 2026",
"status": "Success"
}
]
}
}Atlas also sends webhook notifications as each transfer in the batch is processed. You will receive an OUT_FLOW_PENDING_EVENT when a transfer is initiated, an OUT_FLOW_SUCCESS_EVENT when it completes, and an OUT_FLOW_FAILED_EVENT if it fails. See the webhook events reference for the full payload shapes.
Related guides
How is this guide?
Last updated on