When a customer authorizes a push payment through the card channel or on their Mobile Money handset, OneKhusa processes the collection payment transaction asynchronously and notifies your callback URL endpoint. Push payment requests are initiated for Mobile Money Wallets (Airtel Money, TNM Mpamba) and card payments, and OneKhusa issues three core webhook events: pushpayment.success, pushpayment.failed and pushpayment.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 Push Payment (pushpayment.success)

The pushpayment.success event is dispatched immediately after the customer authorizes the payment — via PIN on their Mobile Money handset or via 3DS/OTP on their card — and the funds are successfully collected. This event confirms that the payment has settled, allowing your application to safely fulfil the order or grant the service the customer paid for.

​
HTTP Event Headers

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

​
Webhook JSON Payload

{  
  "connectorId": 550044,
  "sourceAccountNumber": "265880000000",
  "sourceAccountName": "John Doe",
  "sourceInstitution": "TNM MPAMBA",
  "sourceReferenceNumber": "DII338KORK1",
  "merchantReferenceNumber": "RAE-ABK-44728",
  "beneficiaryAccountNumber": "54833324",
  "transactionReferenceNumber": "260921VK4NEG9V",
  "transactionDescription": "Payment for Order #10234",
  "transactionAmount": 15000,
  "transactionFee": 157.5,
  "transactionDate": "2026-09-21T11:18:42.8474205+02:00",
  "transactionStatusCode": "S",
  "transactionCode": "DMP",
  "responseCode": "S100"
}

​
2. Push Payment Failure (pushpayment.failed)

The pushpayment.failed event is emitted when the push payment cannot be completed, for example when the customer cancels the prompt, enters an incorrect PIN, lets the prompt time out, or has insufficient funds. Receiving this event indicates that no funds were collected, so the transaction must be treated as unsuccessful and the customer must not be considered to have completed the payment. The failure reason is reported in the errorMessages array of the payload.

​
HTTP Event Headers

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: pushpayment.failed
X-OneKhusa-Webhook-Signature: a8f3b019388d901f421f1e2989b71d2fe4a39281a8b329487c53d10a972c7247

​
Webhook JSON Payload

{
  "connectorId": 550044,
  "sourceAccountNumber": "265995558588",
  "sourceInstitution": "Airtel Money",
  "merchantReferenceNumber": "RAE-ABK-44728",
  "beneficiaryAccountNumber": "54833324",
  "transactionDescription": "Payment for Order #10233",
  "transactionCode": "DMP",
  "transactionAmount": 100,
  "transactionDate": "2026-09-24T07:48:28.9498753Z",
  "transactionStatusCode": "F",
  "responseCode": "E307",
  "errorMessages": [
    "Transaction Not Found"
  ]
}

​
3. Push Payment Reversal (pushpayment.reversed)

The pushpayment.reversed event is emitted if a previously settled push payment transaction must be rolled back, for example due to duplicate debit reconciliation by the Mobile Money operator. 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: pushpayment.reversed
X-OneKhusa-Webhook-Signature: a8f3b019388d901f421f1e2989b71d2fe4a39281a8b329487c53d10a972c7247

​
Webhook JSON Payload

{
  "connectorId": 550044,
  "sourceAccountNumber": "265995458441",
  "sourceAccountName": "John Doe",
  "sourceInstitution": "Airtel Money",
  "sourceReferenceNumber": "DII338KORK1",
  "merchantReferenceNumber": "RAE-ABK-44728",
  "beneficiaryAccountNumber": "54833324",
  "transactionReferenceNumber": "260921VK4NEG9V",
  "transactionDescription": "Payment for Order #10234",
  "transactionAmount": 15000,
  "transactionFee": 157.5,
  "transactionDate": "2026-09-21T11:18:42.8474205+02:00",
  "transactionStatusCode": "R",
  "transactionCode": "DMP",
  "responseCode": "S100"
}
For detailed field descriptions, refer to the Field Descriptions section in the Collection Webhooks Overview.