Bulk Payout
Bulk 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.
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 '{\n "accounts": [\
{ "accountNumber": "0123456789", "bankCode": "099858" },\
{ "accountNumber": "2233445566", "bankCode": "057" },\
{ "accountNumber": "9876543210", "bankCode": "011" }\
]\n }'
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 '{\n "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.