Welcome to the OneKhusa Developer Portal. OneKhusa is a high-performance, secure, robust, reliable and developer-first payment gateway infrastructure engineered to support any ecosystem for processing payments. OneKhusa is licensed as a Payment System Operator (PSO) provided by the regulator (central bank) and supports ISO8583, ISO20022 payment instructions. Our platform bridges the gap between modern software architectures and local banking infrastructure (including NATSWITCH, mobile money networks, and institutional billing points), allowing you to embed secure, resilient payment capabilities into your applications with minimal friction.

​
What Developers Should Expect

We believe that integration speed is directly proportional to documentation clarity. When building with OneKhusa, you should expect an environment designed by engineers, for engineers:
  • Zero-DI Capabilities: Our native SDKs are built to be light and flexible. If you are building microservices or minimal console applications where you don’t want heavy Dependency Injection abstractions, our SDKs support clean, manual initialization out of the box (new OneKhusaClient(options)).
  • Predictable REST Patterns: Clean, resource-oriented HTTP endpoints using standard JSON request/response bodies and status codes.
  • Production-Grade Guardrails: Idiomatic error responses, clear parameter validation before requests hit network boundaries, and automatic handling of complex payload criteria.
  • True Sandbox Environment: An isolated simulation environment that mirrors live processing behaviour, down to transaction state delays and webhook retries, without moving real currency.

​
Key Areas of Focus

When integrating with OneKhusa, your architecture should focus on three foundational pillars: Security, Idempotency, and Lifecycle Resilience.

​
1. Robust Security (No-Mercy Compliance)

Financial infrastructure demands strict security. All communications must occur over TLS 1.3. API Authentication: Secured via explicit, cryptographically random API Keys created and used when generating access token using OAuth 2.0 (OIDC) for subsequent API calls. Payload Encryption: High-risk transaction data utilizes authenticated encryption via AES-GCM to ensure data confidentiality and integrity. Webhook Verification: All asynchronous callbacks from OneKhusa include a cryptographic signature (X-OneKhusa-Signature). You must verify this signature before processing any state changes.

​
2. Strict Idempotency

To prevent double-charging due to network dropouts or client retries, all mutate operations (such as /collections/requestToPay/initiate) require an Idempotency-Key header. If a request times out, you can safely retry the exact same request with the same key. OneKhusa guarantees that the transaction will execute exactly once, returning the identical cached response for subsequent hits.

​
3. Asynchronous Execution & Reconciliations

Financial transactions across clearing networks are inherently decoupled. The Workflow: Most payment operations return an immediate 202-Accepted or 201-Created status with a unique tracking identifier. State Updates: Your system should rely on incoming Webhooks to receive final status updates/events such as SUCCESS, FAILED etc. The Fallback: Always implement a polling or reconciliation fallback loop. If a webhook retry period expires, your system should proactively query the transaction status endpoint using a scheduled worker to guarantee consistency.

​
API vs. SDK: Choosing Your Integration Path

OneKhusa provides two ways to connect to the network. Both environments hit the same reliable engine, allowing you to choose the abstraction layer that matches your tech stack.

​
The Direct REST API

Perfect for cross-platform applications, custom language microservices, or quick integrations where you want absolute control over the HTTP raw socket. Refer to API reference for more details.

​
The Native SDK

For teams building on structured backend ecosystems (such as modern .NET), our official SDK wraps the REST API into high-performance, type-safe binaries. It includes built-in models, local request validation prior to network flight, and seamless thread pool management. Refer to SDK for more details.