Account Top-up

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.

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

1. Successful Account Top-up (`payment.success`)

HTTP Event Headers

Webhook JSON Payload

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

HTTP Event Headers

Webhook JSON Payload

​1. Successful Account Top-up (payment.success)

​HTTP Event Headers

​Webhook JSON Payload

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

​HTTP Event Headers

​Webhook JSON Payload

1. Successful Account Top-up (`payment.success`)

HTTP Event Headers

Webhook JSON Payload

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

HTTP Event Headers

Webhook JSON Payload