Collection Webhooks

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

Step 2: Configure Your Webhook

Configure your webhook endpoint with the required information below.

Required Information

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

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

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

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

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"
    }
  }

For the complete field descriptions and architectural overview, see the Collection Webhooks Overview.

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

Overview

Webhook Configuration

Step 1: Access OneKhusa Portal

Step 2: Configure Your Webhook

Required Information

Request Headers

Webhook Events

1. Payment Success Event

2. Payment Reversed Event

3. Request To Pay Success Event

4. Request To Pay Reversed Event

Webhook Payload Structure

Complete Payload Example

​Overview

​Webhook Configuration

​Step 1: Access OneKhusa Portal

​Step 2: Configure Your Webhook

​Required Information

Request Headers

​Webhook Events

​1. Payment Success Event

​2. Payment Reversed Event

​3. Request To Pay Success Event

​4. Request To Pay Reversed Event

​Webhook Payload Structure

​Complete Payload Example

Overview

Webhook Configuration

Step 1: Access OneKhusa Portal

Step 2: Configure Your Webhook

Required Information

Webhook Events

1. Payment Success Event

2. Payment Reversed Event

3. Request To Pay Success Event

4. Request To Pay Reversed Event

Webhook Payload Structure

Complete Payload Example