When a customer or merchant prefunds (top-up) your OneKhusa merchant account through MNO wallet/bank account, OneKhusa processes the collection payment transaction asynchronously and notifies your callback URL endpoint. For merchant account top-ups originating from Mobile Money Wallets (Airtel Money, TNM Mpamba) or Commercial Banks, OneKhusa issues two core webhook events: payment.success and payment.reversed.
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 Account Top-up (payment.success)

The payment.success event is dispatched immediately after funds are successfully collected from an MNO wallet or bank account and credited to your OneKhusa merchant account. This event confirms that the top-up has cleared, allowing your application to safely update internal balances or execute internal processes.

​
HTTP Event Headers

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

​
Webhook JSON Payload

{
    "connectorId": 892353,
    "sourceAccountNumber": "74629183",
    "sourceAccountName": "OneKhusa Suppliers Ltd",
    "sourceInstitution": "National Bank of Malawi",
    "sourceReferenceNumber": "SRC4K8L2M9Q1Z",
    "beneficiaryAccountNumber": "102345678901",
    "transactionReferenceNumber": "250905SLFVXD",
    "transactionDescription": "Payment for invoice INV-2025-1010",
    "transactionAmount": 320500.75,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T14:50:00Z",
    "transactionStatusCode": "S",
    "transactionCode": "BAM",
    "responseCode": "S100"
}

​
2. Account Top-up Reversal (payment.reversed)

The payment.reversed event is emitted if a previously settled top-up transaction must be rolled back due to a bank reversal, network dispute, or carrier clearing correction. Receiving this event indicates that the corresponding funds have been debited from your OneKhusa merchant account balance, requiring your backend system to adjust the account/ledger accordingly.

​
HTTP Event Headers

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

​
Webhook JSON Payload

{
    "connectorId": 247482,
    "sourceAccountNumber": "74629183",
    "sourceAccountName": "OneKhusa Suppliers Ltd",
    "sourceInstitution": "Airtel Money",
    "sourceReferenceNumber": "SRC4K8L2M9Q1Z",
    "beneficiaryAccountNumber": "2659912345678",
    "transactionReferenceNumber": "251014SRTYXB",
    "transactionDescription": "Payment for invoice INV-2025-1010",
    "transactionAmount": 320500.75,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T14:50:00Z",
    "transactionStatusCode": "R",
    "transactionCode": "MWM",
    "responseCode": "S100"
}
For detailed field descriptions, refer to the Field Descriptions section in the Collection Webhooks Overview.