Plan a Khalti checkout: initiation, return and lookup

A checkout integration should preserve your own order state even when a customer closes a tab, a network request times out or the provider result arrives later. This guide reviews KPG-2 documentation and proposes an implementation plan, not a tested production Node.js example.

Keep initiation and lookup server-side

Khalti’s reviewed KPG-2 documentation describes server-side initiation, a pidx identifier, a browser return and a lookup operation. It uses paisa for the documented amount field and identifies a successful completed result as Completed.

Use the credentials and environment supplied for your merchant account. Avoid mixing a legacy SDK’s fields with the current web-checkout contract. Keep keys out of browser code and never copy a documentation sample key into a production deployment.

Reference: Khalti — KPG-2 web checkout ↗

Persist the payment attempt before redirecting

Store your order, exact expected amount, merchant context and provider reference together with the attempt’s state. If initiation fails, retain enough information to explain the failure without recording a successful payment.

A second checkout attempt should not silently replace the evidence from the first. Link both attempts to the order and define what happens if results arrive out of order.

Treat returns and lookups as separate evidence

Validate incoming return data and use the documented authoritative verification flow. Match the result to your stored attempt before changing the order. A status in a query string is not an adequate basis for dispatch.

Keep all provider states explicit in your adapter. A refund, pending result or expiry should not fall through a generic truthy check into the same branch as successful fulfilment.

Make the operating handover part of the work

Write down where staff find the provider reference and how to investigate an unmatched order. Log references and decisions without exposing keys or unnecessary customer data.

Run your test matrix in the approved sandbox and complete the merchant’s production approval process. The flow described here was checked against public documentation; no live or sandbox transaction is claimed.

Design a reviewable reconciliation workflow →