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 Payout (payout.success)

The payout.success event is dispatched immediately after funds are successfully transferred from your merchant account and credited to the beneficiary’s mobile money wallet (e.g., Airtel Money, TNM Mpamba) or commercial bank account. This event confirms final settlement, allowing your backend to safely update transaction accounts and confirm payout completion.

​
HTTP Request Example

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

​
JSON Payload

{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812UIK",
  "sourceReferenceNumber": "SRC4K8L2M9Q1Z",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MBA",
  "transactionAmount": 1000.00,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "S",
  "responseCode": "S100",
  "connectorId": 220400
}

​
2. Failed Payout (payout.failed)

The payout.failed event is emitted when an individual payout request fails during execution (e.g., due to an invalid/inactive beneficiary account, network timeout, or carrier rejection). 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 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: payout.failed
X-OneKhusa-Webhook-Signature: 7c82a1b94e310d2938ab4710293e847192039b821a82301938b8d901f421f1e2

​
JSON Payload

{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812HMM",
  "sourceReferenceNumber": "671DS8L2M9Q1Z",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MMW",
  "transactionAmount": 1000.00,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "F",
  "responseCode": "E999",
  "connectorId": 220400
}

​
3. Payout Reversal (payout.reversed)

The payout.reversed event is emitted if a previously settled payout transaction must be rolled back due to a downstream bank reversal, carrier settlement error, or compliance adjustment. Receiving this event indicates that the transaction 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: payout.reversed
X-OneKhusa-Webhook-Signature: d3840e2f5b610c2838491823abf10928aef49102938471b028471920d39b821a

​
JSON Payload

{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812HMM",
  "sourceReferenceNumber": "671DS8L2M9Q1Z",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MMW",
  "transactionAmount": 1000.00,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "R",
  "responseCode": "S100",
  "connectorId": 220400
}

​
Payload Field Reference

The table below details all attributes present within single disbursement webhook notification payloads:
FieldTypeDescriptionExample
sourceAccountNumberstringThe account number from which the disbursement originates85231947
sourceReferenceNumberstringA unique identifier from the source systemQKAHXD200923
beneficiaryAccountNumberstringThe account number of the recipient1111203344
beneficiaryInstitutionstringThe name of the institution where the beneficiary’s account is heldNational Bank of Malawi
transactionReferenceNumberstringA unique transaction reference generated by the system251005TYHKOPL
transactionAmountdecimalThe monetary value of the disbursement transaction15000.00
transactionFeedecimalThe fee charged for processing the transaction1000.00
transactionDescriptionstringA brief description of the transactionSalary Payment for September
transactionDatedatetimeThe date and time when the transaction was initiated (ISO 8601)2025-10-10T09:00:00Z
processedDatedatetimeThe date and time when the transaction was completed (ISO 8601)2025-10-10T09:11:10Z
transactionStatusCodestringThe status of the transaction (S = Success, F = Failed, R = Reversed)S
beneficiaryAccountNamestringThe name registered on the beneficiary’s accountJohn Doe
responseCodestringThe code set after the disbursement transaction is processed. Refer to Transaction Responses for more details.S000
transactionCodestringAn internal transaction code used for classification or processing. For disbursements, this will be MBA (Merchant To Account) or MMW (Merchant To Mobile Wallet). Refer to Transaction Types for more details.MBA
connectorIdintegerThe unique number representing the institution (bank/MNO) used for the disbursement transaction220400