Important: Do not trust any webhook notifications received, your system is required to verify prior to processing to avoid unauthorised notifications being processed.

​
1. Batch Received (batch.received)

The batch.received event is dispatched immediately a batch file/JSON payload passed initial schema and funds validation rules and has been queued in readiness of the actual funds transfer to beneficiaries.

​
HTTP Request Example

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: batch.received
X-OneKhusa-Webhook-Signature: 9b71d2fe4a39281a8b329487c53d10a972c7247853b01938b8d901f421f1e298

​
JSON Payload

{
  "batchNumber": 20241013001,
  "merchantAccountNumber": 35253486,
  "uploadType": "CSV",
  "numberOfFailedTransactions": 5,
  "numberOfSuccessfulTransactions": 145,
  "numberOfTransactions": 150,
  "successfulTotalAmount": 150000.00,
  "capturerEmailAddress": "johndoe@gmail.com",
  "dateReceived": "2024-10-13T10:30:00Z",
  "dateCaptured": "2024-10-13T10:30:00Z"
}

​
2. Failed Batch (batch.failed)

The batch.failed event is emitted when the entire batch failed prior to funds transfer (e.g., critical error, account lock, insufficient merchant balance) and corresponding error file is available for download through merchant portal. When this occurs, any held principal funds and associated transaction fees are automatically credited back to your OneKhusa merchant account balance, requiring your backend to mark the batch payout attempt as failed.

​
HTTP Request Example

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: batch.failed
X-OneKhusa-Webhook-Signature: 7c82a1b94e310d2938ab4710293e847192039b821a82301938b8d901f421f1e2

​
JSON Payload

{
  "merchantAccountNumber": 35253486,
  "isBatchScheduled": false,
  "scheduledDate": null,
  "uploadType": "XLSX",
  "capturerEmailAddress": "johndoe@gmail.com",
  "dateCaptured": "2024-10-13T10:30:00Z",
  "errorMessage": "All transactions failed validation",
  "metaData": {
    "batchNumber": "12345678",
    "totalAmount": "150000.00",
    "numberOfTransactions": "150",
    "dateOccurred": "2024-10-13T10:30:00Z"
  }
}

​
Payload Field Reference

The table below details all attributes present within batch disbursement upload webhook notification payloads:
FieldTypeDescriptionExample
batchNumberintegerThe unique system-generated identifier assigned to the batch when it was received20241013001
merchantAccountNumberintegerThe OneKhusa merchant account number from which the batch funds are disbursed35253486
isBatchScheduledbooleanIndicates whether the batch was scheduled for future processing instead of immediate executionfalse
scheduledDatedatetimeThe date and time the batch is scheduled to be processed (only present when the batch is scheduled)2024-10-13T10:30:00Z
uploadTypestringThe file format used to upload the batch, either CSV or XLSXCSV
capturerEmailAddressstringThe email address of the merchant user who captured/uploaded the batchjohndoe@gmail.com
dateCaptureddatetimeThe date and time the batch was captured/uploaded by the merchant (ISO 8601)2024-10-13T10:30:00Z
dateReceiveddatetimeThe date and time the batch was received by the OneKhusa gateway (ISO 8601)2024-10-13T10:30:00Z
numberOfSuccessfulTransactionsintegerThe number of transactions in the batch that passed validation145
numberOfFailedTransactionsintegerThe number of transactions in the batch that failed validation5
numberOfTransactionsintegerThe total number of transactions contained in the batch150
successfulTotalAmountdecimalThe total monetary value of the transactions that passed validation150000.00
errorMessagestringA description of why the entire batch failed (present only in batch.failed)All transactions failed validation
metaDataobjectA nested object containing additional failure details (present only in batch.failed)