​
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

  1. Login at https://app.onekhusa.com
  2. Go to Developers → Webhooks
  3. Open Webhook Configuration page

​
Step 2: Configure Your Webhook

Configure your webhook endpoint with the required information below.

​
Required Information

FieldDescriptionExample
Callback URLYour secure HTTPS endpoint for receiving webhook notificationshttps://yourdomain.com/webhooks/khusa
Event TypeThe types of events you want your webhook to listen forpayment.success and payment.reverse

​
Callback URL Requirements

Ensure your webhook endpoint meets the following requirements:
  • HTTPS Protocol: The URL must use HTTPS for secure communication
  • Public Accessibility: The URL must be publicly accessible and reachable from the internet
  • POST Request Support: The endpoint should accept HTTP POST requests with JSON payloads
  • Response Confirmation: Respond with HTTP 200 OK to confirm successful receipt of the webhook

​
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

​
Event Types Summary

Event TypeEvent CodeDescriptionWhen Triggered
Payment Successpayment.successIndicates that the payment transaction is completed successfullyAfter successfully processing the payment
Payment Reversepayment.reverseIndicates that the payment transaction is reversedAfter successfully processing the reversal

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

​
Field Descriptions

FieldTypeDescriptionExample
SourceAccountNumberstringThe account number from which the payment originates74629183
SourceAccountNamestringThe name registered on the payer’s accountOneKhusa Suppliers Ltd
SourceInstitutionstringThe financial institution or bank that holds the payer’s accountNational Bank of Malawi
SourceReferenceNumberstringA unique reference identifier provided by the payer’s bank for this transactionSRC4K8L2M9Q1Z
BeneficiaryAccountNumberstringThe account number of the receiving merchant or beneficiary102345678901
TransactionReferenceNumberstringA unique transaction reference generated by the system to identify the transactionTXN7D3P8L5Q2X
TransactionDescriptionstringA short description or purpose of the transactionPayment for invoice INV-2025-1010
TransactionAmountdecimalThe total monetary value of the transaction320500.75
TransactionFeedecimalThe fee charged for processing the transaction1000.00
TransactionDatedatetimeThe exact date and time when the transaction was processed (ISO 8601 format)2025-10-10T14:50:00Z
TransactionStatusCodestringIndicates the current status of the transactionS (Success), F (Failed)
TransactionCodestringAn internal transaction code used for classification or processingBAM, MWM