Khalti Integration in React / Next.js: Production Setup (2026)

Setup

• Khalti merchant account — sign up at khalti.com merchant portal
• Live secret key: from merchant dashboard. Store in .env.local as KHALTI_SECRET (never commit)
• Test secret key: from dev.khalti.com for UAT
• Webhook / return URL: https://yoursite.com/payment/return

Initiation API route (App Router)

app/api/payment/initiate/route.ts

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { orderId, amountPaisa, customer } = await req.json();
  const body = {
    return_url: 'https://yoursite.com/payment/return',
    website_url: 'https://yoursite.com',
    amount: amountPaisa,        // amount in paisa, e.g. 100000 = NPR 1000
    purchase_order_id: orderId,
    purchase_order_name: 'Order ' + orderId,
    customer_info: customer,
  };
  const r = await fetch('https://khalti.com/api/v2/epayment/initiate/', {
    method: 'POST',
    headers: {
      Authorization: 'Key ' + process.env.KHALTI_SECRET!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  if (!r.ok) return NextResponse.json({ error: 'init failed' }, { status: 500 });
  const data = await r.json();
  return NextResponse.json({ paymentUrl: data.payment_url, pidx: data.pidx });
}

Frontend pay button

components/PayWithKhalti.tsx

'use client';
import { useState } from 'react';

export default function PayWithKhalti({ orderId, amountPaisa }: { orderId: string; amountPaisa: number }) {
  const [loading, setLoading] = useState(false);
  async function pay() {
    setLoading(true);
    const res = await fetch('/api/payment/initiate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ orderId, amountPaisa, customer: { name: 'Customer', email: '', phone: '' } }),
    });
    const data = await res.json();
    if (data.paymentUrl) window.location.href = data.paymentUrl;
    else alert('Payment initiation failed');
    setLoading(false);
  }
  return (
    <button onClick={pay} disabled={loading}>{loading ? 'Loading…' : 'Pay with Khalti'}</button>
  );
}

Return-URL handler with lookup verification

app/payment/return/page.tsx

import { redirect } from 'next/navigation';

async function lookup(pidx: string) {
  const r = await fetch('https://khalti.com/api/v2/epayment/lookup/', {
    method: 'POST',
    headers: {
      Authorization: 'Key ' + process.env.KHALTI_SECRET!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ pidx }),
    cache: 'no-store',
  });
  return r.json();
}

export default async function Page({ searchParams }: { searchParams: Promise<{ pidx?: string }> }) {
  const sp = await searchParams;
  if (!sp.pidx) return <p>No payment reference.</p>;

  const result = await lookup(sp.pidx);
  if (result.status === 'Completed') {
    // markOrderPaid(...) — idempotent! use pidx as unique key in your DB
    return <p>Payment successful. Order is being processed.</p>;
  }
  if (result.status === 'Pending') {
    return <p>Payment pending. We will email you when confirmed.</p>;
  }
  return <p>Payment {result.status.toLowerCase()}. Please try again or contact us.</p>;
}

Idempotency in the DB

The lookup may be called multiple times (browser refresh, race conditions). Mark the order paid only once. SQL pattern:

Postgres example

-- ensure pidx column has a unique constraint on the orders table
ALTER TABLE orders ADD CONSTRAINT orders_pidx_unique UNIQUE (khalti_pidx);

-- when handling a successful lookup
INSERT INTO payment_events (order_id, pidx, status, amount_paisa, processed_at)
VALUES ($1, $2, 'Completed', $3, NOW())
ON CONFLICT (pidx) DO NOTHING
RETURNING id;
-- if this returned a row, then transition the order; otherwise no-op (already processed)

Error states to handle

• Pending: bank transfer hasn't cleared. Show "we'll email when confirmed"; re-lookup every 10 min for 1 hour
• User canceled: show friendly cancel message; preserve cart
• Failed: friendly error; allow retry with different method
• Refunded: if you query an old transaction; surface accurately
• Amount mismatch: alarming — log + alert ops + do not auto-process

Common production gotchas

• Sandbox vs production keys: Khalti gives separate keys for sandbox and live. A surprising number of Nepali sites accidentally ship sandbox keys to production. Use environment variables (KHALTI_SECRET_KEY_LIVE) and verify on deploy
• Webhook verification: always verify the lookup endpoint on your server before marking an order paid. Client-side success callback is not authoritative — it can be spoofed
• Idempotency: Khalti may call your verify endpoint twice if its network hiccups. Treat orders by pidx + status, not by timestamp
• CORS: Khalti's checkout uses a redirect flow now, not popup — CORS rarely an issue, but if you embed the legacy popup, set frame-ancestors in CSP
• Retry-after handling: Khalti rate-limits aggressively in sandbox; back off exponentially in tests

Refund handling

Khalti supports partial and full refunds via the merchant dashboard or API. For programmatic refunds: call POST /api/v2/epayment/refund/ with the original pidx and the refund amount. The funds typically return to the customer wallet within 24 hours. Always store the refund pidx alongside your order record so support staff can trace disputes. For broader payment-stack design choices, see our multi-gateway selector guide.

Observability for payment flows

Payments are the highest-stakes pages in your app. Treat them accordingly:

• Structured logs on every initiate / lookup call — log pidx, order id, amount, status, latency. Search by pidx becomes the standard debug move
• Synthetic monitoring — run a sandbox-payment every 5 minutes from an external prober (Better Stack, UptimeRobot). Catches gateway-side outages before customers report them
• Alerts on success-rate drop — calculate rolling 5-minute payment-success rate; page on-call when it drops below 95%
• Capture verification mismatches separately — they should be zero in steady state; any nonzero is investigation-grade
• Customer-facing status page — when Khalti is degraded, surface a banner rather than letting customers think your site is broken
• Daily reconciliation report — compare yesterday's gateway settlements to your orders; investigate every discrepancy

Multi-region resilience

If your Next.js app runs on Vercel or similar edge platforms, ensure the payment-initiation and lookup routes pin to a single region close to Khalti's infrastructure (Mumbai works well for Nepal). Edge functions can introduce subtle race conditions when the same pidx is touched from different regions simultaneously. Database-level uniqueness on pidx (as in the SQL pattern above) is your last line of defence; do not rely solely on application-level locking.