​
Architectural Overview & Integration Principles

In high-volume payment integration, relying on backend polling to verify transaction outcomes creates unnecessary system latency and network overhead. OneKhusa’s Collection Webhooks implement an event-driven, push-based model designed to deliver real-time transaction settlement notifications directly to your application infrastructure the moment funds are verified.

​
1. Core Event-Driven Flow

When a transaction occurs, whether through a hosted checkout page or a direct payment API prompt, OneKhusa decouples payment initiation from transaction confirmation. Accept Payments

​
Event Lifecycle

1.1. Initiation & Pending State : Your client receives an initial response (e.g., 200-OK) indicating the payment prompt/TAN or checkout session has started. 1.2. Asynchronous Processing : The payment moves through carrier pathways (MNO mobile wallets, card networks, or bank transfers). 1.3. Event Dispatch : Once a transaction reaches a final state as verified, the OneKhusa Webhook Engine constructs a notification and pushes it to your registered event callback URL. 1.4. Local Handshake & Queueing : Your system validates the authenticity of the transaction payload, immediately acknowledges receipt with an HTTP 200 OK, and hands the event off to your local background service for fulfillment.

​
2. Event Lifecycle Categories

You can configure endpoint listeners inside the OneKhusa Developer (Merchant) Portal based on the specific lifecycle stages your platform needs to handle either through standard checkout or direct API push payment:
CategoryDescription
Successful CollectionsDispatched as soon as funds clear from an MNO wallet or bank account or payment card, confirming that the money is safely credited to your merchant account.
Collection ReversalsTriggered in the event of an authorized chargeback, customer dispute, or network-level settlement reversal requiring a debit entry in your internal accounting.

​
3. Integration Standards & Security Architecture

To ensure high availability and prevent unauthorized access, your webhook receiver should adhere to three core security and reliability principles:

​
3.1 Cryptographic Identity Verification

Every incoming transmission contains a secure HMAC-SHA512 signature header (X-OneKhusa-Webhook-Signature) and X-OneKhusa-Webhook-Event (this header indicates the event type such as payment.success, payrequest.success etc.). Your endpoint must calculate an identical HMAC hash using your raw request payload string and merchant webhook secret before accepting the transaction. This guarantees that the notification truly originated from OneKhusa and guards against spoofing attacks.

​
3.2 Non-Blocking Acknowledgment

To maintain gateway health and prevent callback timeouts, your HTTP handler must remain lightweight. Avoid running synchronous database locks, complex transaction/account updates, or third-party email notifications within the incoming HTTP request thread. Verify the signature, queue the event internally, and respond immediately with 200 OK. Remember that our webhook engine waits for your system response within 30 seconds otherwise it will retry to deliver webhook notification.

​
3.3 Idempotent Event Handling

Network interruptions can occasionally cause duplicate event deliveries due to webhook engine retries. Your receiving service should track incoming unique event reference (transactionReferenceNumber) from transaction payload. If a duplicate message arrives, your system should acknowledge it with a 200 OK without re-processing the order or double-crediting system account balances.

​
4. Delivery Guarantees & Retry Circuit Breaker

If your endpoint is temporarily offline, undergoing maintenance, or returns anything other than an explicit success status (such as a 5xx error or connection timeout), OneKhusa’s webhook delivery engine automatically activates an exponential backoff retry schedule (e.g., 1 minute, 2 minutes, 4 minutes). This ensures that temporary infrastructure blips do not lead to dropped payment records or unfulfilled orders.

​
Field Descriptions

This section describes the common properties/fields for collection webhook payloads.
FieldTypeDescriptionExample
ConnectorIdintegerUnique 6-digit identifier for the connector247482
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
ResponseCodeStringThe code set after the collection transaction is processed. Refer to Transaction Responses for more details.S100
TimedAccountNumberStringThe generated unique temporary (short-lived) account number tied to a request-to-pay transaction11005533
ReferenceNumberStringThe unique reference number generated by the merchant system tied to a request-to-pay transaction1020XDFS76GS777
SourceDescriptionStringThe transaction description generated by the merchant system for the service/product(s) purchased by the customer tied to a request-to-pay transactionSamsung 85inch TV purchase