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

​
1. Successful Batch Payout (batch.payout.success)

The batch.payout.success event is dispatched immediately a chunk/group of up-to-10 transactions within the batch completed successfully and funds credited to beneficiary’s mobile wallets and bank accounts. This event confirms final funds settlement, allowing your backend to safely update transaction accounts and confirm chunk payout completion.

​
HTTP Request Example

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

​
JSON Payload

[
  {
    "sourceAccountNumber": "98743210",
    "sourceReferenceNumber": "ATSY27181",
    "beneficiaryAccountNumber": "1234567890",
    "beneficiaryAccountName": "John Doe",
    "transactionReferenceNumber": "251105PCDRLL",
    "transactionAmount": 1000.50,
    "transactionFee": 10.00,
    "transactionDate": "2024-01-15T09:00:00Z",
    "processedDate": "2024-01-15T10:30:00Z",
    "transactionStatusCode": "S",
    "responseCode": "S100",
    "transactionCode": "MBA",
    "connectorId": 213346
  },
  {
    "sourceAccountNumber": "98743210",
    "sourceReferenceNumber": "BTSY27182",
    "beneficiaryAccountNumber": "0987654321",
    "beneficiaryAccountName": "Jane Smith",
    "transactionReferenceNumber": "TXN-REF-12345",
    "transactionAmount": 2500.75,
    "transactionFee": 15.00,
    "transactionDate": "2024-01-15T09:05:00Z",
    "processedDate": "2024-01-15T10:35:00Z",
    "transactionStatusCode": "S",
    "responseCode": "S100",
    "transactionCode": "MMW",
    "connectorId": 213346
  }
]

​
2. Failed Batch Payout (batch.payout.failed)

The batch.payout.failed event is emitted immediately a chunk/group of up-to-10 transactions within the batch fails (e.g., invalid account, destination network down). 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.payout.failed
X-OneKhusa-Webhook-Signature: 7c82a1b94e310d2938ab4710293e847192039b821a82301938b8d901f421f1e2

​
JSON Payload

[
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "WTSY27181",
    "beneficiaryAccountNumber": "1234567890",
    "beneficiaryAccountName": "John Doe",
    "transactionReferenceNumber": "TXN-REF-67890",
    "transactionAmount": 1000.50,
    "transactionFee": 10.00,
    "transactionDate": "2024-01-15T09:00:00Z",
    "processedDate": "2024-01-15T10:30:00Z",
    "transactionStatusCode": "F",
    "responseCode": "E233",
    "transactionCode": "MBA",
    "connectorId": 224368
  },
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "BTSY27ER3",
    "beneficiaryAccountNumber": "0987654321",
    "beneficiaryAccountName": "Jane Smith",
    "transactionReferenceNumber": "TXN-REF-12345",
    "transactionAmount": 2500.75,
    "transactionFee": 15.00,
    "transactionDate": "2024-01-15T09:05:00Z",
    "processedDate": "2024-01-15T10:35:00Z",
    "transactionStatusCode": "F",
    "responseCode": "E228",
    "transactionCode": "MMW",
    "connectorId": 224368
  }
]

​
3. Batch Payout Reversal (batch.payout.reversed)

The batch.payout.reversed event is emitted if the previously settled batch payout transactions must be rolled back due to a downstream bank reversal, carrier settlement error, or compliance adjustment. Receiving this event indicates that the batch transactions’ state has been converted to Reversed, requiring your backend system to adjust system accounts accordingly.

​
HTTP Request Example

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: batch.payout.reversed
X-OneKhusa-Webhook-Signature: d3840e2f5b610c2838491823abf10928aef49102938471b028471920d39b821a

​
JSON Payload

[
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "WFKY27181",
    "beneficiaryAccountNumber": "1234567890",
    "beneficiaryAccountName": "John Doe",
    "transactionReferenceNumber": "251105PCDRLL",
    "transactionAmount": 1000.50,
    "transactionFee": 10.00,
    "transactionDate": "2024-01-15T09:00:00Z",
    "processedDate": "2024-01-15T10:30:00Z",
    "transactionStatusCode": "R",
    "responseCode": "S100",
    "transactionCode": "MBA",
    "connectorId": 213346
  },
  {
    "sourceAccountNumber": "9876543210",
    "sourceReferenceNumber": "ERSY27956",
    "beneficiaryAccountNumber": "1234567890",
    "beneficiaryAccountName": "John Doe",
    "transactionReferenceNumber": "251105PCDRLL",
    "transactionAmount": 1000.50,
    "transactionFee": 10.00,
    "transactionDate": "2024-01-15T09:00:00Z",
    "processedDate": "2024-01-15T10:30:00Z",
    "transactionStatusCode": "R",
    "responseCode": "S100",
    "transactionCode": "MBA",
    "connectorId": 213346
  }
]

​
Payload Field Reference

The table below details all attributes present within batch disbursement transfer webhook notification payloads:
FieldTypeDescriptionExample
sourceAccountNumberstringThe account number from which the disbursement originates98743210
sourceReferenceNumberstringA unique identifier from the source systemATSY27181
beneficiaryAccountNumberstringThe account number of the recipient1234567890
beneficiaryAccountNamestringThe name registered on the beneficiary’s accountJohn Doe
transactionReferenceNumberstringA unique transaction reference generated by the system251105PCDRLL
transactionAmountdecimalThe monetary value of the disbursement transaction1000.50
transactionFeedecimalThe fee charged for processing the transaction10.00
transactionDatedatetimeThe date and time when the transaction was initiated (ISO 8601)2024-01-15T09:00:00Z
processedDatedatetimeThe date and time when the transaction was completed (ISO 8601)2024-01-15T10:30:00Z
transactionStatusCodestringThe status of the transaction (S = Success, F = Failed, R = Reversed)S
responseCodestringThe code set after the disbursement transaction is processed. Refer to Transaction Responses for more details.S100
transactionCodestringAn internal transaction code used for classification. For disbursements, this will be MBA (Merchant To Account) or MMW (Merchant To Mobile Wallet).MBA
connectorIdintegerThe unique number representing the institution (bank/MNO) used for the disbursement transaction213346