Batch Upload

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:

Field	Type	Description	Example
`batchNumber`	integer	The unique system-generated identifier assigned to the batch when it was received	`20241013001`
`merchantAccountNumber`	integer	The OneKhusa merchant account number from which the batch funds are disbursed	`35253486`
`isBatchScheduled`	boolean	Indicates whether the batch was scheduled for future processing instead of immediate execution	`false`
`scheduledDate`	datetime	The date and time the batch is scheduled to be processed (only present when the batch is scheduled)	`2024-10-13T10:30:00Z`
`uploadType`	string	The file format used to upload the batch, either `CSV` or `XLSX`	`CSV`
`capturerEmailAddress`	string	The email address of the merchant user who captured/uploaded the batch	`johndoe@gmail.com`
`dateCaptured`	datetime	The date and time the batch was captured/uploaded by the merchant (ISO 8601)	`2024-10-13T10:30:00Z`
`dateReceived`	datetime	The date and time the batch was received by the OneKhusa gateway (ISO 8601)	`2024-10-13T10:30:00Z`
`numberOfSuccessfulTransactions`	integer	The number of transactions in the batch that passed validation	`145`
`numberOfFailedTransactions`	integer	The number of transactions in the batch that failed validation	`5`
`numberOfTransactions`	integer	The total number of transactions contained in the batch	`150`
`successfulTotalAmount`	decimal	The total monetary value of the transactions that passed validation	`150000.00`
`errorMessage`	string	A description of why the entire batch failed (present only in `batch.failed`)	`All transactions failed validation`
`metaData`	object	A nested object containing additional failure details (present only in `batch.failed`)

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

1. Batch Received (`batch.received`)

HTTP Request Example

JSON Payload

2. Failed Batch (`batch.failed`)

HTTP Request Example

JSON Payload

Payload Field Reference

​1. Batch Received (batch.received)

​HTTP Request Example

​JSON Payload

​2. Failed Batch (batch.failed)

​HTTP Request Example

​JSON Payload

​Payload Field Reference

1. Batch Received (`batch.received`)

HTTP Request Example

JSON Payload

2. Failed Batch (`batch.failed`)

HTTP Request Example

JSON Payload

Payload Field Reference