Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kotanipay.com/llms.txt

Use this file to discover all available pages before exploring further.

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
  • 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 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 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, 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