​
Why OneKhusa Uses Both?

When tracking a payout or collection flow through an integrated platform, it is easy to assume that a transaction simply succeeds or fails. However, across real financial infrastructure, a state change alone does not explain why something happened. To give you complete, automated visibility into every transaction without messy parsing scripts, OneKhusa separates a transaction’s lifecycle into two distinct components: Transaction Statuses and Transaction Responses. Understanding how these two layers work in tandem is the secret to a smooth, production-grade integration.

​
1. The Coding Engine: Transaction Responses

A Transaction Response represents the concrete, downstream reason code generated when a transaction attempts to route through our payment gateway to a carrier (like Airtel or TNM) or a bank or card network via switch. Instead of dealing with completely different error systems per channel, OneKhusa maps everything into a highly structured alpha-numeric alphanumeric coding standard:
  • The second character indicates the outcome type (S for Successful, E for Error, R for Reviewed, X for Rejected).
  • The trailing 3 digits, a unique number for response.
Because we explicitly separate these codes, your code can instantly handle exact accounting scenarios automatically without human intervention. Refer to Transaction Responses for more details.

​
Response Code Mapping Examples

​
2. The Operational State: Transaction Statuses

While a Response Code tells you exactly why a specific event occurred, a Transaction Status represents the overall high-level state of that transaction within its active lifecycle. Think of the Status as the macroscopic state machine (tracking where the payload is right now for example, whether it is still actively moving, stuck awaiting, or has reached a final, unalterable terminal state), while the Response Code acts as the granular microscopic context. Crucial Rule: Always evaluate Transaction Responses in direct conjunction with Transaction Statuses to derive the complete truth of a transaction. A transaction status tells your frontend UI how to behave, while the response code tells your database ledger and business logic exactly how to account for it.

​
How This Simplifies Your Integration

Using these two concepts together completely changes how you build your financial backend:
  1. Clear UI Routing: When an operation finishes, your application can look at the Transaction Status to determine if it should switch the user’s interface to a success page or an error modal. Simultaneously, it looks at the response code (E231 vs. E229) to display a clear, context-aware message to the user (e.g., “You cancelled the request on your phone” versus “Your wallet balance is insufficient”).
  2. Ledger Integrity: By checking for explicit response signals like S100 alongside a finalized state, your system can confidently mark a transaction as cleared, minimizing manual ledger balance checks and reconciliation disputes.
  3. Resilient Circuit Breaking: If your asynchronous webhook processing worker encounters errors like E205 (Network Timeout) or E248 (Issuer Inoperative), your architecture can automatically flag those specific channels as temporarily degraded and hold future processing queues rather than continually exhausting API limits.
For more information, refer to Transaction Statuses.