📖 Disbursements API Overview
The Disbursements API handles sending money (payouts) to recipients.Disbursement Types
Batch Disbursements
Send money to multiple recipients at once
- Upload files or JSON data
- Scheduled or immediate processing
Single Disbursement
Send money to one recipient
- Individual transactions
- Immediate processing
Batch Modes
Scheduled Disbursements
Future-dated transfers with specific execution date and time
- Set execution date/time in file upload
- Perfect for recurring payments
- View details: Authorization Workflows
Unscheduled Disbursements
Immediate transfers processed on upload
- No scheduling required
- Process immediately after upload
- View details: Authorization Workflows
Authorization Workflows
Authorization depends on merchant account configuration:2-Eye Principle
Initiator OnlySingle person can create and execute disbursements immediately. No approval required.
- Batch: Upload → Transfer
- Single: Create → Transfer immediately
4-Eye Principle
Initiator + Approver
Two-person control: one creates, another approves before funds transfer.
- Batch: Upload → Approve → Transfer
- Single: Create → Approve → Transfer
6-Eye Principle
Initiator + Reviewer + Approver
Three-person control: create, review, then approve before funds transfer.
- Batch: Upload → Review → Approve → Transfer
- Single: Create → Review → Approve → Transfer
- Authorization level is defined per merchant account (editable in portal).
- Determines workflow for all disbursements (batch & single).
Workflow Steps
2-Eye- Batch: Upload → Auto-transfer
- Single: Create → Auto-transfer
- Batch: Upload → Approve → Transfer
- Single: Create → Approve → Transfer
- Batch: Upload → Review → Approve → Transfer
- Single: Create → Review → Approve → Transfer
🔹 1. Creating Disbursements
Batch Upload
Upload File (/batch/addFile)
Upload File (/batch/addFile)
Upload Microsoft Excel or CSV file with disbursement transactions. Note that Microsoft Excel file can hold up to 50,000 transactions at one go, likewise CSV file up to 100,000 transaction
- Scheduled: Future execution date and time required
- Unscheduled: Immediate processing
- Validates account balance
Upload JSON (/batch/addJson)
Upload JSON (/batch/addJson)
Send bulk disbursement transactions through JSON payload and OneKhusa supports up to 10,000 transaction per request body at one go
- Programmatic integration
- Same validation rules as file upload
Single Disbursement
Add Single (/single/add)
Add Single (/single/add)
Create individual disbursement transaction
- Payment methods: Bank account or mobile wallet
- Authorization: 2-eye, 4-eye, or 6-eye principle
🔹 2. Transaction Management
Batch Management
Approve Batch
/batch/changeStatus → Move to approved status- Review batch before approval
- Set stage to ‘A’ for approval
Reject Batch
/batch/reject → Reject with reason- Provide rejection reason
- Cannot be reactivated
Mark as Reviewed
/batch/changeStatus → Mark as reviewed (6-eye only)- Review before final approval
- Required for 6-eye workflows
Cancel Batch
/batch/cancel → Cancel before execution- Stop processing before funds transfer
- Specify cancellation reason
Single Transaction Management
Approve Transaction
/single/changeStatus → Move to approved status- Move transaction to approved state
- Immediate funds transfer after approval
Reject Transaction
/single/reject → Reject with reason- Provide detailed rejection reason
- Prevents further processing
Mark as Reviewed
/single/changeStatus → Mark as reviewed (6-eye only)- Review before final approval
- Required for 6-eye workflows
🔹 3. Execution & Monitoring
Batch
Transfer Funds
/batch/transferFunds → Execute approved disbursements- Scheduled: Executes on set date/time
- Unscheduled: Executes immediately
- Handles partial failures + notifications
🔹 4. Information Retrieval
Batch Operations
Batch Operations
- Get Batches →
/batch/getBatches- List all batches with status - Get Batch →
/batch/getBatch- Detailed batch information - Get Batch Transactions →
/batch/getTransactions- All transactions in batch - Get Transaction →
/batch/getTransaction- Individual transaction details
Single Transaction Operations
Single Transaction Operations
- Get Single Transactions →
/single/getTransactions- List individual single disbursement transactions - Get Single Transaction →
/single/getTransaction- Specific transaction details
🔹 5. Utilities
Download Batch
/batch/download → Export uploaded batch files- Download original Microsoft Excel/CSV files
- Useful for record keeping
Generate Test Data
/batch/generateFakeTransactions → Create test batches- Generate test data
- Perfect for development/testing
Validation Rules
- Merchant account must be active
- Must have sufficient balance
- Must have an active settlement bank account
- Batch only: Scheduled disbursements cannot use past dates