Bulk Payments
Process large batches of payments efficiently with our bulk payment API. Perfect for payroll, vendor payments, and mass disbursements.
Overview
The Bulk Payments API allows you to create and process batches of payments in a single operation. Features include:
- Upload payment lists via CSV or JSON
- Validate all recipients before processing
- Optional approval workflow for large batches
- Real-time progress tracking
- Download results with success/failure details
- Support for M-Pesa and bank transfers
Batch Lifecycle
| Status | Description |
|---|---|
DRAFT | Batch created, items can still be added |
VALIDATING | Recipients are being validated |
VALIDATED | All items validated and ready for submission |
PENDING_APPROVAL | Awaiting approval (if required) |
APPROVED | Approved and queued for processing |
PROCESSING | Payments are being processed |
COMPLETED | All payments processed successfully |
PARTIALLY_COMPLETED | Some payments failed |
FAILED | Batch processing failed |
CANCELLED | Batch was cancelled |
CSV Format
When uploading payments via CSV, use the following format:
bulk-payment-template.csv
phoneNumber,bankCode,accountNumber,recipientName,amount,narration+254712345678,,,John Doe,5000,Salary Jan 2024+254722345678,,,Jane Smith,6000,Salary Jan 2024,01,1234567890,Bob Wilson,10000,Vendor Payment,02,0987654321,Alice Brown,15000,Supplier Payment
Note: For M-Pesa payments, provide phoneNumber. For bank transfers, provide bankCode and accountNumber.
API Reference
Create Bulk Payment
Create a new bulk payment batch with items.
Upload CSV
Upload a CSV file to create or add items to a bulk payment batch.
Get CSV Template
Download the CSV template for bulk payments.
Get Bulk Payment
Retrieve details of a bulk payment batch.
List Bulk Payments
List all bulk payment batches with optional filters.
Get Batch Items
Retrieve individual payment items within a batch.
Validate Batch
Validate all recipients in a batch before processing.
Submit Batch
Submit a validated batch for processing.
Cancel Batch
Cancel a bulk payment batch. Only batches not yet processing can be cancelled.
Code Examples
Process Payroll (JavaScript)
process-payroll.js
1async function processPayroll(walletId, employees) {2 const API_KEY = process.env.WASAAPAY_API_KEY;3 const BASE_URL = 'https://api.wasaapay.com/api/v1/partner';45 // Step 1: Create the bulk payment6 const createResponse = await fetch(`${BASE_URL}/bulk-payments`, {7 method: 'POST',8 headers: {9 'Content-Type': 'application/json',10 'X-API-Key': API_KEY,11 'X-Idempotency-Key': `payroll_${new Date().toISOString().slice(0,7)}`,12 },13 body: JSON.stringify({14 sourceWalletId: walletId,15 name: `Payroll ${new Date().toLocaleDateString('en-US', { month: 'long', year: 'numeric' })}`,16 provider: 'MPESA',17 items: employees.map(emp => ({18 phoneNumber: emp.phone,19 recipientName: emp.name,20 amount: emp.salary,21 narration: `Salary ${new Date().toLocaleDateString('en-US', { month: 'short', year: 'numeric' })}`,22 })),23 requiresApproval: true,24 externalReference: `PAYROLL-${new Date().toISOString().slice(0,7)}`,25 }),26 });2728 const batch = await createResponse.json();29 if (!batch.success) throw new Error(batch.message);3031 console.log(`Batch created: ${batch.data.id}`);32 console.log(`Total: KES ${batch.data.totalAmount}`);3334 // Step 2: Validate the batch35 await fetch(`${BASE_URL}/bulk-payments/${batch.data.id}/validate`, {36 method: 'POST',37 headers: { 'X-API-Key': API_KEY },38 });3940 // Step 3: Wait for validation (poll or use webhooks)41 let status = 'VALIDATING';42 while (status === 'VALIDATING') {43 await new Promise(r => setTimeout(r, 2000));44 const check = await fetch(`${BASE_URL}/bulk-payments/${batch.data.id}`, {45 headers: { 'X-API-Key': API_KEY },46 }).then(r => r.json());47 status = check.data.status;48 }4950 // Step 4: Submit for processing/approval51 const submitResponse = await fetch(`${BASE_URL}/bulk-payments/${batch.data.id}/submit`, {52 method: 'POST',53 headers: { 'X-API-Key': API_KEY },54 });5556 const result = await submitResponse.json();57 console.log(`Batch submitted: ${result.data.status}`);5859 return batch.data;60}6162// Example usage63const employees = [64 { name: 'John Doe', phone: '+254712345678', salary: 50000 },65 { name: 'Jane Smith', phone: '+254722345678', salary: 60000 },66 { name: 'Bob Wilson', phone: '+254733345678', salary: 45000 },67];6869processPayroll('wallet_company123', employees)70 .then(batch => console.log('Payroll batch:', batch.reference))71 .catch(console.error);
Webhooks
Receive notifications about batch processing progress. See Webhooks documentation for setup.
Bulk Payment Events
| Event | Description |
|---|---|
bulk_payment.validated | Batch validation completed |
bulk_payment.approved | Batch was approved |
bulk_payment.processing | Batch processing started |
bulk_payment.completed | All payments processed successfully |
bulk_payment.partially_completed | Some payments failed |
bulk_payment.failed | Batch processing failed |
bulk_payment.item.completed | Individual payment completed |
bulk_payment.item.failed | Individual payment failed |
Limits & Pricing
| Limit | Value |
|---|---|
| Max items per batch | 10,000 |
| Max batch amount | KES 100,000,000 |
| CSV file size | 10 MB |
| Concurrent batches | 5 |
Best Practices
- Validate before submitting: Always run validation to catch invalid recipients early
- Use approval workflows: Enable approvals for large batches to prevent errors
- Monitor progress: Use webhooks to track batch status in real-time
- Handle partial failures: Download results to identify and retry failed payments
- Idempotency: Use unique idempotency keys to prevent duplicate batches
- Sufficient balance: Ensure wallet has enough balance for entire batch before submitting