The OneKhusa Push Payments & Hosted Checkout API provides specialized integration pathways for high-conversion pay-in flows. It focuses specifically on automated push authorization mechanisms across cards and mobile money wallets, alongside low-code hosted payment interfaces designed to minimize PCI-DSS compliance scope.

​
Core Push & Hosted Pathways

Summary of supported channels for push authorization and hosted checkouts:
Channel TypeAuthentication MethodIntegration EffortCustomer Flow
Mobile Money PushSTK Push / USSD PIN promptLow (API-driven)Prompt appears automatically on mobile handset for PIN approval
Card Payment PushNon-3D push / 3DS 2.0 OTPLow (Checkout-driven)Customer approves debit via bank app notification or 3DS challenge if the card supports this
Hosted Checkout ServiceMulti-factor gateway authenticationMinimal (Redirect)Redirects customer to a secure page presenting all payment options

​
Execution Workflows

​
1. Mobile Money Push Payments

  • Target Use Case: Mobile checkouts, micro-transactions, and instant digital account funding.
  • Technical Process: Your application sends a push payload containing the customer’s phone number. OneKhusa connects directly to the Mobile Network Operator (MNO) to dispatch a network-level STK push or USSD prompt. The customer completes authorization on their phone using their secret PIN.

​
2. Hosted Checkout Service

  • Target Use Case: E-commerce platforms requiring minimal PCI-DSS overhead and multi-pay-in readiness.
  • Technical Process: Your backend requests a session creation endpoint. OneKhusa generates a short-lived checkoutUrl that expires after 10 minutes. You redirect the user to this gateway page or launch it via modal overlay. The customer selects their preferred payment method (Mobile Money, Card, etc.), completes verification, and is automatically returned to your successCallbackUrl or failureCallbackUrl.

​
Supported Webhook Events

Because push payments depend on asynchronous user interaction on external devices, your application must subscribe to real-time status webhooks:
  • pushpayment.success: Triggered immediately when the customer successfully authenticates and authorizes the push debit payment on their mobile wallet or card app. Indicates settled/cleared funds.
  • pushpayment.failed: Dispatched when a push payment request is declined, cancelled by the user, timed out (handset unresponsiveness), or rejected due to insufficient funds etc.
  • pushpayment.reversed: Emitted when a previously successful transaction is automatically rolled back or reversed by the partner network switch or issuing bank due to various reasons.

​
Implementation Guidelines

  • Session Expiry Management: Always configure timeout windows for push notifications. Mobile money push prompts typically expire within 30 to 120 seconds if unacknowledged by the user.
  • Webhook Listener Implementation: Implement endpoint handlers for pushpayment.success, pushpayment.failed, and pushpayment.reversed to handle transactional lifecycle state changes programmatically.
  • PCI-DSS Scope Minimization: Use the Hosted Checkout Service to offload full card collection forms and reduce your application’s PCI compliance obligations.
  • Strict Idempotency: Header keys like Idempotency-Key should be generated for each attempt to avoid duplicate prompts being sent to the user’s handset.