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.

Each amount is in the currency's major unit, so 50000 sends NGN 50,000, not 50,000 kobo. Responses report the same value.

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 the currency and 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 '{
    "currency": "NGN",
    "accounts": [
      { "account_number": "0123456789", "bank_code": "099858" },
      { "account_number": "2233445566", "bank_code": "057" },
      { "account_number": "9876543210", "bank_code": "011" }
    ]
  }'

A successful response returns the resolved account name for each entry:

JSON

{
  "requestId": "d3a1f200-84bc-4c21-a6f2-cc7e90d14b11",
  "requestTimestamp": "2026-03-21 10:00:00.000",
  "message": "Bulk name enquiry successful.",
  "statusCode": 200,
  "data": [
    {
      "accountNumber": "0123456789",
      "accountName": "John Doe",
      "bankCode": "099858",
      "sessionId": "999999118090260326113657535174973337"
    },
    {
      "accountNumber": "2233445566",
      "accountName": "Adaeze Okafor",
      "bankCode": "057",
      "sessionId": "999999118090260326113657535174973338"
    },
    {
      "accountNumber": "9876543210",
      "accountName": "Fatima Bello",
      "bankCode": "011",
      "sessionId": "999999118090260326113657535174973339"
    }
  ]
}

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:

JSON

{
  "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": "NGN242500"
    },
    "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:

JSON

{
  "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": "NGN50000" },
        "narration": "Salary - March 2026",
        "status": "Success"
      },
      {
        "reference": "TRN_XYZABC000002",
        "recipientAccountName": "Adaeze Okafor",
        "recipientAccountNumber": "2233445566",
        "recipientBankName": "Zenith Bank",
        "amount": { "value": 180000, "currency": "NGN", "formatted": "NGN180000" },
        "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": "NGN12500" },
        "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.

Initiating a bulk payout

Validating recipient accounts

Sending the batch

Checking bulk payout status

By Atlas reference

By source reference

Related guides

On this page