Overview
The Bulk Payments API enables clients to authenticate, create batches, attach transactions, and monitor batch processing status.
Base URL: {host}/pay/v1/e-payments
Authentication
1. Use Basic Auth (username / password) to obtain a token
2. Use Bearer Token for all subsequent requests
Authorization: Bearer {{auth_token}}
Workflow
- Authenticate — call the Auth endpoint to receive a bearer token
- Create Batch — initialize a new payment batch with a reference, count, and total amount
- Attach Transactions — add individual transactions to the batch one at a time
- Query Status — check the processing status of the batch by reference
Create Batch
POST /pay/v1/e-payments/auth/BulkServices/CreateBatch
Request Body
{
"reference": "D12345681",
"count": 2,
"total_amount": "100"
}
| Field | Type | Description |
|---|---|---|
| reference | string | Unique identifier for the batch |
| count | integer | Number of transactions to be included in the batch |
| total_amount | string | Total sum of all transaction amounts |
Response 200 OK
{
"api_reference": "17748599827890000",
"data": {
"reference": "D12345681",
"time": "2026-03-30T10:39:42"
},
"message": "Batch was created successfully.",
"status": 0,
"success": true
}
| Field | Type | Description |
|---|---|---|
| api_reference | string | System-generated unique reference for this API call |
| data.reference | string | Echo of the batch reference provided in the request |
| data.time | string | Timestamp when the batch was created (ISO 8601) |
| message | string | Human-readable status message |
| status | integer | Status code; 0 indicates success |
| success | boolean | Whether the request was successful |
Error Response 400 / 422
{
"api_reference": "17748599948380000",
"message": "reference has already been taken",
"status": 1,
"success": false
}
Attach Transactions
POST /pay/v1/e-payments/auth/BulkServices/AttachToBatch
Request Body
{
"narration": "Fundtransfer",
"reference": "D12345681",
"customer_name": "Jane Doe",
"sort_code": "186084101",
"account_number": "0978786406",
"amount": "50"
}
| Field | Type | Description |
|---|---|---|
| narration | string | Description or purpose of the transaction |
| reference | string | Reference of the batch to attach this transaction to |
| customer_name | string | Full name of the transaction recipient |
| sort_code | string | Bank sort code identifying the recipient's bank |
| account_number | string | Recipient's bank account number |
| amount | string | Transaction amount |
Response 200 OK
{
"message": "Transaction was attached successfully",
"success": true
}
| Field | Type | Description |
|---|---|---|
| message | string | Human-readable status message |
| success | boolean | Whether the transaction was attached successfully |
Error Response 400 / 422
{
"api_reference": "17748600242140000",
"message": "Cannot exceed batch transaction count with reference: D12345681!",
"status": 1,
"success": false
}
Bulk Attach Transactions
POST /pay/v1/e-payments/auth/BulkServices/BatchTxn
Attach multiple transactions to a batch in a single request instead of one-by-one.
Request Body
{
"reference": "{{$timestamp}}",
"count": 2,
"total_amount": "100",
"transactions": [
{
"narration": "Fundtransfer",
"reference": "{{$timestamp}}",
"customer_name": "Jane Doe",
"sort_code": "186084101",
"account_number": "0978786406",
"amount": "50"
},
{
"narration": "Fundtransfer",
"reference": "{{$timestamp}}",
"customer_name": "John Doe",
"sort_code": "186084101",
"account_number": "0978786407",
"amount": "50"
}
]
}
| Field | Type | Description |
|---|---|---|
| reference | string | Unique identifier for the batch |
| count | integer | Number of transactions in the batch |
| total_amount | string | Total sum of all transaction amounts |
| transactions | array | List of transaction objects to attach to the batch |
| transactions[].narration | string | Description or purpose of the transaction |
| transactions[].customer_name | string | Full name of the transaction recipient |
| transactions[].sort_code | string | Bank sort code identifying the recipient's bank |
| transactions[].account_number | string | Recipient's bank account number |
| transactions[].amount | string | Amount for this individual transaction |
Response 200 OK
{
"api_reference": "17748741488660000",
"data": {
"count": 2,
"reference": "1774874148",
"total_amount": "100"
},
"message": "Batch created and all transactions attached successfully.",
"status": 0,
"success": true
}
| Field | Type | Description |
|---|---|---|
| api_reference | string | System-generated unique reference for this API call |
| data.count | integer | Number of transactions attached to the batch |
| data.reference | string | The batch reference |
| data.total_amount | string | Total amount across all attached transactions |
| message | string | Human-readable status message |
| status | integer | Status code; 0 indicates success |
| success | boolean | Whether all transactions were attached successfully |
Error Response 400 / 422
{
"api_reference": "17748577834780000",
"message": "Amount mismatch: declared 1 but sum of transactions is 140.",
"status": 1,
"success": false
}
Query Batch Status
GET /pay/v1/e-payments/auth/BulkServices/QueryBatchStatus
Query Parameter
?reference=1774859915
| Parameter | Type | Description |
|---|---|---|
| reference | string | The batch reference to query |
Response 200 OK
{
"api_reference": "17748614683260000",
"data": {
"batch_no": "1774859915",
"batch_status": "Pending Approval",
"count": 2,
"total_amount": "140",
"transactions": [
{
"account_number": "0978786406",
"amount": "70",
"customer_name": "Jane Doe",
"narration": "Batch",
"reference": "17748599152390000",
"sort_code": "186084101",
"status": "Pending Approval",
"txn_date": "2026-03-30 10:38:35"
},
{
"account_number": "0978786406",
"amount": "70",
"customer_name": "Jane Doe",
"narration": "Batch",
"reference": "17748599152390001",
"sort_code": "186084101",
"status": "Pending Approval",
"txn_date": "2026-03-30 10:38:35"
}
]
},
"message": "Batch transactions retrieved successfully.",
"status": 0,
"success": true
}
| Field | Type | Description |
|---|---|---|
| api_reference | string | System-generated unique reference for this API call |
| data.batch_no | string | The batch number / reference |
| data.batch_status | string | Current status of the batch (e.g. Pending Approval, Processed) |
| data.count | integer | Number of transactions in the batch |
| data.total_amount | string | Total amount across all transactions in the batch |
| data.transactions | array | List of individual transaction records |
| data.transactions[].account_number | string | Recipient's bank account number |
| data.transactions[].amount | string | Transaction amount |
| data.transactions[].customer_name | string | Recipient's full name |
| data.transactions[].narration | string | Transaction description |
| data.transactions[].reference | string | Unique reference for the individual transaction |
| data.transactions[].sort_code | string | Bank sort code of the recipient's bank |
| data.transactions[].status | string | Current status of the transaction |
| data.transactions[].txn_date | string | Date and time the transaction was recorded |
| message | string | Human-readable status message |
| status | integer | Status code; 0 indicates success |
| success | boolean | Whether the request was successful |
Error Response 400 / 422
{
"api_reference": "17748615153920000",
"message": "Missing required keys: [\"reference\"]",
"status": 1,
"success": false
}
Get Merchant Balance
GET /pay/v1/e-payments/auth/BulkServices/GetMerchantBalance
Returns the current account balance for the authenticated merchant. No request parameters are required.
Response 200 OK
{
"api_reference": "17748994758260000",
"data": {
"account_number": "0001",
"balance": "1880"
},
"message": "Merchant balance retrieved successfully.",
"status": 0,
"success": true
}
| Field | Type | Description |
|---|---|---|
| api_reference | string | System-generated unique reference for this API call |
| data.account_number | string | Merchant's account number |
| data.balance | string | Current account balance |
| message | string | Human-readable status message |
| status | integer | Status code; 0 indicates success |
| success | boolean | Whether the request was successful |
Error Response 401 Unauthorized
{
"message": "Unauthorized",
"status": "error"
}