> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kotanipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Payments Flow

> How to disburse funds to many recipients at once — validate a CSV, assign wallets, and track batch processing

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.

***

## Before You Start

* An API key — see [API Keys](/v3/getting-started/api-keys)
* Funded payout wallets for each currency in your CSV
* A `callbackUrl` — each individual payment fires a `transaction.withdrawal.status.updated` webhook as it settles

***

## 1. Validate Your CSV

Call [POST /api/v3/bulk-payments/validate-csv](/v3/api-reference/bulk-payments/validate-csv) 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 [POST /api/v3/bulk-payments/preview-batches](/v3/api-reference/bulk-payments/preview-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 [POST /api/v3/bulk-payments/create-batches](/v3/api-reference/bulk-payments/create-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 `batchId`s 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](/v3/essentials/webhooks#transactionwithdrawalstatusupdated).

<Note>
  For overall batch progress, poll the batch status endpoints rather than relying solely on per-payment webhooks.
</Note>

***

## 6. Track Progress

* [GET /api/v3/bulk-payments/batches/:batchId](/v3/api-reference/bulk-payments/get-batch) — current batch status and success/fail counts
* [GET /api/v3/bulk-payments/batches/:batchId/payments](/v3/api-reference/bulk-payments/get-batch-payments) — status of each individual payment
* [GET /api/v3/bulk-payments/transactions/:transactionId](/v3/api-reference/bulk-payments/list-transactions) — overview of all batches under a transaction

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

***

## Monitoring from the Dashboard

1. Log in to [integrator.kotanipay.com](https://integrator.kotanipay.com)
2. Navigate to **Bulk Payments** in the left sidebar
3. Select a transaction to see all batches and individual payment statuses