Overview
The OneKhusa Payment Gateway Webhooks for Collections provide an easy way for merchants to receive real-time updates whenever customers make payments.
Instead of manually checking for new payments, webhooks automatically notify your system as soon as a payment event occurs.
Important: Do not trust any webhook notifications received, your system is required to
verify prior to processing to avoid unauthorised notifications being processed.
Webhook Configuration
Step 1: Access OneKhusa Portal
- Login at https://app.onekhusa.com
- Go to Developers → Webhooks
- Open Webhook Configuration page
Configure your webhook endpoint with the required information below.
Request Headers
| Header Name | Description | Example |
|---|
| X-OneKhusa-Webhook-Event | The request should include this header indicating the event type | payment.success, payment.reversed |
| X-OneKhusa-Webhook-Signature | A secret signature used to verify the authenticity of webhook notifications | a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 |
Webhook signatures should not be shared with unauthorised users.
Webhook Events
1. Payment Success Event
event_code
string
default:"payment.success"
Event Code: payment.success
- Description: Triggered when a payment transaction is successfully completed
- When Sent: After the payment has been processed and funds have been transferred
2. Payment Reversed Event
event_code
string
default:"payment.reversed"
Event Code: payment.reversed
- Description: Triggered when a payment collection transaction is reversed or refunded
- When Sent: After the reversal has been processed and funds have been returned to the customer
3. Request To Pay Success Event
event_code
string
default:"payrequest.success"
Event Code: payrequest.success
- Description: Triggered when a request-to-pay transaction is successfully completed
- When Sent: After the payment has been processed and funds have been credited to the merchant account
4. Request To Pay Reversed Event
event_code
string
default:"payrequest.reversed"
Event Code: payrequest.reversed
- Description: Triggered when a request-to-pay transaction is reversed
- When Sent: After the reversal has been processed and funds have been returned to the customer, the merchant account is debited
Webhook Payload Structure
All webhook payloads follow the same JSON structure with two main sections: Webhook and Transaction.
Complete Payload Example
Payment Success
Payment Reversed
Request To Pay Success
Request To Pay Reversed
{
"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"
}
{
"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"
}
{
"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",
"metaData": {
"timedAccountNumber": "11005533",
"referenceNumber": "1020XDFS76GS777",
"sourceDescription": "Samsung 85inch TV purchase"
}
}
{
"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",
"metaData": {
"timedAccountNumber": "11005533",
"referenceNumber": "1020XDFS76GS777",
"sourceDescription": "Samsung 85inch TV purchase"
}
}
