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 immediate202-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.