Skip to main content
Bulk payments let you disburse to hundreds or thousands of recipients in a single operation. Upload a CSV of recipients, assign a payout wallet per currency, and Kotani Pay processes the payments asynchronously — one batch per currency.
You need an API key and a reachable callbackUrl — see the Quickstart if you haven’t set those up. For this flow you also need a funded payout wallet for every currency in your CSV. Each payment fires its own withdrawal webhook as it settles.

​
1. Validate Your CSV

Call Validate CSV File with your CSV file. Kotani Pay validates every row and returns:
  • A summary grouped by currency with totals
  • Row-level errors with line numbers if any data is invalid
Fix any errors and re-upload. A file hash is computed to prevent duplicate submissions.

​
2. Preview Batches

Call Preview Bulk Payment Batches with the file hash. This shows you exactly how many batches will be created, the total per currency, and which wallet you’ll need to assign to each.

​
3. Create Batches

Call Create Bulk Payment Batches, assigning a payout wallet to each currency. Kotani Pay verifies your balance, creates the transaction record, and queues all batches for processing. Save the transactionId and batchIds from the response — you’ll need them to track progress.

​
4. Processing Happens Asynchronously

Batches process in the background. For each recipient, Kotani Pay initiates a disbursement to their mobile money wallet or bank account. Your payout balance is debited as each payment is sent.
  • If a disbursement succeeds, the recipient gets an SMS from the mobile money network
  • If a disbursement fails, the debit is automatically reversed

​
5. Kotani Pay Notifies You

Each individual payment fires a transaction.withdrawal.status.updated webhook as it settles — the same payload as a standard withdrawal. See Webhooks.
For overall batch progress, poll the batch status endpoints rather than relying solely on per-payment webhooks.

​
6. Track Progress

Batch statuses move from pending → processing → completed, completed_with_errors, or failed.

​
Monitoring from the Dashboard

  1. Log in to backoffice.kotanipay.com
  2. Navigate to Bulk Payments in the left sidebar
  3. Select a transaction to see all batches and individual payment statuses