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.

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.reverse`
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 Reverse Event

event_code

string

default:"payment.reverse"

Event Code: payment.reverse

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 Reverse Event

event_code

string

default:"payrequest.reverse"

Event Code: payrequest.reverse

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

Field Descriptions

Field	Type	Description	Example
`ConnectorId`	string	Unique 6-digit identifier for the connector	`247482`
`SourceAccountNumber`	string	The account number from which the payment originates	`74629183`
`SourceAccountName`	string	The name registered on the payer’s account	`OneKhusa Suppliers Ltd`
`SourceInstitution`	string	The financial institution or bank that holds the payer’s account	`National Bank of Malawi`
`SourceReferenceNumber`	string	A unique reference identifier provided by the payer’s bank for this transaction	`SRC4K8L2M9Q1Z`
`BeneficiaryAccountNumber`	string	The account number of the receiving merchant or beneficiary	`102345678901`
`TransactionReferenceNumber`	string	A unique transaction reference generated by the system to identify the transaction	`TXN7D3P8L5Q2X`
`TransactionDescription`	string	A short description or purpose of the transaction	`Payment for invoice INV-2025-1010`
`TransactionAmount`	decimal	The total monetary value of the transaction	`320500.75`
`TransactionFee`	decimal	The fee charged for processing the transaction	`1000.00`
`TransactionDate`	datetime	The exact date and time when the transaction was processed (ISO 8601 format)	`2025-10-10T14:50:00Z`
`TransactionStatusCode`	string	Indicates the current status of the transaction	`S` (Success), `F` (Failed)
`TransactionCode`	string	An internal transaction code used for classification or processing	`BAM`, `MWM`
`ResponseCode`	String	The code set after the collection transaction is processed. Refer to Transaction Responses for more details.	`S100`
`TimedAccountNumber`	String	The generated unique temporary (short-lived) account number tied to a request-to-pay transaction	`11005533`
`ReferenceNumber`	String	The unique reference number generated by the merchant system tied to a request-to-pay transaction	`1020XDFS76GS777`
`SourceDescription`	String	The transaction description generated by the merchant system for the service/product(s) purchased by the customer tied to a request-to-pay transaction	`Samsung 85inch TV purchase`

Getting Started

Disbursements

Accept Payments

Merchants

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 Reverse Event

3. Request To Pay Success Event

4. Request To Pay Reverse Event

Webhook Payload Structure

Complete Payload Example

Field Descriptions

Getting Started

Disbursements

Accept Payments

Merchants

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 Reverse Event

​3. Request To Pay Success Event

​4. Request To Pay Reverse Event

​Webhook Payload Structure

​Complete Payload Example

​Field Descriptions

Overview

Webhook Configuration

Step 1: Access OneKhusa Portal

Step 2: Configure Your Webhook

Required Information

Webhook Events

1. Payment Success Event

2. Payment Reverse Event

3. Request To Pay Success Event

4. Request To Pay Reverse Event

Webhook Payload Structure

Complete Payload Example

Field Descriptions