Overview

​

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.

​

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:

​

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.