Bulk payments let you send money to multiple beneficiaries in one request. Use this for payroll, vendor batches, contractor payments, and other grouped payouts.

Recommended flow:

Validate every beneficiary.
Build the payment batch.
Submit MAIN_ACCOUNT_BULK_PAYMENT.
Check the batch with BULK_PAYMENT_TSQ.

Step 1: Validate beneficiaries

Use BULK_NAME_ENQUIRY before submitting a bulk payment.

Unlike most Kuda requests, BULK_NAME_ENQUIRY sends data as an array.

{
  "serviceType": "BULK_NAME_ENQUIRY",
  "requestRef": "BNE20260603001",
  "data": [
    {
      "accountNumber": "2000000000",
      "bankCode": "999129"
    },
    {
      "accountNumber": "2000000001",
      "bankCode": "999129"
    }
  ]
}

Check every returned beneficiary before proceeding. Do not include rows with mismatched names, inactive accounts, or failed validation.

Step 2: Build the bulk payment request

Use the validated beneficiary names and bank codes in beneficiaryPaymentData.

Amounts are in kobo.

{
  "serviceType": "MAIN_ACCOUNT_BULK_PAYMENT",
  "requestRef": "BULK20260603001",
  "data": {
    "clientAccountNumber": "2000000000",
    "totalAmount": 700000,
    "notificationEmail": "[email protected]",
    "narration": "June payroll",
    "beneficiaryPaymentData": [
      {
        "feeAmountInKobo": 1000,
        "destinationAccountName": "Sample Employee One",
        "amountInKobo": 550000,
        "bankCode": "999129",
        "narration": "June payroll",
        "accountNumber": "2000000001"
      },
      {
        "feeAmountInKobo": 1000,
        "destinationAccountName": "Sample Employee Two",
        "amountInKobo": 150000,
        "bankCode": "999129",
        "narration": "June payroll",
        "accountNumber": "2000000002"
      }
    ]
  }
}

Before submitting:

confirm totalAmount equals the sum of beneficiary amountInKobo values
confirm the source account has enough balance
confirm the user has reviewed the batch
store the full batch and requestRef

Step 3: Interpret the response

A bulk payment response can show a code such as K06. Do not interpret that using bill-payment response-code meanings.

Use BULK_PAYMENT_TSQ to confirm the status of the batch and beneficiary payments.

Step 4: Check bulk payment status

BULK_PAYMENT_TSQ is another request-envelope exception. Use the original bulk payment reference as the top-level requestRef. You can omit data.

{
  "serviceType": "BULK_PAYMENT_TSQ",
  "requestRef": "BULK20260603001"
}

The status response may include each beneficiary, amount, fee, account number, and current status.

Operational checklist

Use UAT first.
Validate every beneficiary.
Preserve row order from upload to confirmation.
Store the original file or batch payload.
Store the requestRef.
Store the response from MAIN_ACCOUNT_BULK_PAYMENT.
Use BULK_PAYMENT_TSQ before retrying.
Provide a support export with batch reference and affected beneficiary rows when needed.

Common mistakes

Sending BULK_NAME_ENQUIRY.data as an object instead of an array.
Forgetting to check every beneficiary result.
Interpreting a batch-level response as final per-beneficiary success.
Retrying a batch before running BULK_PAYMENT_TSQ.
Losing the original batch requestRef.

Bulk Payments with the Kuda Business API