Overview
To ensure reliability and prevent duplicate processing, OneKhusa supports idempotent requests to avoid customers and merchants to be debited and credited more than once for payments, disbursements, and batch operations. OneKhusa idempotency implementation guarantees that the same request is processed only once, even if it is submitted multiple times due to network retries, timeouts, or user actions.When Idempotency Is Required?
Idempotency is mandatory for all OneKhusa endpoints that:- Initiate, receive and reverse collection transactions
- Initiate, approve, reject and reverse disbursement transactions whether in batch or single-transaction form
- Perform any irreversible or financial action
NOTE: Requests without a valid idempotency key shall be rejected.
Idempotency Key Header
Client systems must include a unique idempotency key in the request header:Key Requirements
| Rule | Description |
|---|---|
| Length | Minimum 15, maximum 80 characters |
| Allowed characters | Letters (A–Z, a–z), numbers (0–9), dash (-) |
| Uniqueness | Must be unique per API request |
| Case sensitivity | Case-sensitive |
Recommended Pattern
Example
Idempotency Retention Period
OneKhusa idempotency keys are retained for 24 hours. After expiration:- The key is no longer recognized
- A new request using the same key will be processed again
IMPORTANT: Clients should generate a new idempotency key for each new API request.
Client Best Practices
- Generate the idempotency key once per API request
- Reuse the same key when retrying a request
- Do not reuse keys for different operations
- Store the key on your side until a successful response is received
- If unsure whether a request succeeded, retry with the same key