Bulk Payments Service
Process multiple payment transactions with single OTP verification
1. Initiate Bulk Payment
Initiates a bulk payment request containing multiple payment transactions.
Subject: svc.account.<entity_id>.bulk_payment.initiate
Request
| Field | Type | Required | Description |
|---|---|---|---|
bulk_payment_id | string | required | Unique identifier for this bulk payment batch |
total_amount | number | required | Total amount in cents for all transactions |
payment_count | number | required | Number of payments in this batch |
description | string | required | Description of the bulk payment batch |
payments | array | required | Array of payment objects, one per transfer (see fields below) |
callback_url | string | optional | Webhook URL for status updates |
Payment object fields
Each item in the payments array must contain the following fields.
| Field | Type | Required | Description |
|---|---|---|---|
payment_id | string | required | Unique identifier for this payment |
amount | number | required | Amount in cents (ie. 1000 == ZAR 10.00) |
ref | string | required | Reference for the recipient (2-25 chars) |
real_time | boolean | required | Pay and clear now option |
own_ref | string | required | Your reference (2-50 chars) |
account_number | string | required | Recipient account number |
branch_code | string | required | Bank branch code |
name | string | required | Recipient name |
notification_email | string | optional | Must be valid email if provided |
Key Features
- Process up to 1000 payments in a single batch
- Single OTP verification for entire batch
- Mixed payment types supported (EFT and RTC)
- Atomic processing (all succeed or all fail)
- Real-time status tracking for each payment
Response
Possible Errors
400 Bad Request: Invalid request data | Exceeds batch limit | Insufficient total funds401 Unauthorized: Authentication failed409 Conflict: Duplicate bulk_payment_id500 Internal Server Error: Server-side error occurred
2. Verify Bulk Payment OTP
Verifies the OTP and processes the bulk payment batch.
Subject: svc.account.<entity_id>.bulk_payment.verify
Request
| Field | Type | Required | Description |
|---|---|---|---|
bulk_payment_id | string | required | The bulk payment identifier |
otp | string | required | The OTP code received |
Response
Processing Notes
After OTP verification, payments are processed asynchronously. Use the status endpoint or webhook callbacks to track individual payment completion.
Possible Errors
400 Bad Request: Invalid OTP | OTP expired404 Not Found: Bulk payment not found429 Too Many Requests: Too many OTP attempts
3. Get Bulk Payment Status
Retrieves the current status of a bulk payment batch and all individual payments.
Subject: svc.account.<entity_id>.bulk_payment.status
Request
| Field | Type | Required | Description |
|---|---|---|---|
bulk_payment_id | string | required | The bulk payment identifier |
Response
Status Values
pending_otp: Awaiting OTP verificationprocessing: Payments are being processedcompleted: All payments have been processedfailed: Batch processing failedcancelled: Batch was cancelled
4. Cancel Bulk Payment
Cancels a pending bulk payment batch (only available before OTP verification).
Subject: svc.account.<entity_id>.bulk_payment.cancel
Request
| Field | Type | Required | Description |
|---|---|---|---|
bulk_payment_id | string | required | The bulk payment identifier |
reason | string | optional | Cancellation reason |
Response
Possible Errors
400 Bad Request: Cannot cancel: already processing404 Not Found: Bulk payment not found
Implementation Notes
Best Practices
- Always validate total amounts before submission
- Implement retry logic for failed individual payments
- Use webhooks for real-time status updates
- Store bulk_payment_id for reconciliation
- Implement proper error handling for partial failures
Limits
- Maximum 1000 payments per batch
- OTP expires after 5 minutes
- Maximum 3 OTP attempts per batch
- Bulk payments cannot be modified after creation
Webhook Events
If a callback_url is provided, the following events will be sent:
bulk_payment.verified: OTP verified successfullybulk_payment.completed: All payments processedpayment.success: Individual payment succeededpayment.failed: Individual payment failed
For more information on webhook implementation, see the Notifications "Webhook" Service.