Payment Gateway Integration in Nepal: Complete eSewa and Khalti Developer Guide

Nepal's digital payment ecosystem has matured significantly, with platforms like eSewa, Khalti, ConnectIPS, and IME Pay enabling millions of transactions daily. For developers building e-commerce platforms, SaaS products, or service marketplaces targeting the Nepali market, integrating these payment gateways is essential. However, each gateway has its own API patterns, authentication mechanisms, and verification workflows. This guide covers the practical steps to integrate Nepal's major payment gateways into modern web applications, with a focus on security, reliability, and user experience.

How Does the eSewa Payment Integration Flow Work?

eSewa uses a redirect-based payment flow. Your application generates a payment request with the transaction amount, a unique product delivery URL, and a success/failure callback URL. The user is redirected to eSewa's payment page, where they authenticate and confirm the transaction. After payment, eSewa redirects back to your success URL with transaction parameters. Critically, you must then verify the transaction server-side by calling eSewa's verification API with the reference ID—never trust client-side callbacks alone, as they can be forged. The verified response confirms the payment amount and status, after which you can safely fulfill the order.

// eSewa payment initiation (simplified)
const esewaConfig = {
  amount: '1000',
  tax_amount: '130',
  total_amount: '1130',
  transaction_uuid: crypto.randomUUID(),
  product_code: 'EPAYTEST',
  product_service_charge: '0',
  product_delivery_charge: '0',
  success_url: 'https://yoursite.com/api/payment/esewa/success',
  failure_url: 'https://yoursite.com/api/payment/esewa/failure',
  signed_field_names: 'total_amount,transaction_uuid,product_code',
};
// Generate HMAC signature and submit form to eSewa endpoint

What Is the Khalti Payment Integration Process?

Khalti offers both a web SDK and a server-to-server API for payment processing. The recommended approach for web applications is the Khalti Web Checkout SDK, which opens a payment modal within your application—providing a smoother user experience than a full redirect. The user enters their Khalti credentials, completes the OTP verification, and the SDK returns a token and transaction details to your frontend callback. You then send this token to your backend, which calls Khalti's verification endpoint to confirm the payment before fulfilling the order. Khalti also supports recurring payments and subscription billing, making it suitable for SaaS applications.

What Security Measures Are Essential for Payment Integration?

• Always verify transactions server-side using the gateway's verification API—never rely on client-side callbacks
• Use HMAC-SHA256 signatures to ensure payment request parameters have not been tampered with
• Store API keys and merchant secrets in environment variables, never in client-side code or version control
• Implement idempotency keys to prevent duplicate payment processing during network retries
• Log all payment events with transaction IDs for audit trails and dispute resolution
• Use database transactions to ensure order status and payment status are always consistent

How Do You Handle Payment Failures and Edge Cases?

Robust payment integration must gracefully handle numerous edge cases: users abandoning the payment page, network timeouts during verification callbacks, duplicate webhook deliveries, and partial payment scenarios. Implement a payment status state machine with states like INITIATED, PENDING, VERIFIED, FAILED, and REFUNDED. Use webhook listeners with retry logic and idempotent processing to handle asynchronous payment confirmations. BidHex has extensive experience integrating Nepali payment gateways into production applications, ensuring that every edge case is handled and every transaction is accurately tracked and reconciled.