n8n-nodes-khalti

An n8n community node for Khalti’s current ePayment Web Checkout (KPG-2) API. Initiate checkout, verify a PIDX, and issue full or partial refunds without manually configuring API URLs.

This is an independent community integration and is not endorsed by or affiliated with IME Khalti Limited. “Khalti” is a trademark of its respective owner.

Installation

In n8n, open Settings → Community Nodes, choose Install, enter n8n-nodes-khalti, accept the community-node warning, and install. For a self-hosted command-line installation:

cd ~/.n8n
npm install n8n-nodes-khalti

Restart n8n after command-line installation.

Credentials

Create a Khalti API credential and select one environment:

• Sandbox uses https://dev.khalti.com/api automatically. Obtain the sandbox live_secret_key from test-admin.khalti.com.
• Production uses https://khalti.com/api automatically. Obtain the production live_secret_key from admin.khalti.com.

Paste only the secret key. Never expose it in workflow fields, browser code, logs, or webhook responses.

Workflow examples

Initiate Payment

Connect your order source to Khalti → Payment → Initiate Payment. Amounts are integers in paisa (1000 = NPR 10). Send the returned payment_url to the customer. The output contains payment_url, pidx, expires_at, expires_in, and the complete API response.

{
  "amount": 100000,
  "purchaseOrderId": "ORDER-2026-0001",
  "purchaseOrderName": "Annual plan",
  "customerName": "Ram Bahadur",
  "customerEmail": "[email protected]",
  "customerPhone": "9800000000",
  "returnUrl": "https://example.com/webhooks/khalti-return",
  "websiteUrl": "https://example.com"
}

Custom metadata becomes documented merchant_* fields. For example, key invoice_id is sent as merchant_invoice_id and returned by Khalti on redirect.

Webhook / return URL

Khalti redirects the customer to return_url using GET query parameters. In n8n, create a Webhook node with GET enabled and a stable production URL, then pass that URL to Initiate Payment. Do not fulfill an order from redirect parameters alone:

1. Read pidx from the Webhook query.
2. Pass it to Lookup Payment.
3. Fulfill only when the lookup result has status: "Completed".
4. Return a customer-facing response or redirect.

Lookup Payment

Use Khalti → Payment → Lookup Payment, mapping PIDX from Initiate Payment or the return webhook. The node returns Khalti’s complete lookup object, including status, transaction_id, total_amount, fee, and refunded.

{
  "pidx": "HT6o6PEZRWFJ5ygavzHWd5",
  "total_amount": 100000,
  "status": "Completed",
  "transaction_id": "GFq9PFS7b2iYvL8Lir9oXe",
  "fee": 0,
  "refunded": false
}

Refund Payment

Use Refund Payment, provide the PIDX, then choose full or partial refund. For partial refunds, provide an integer amount in paisa. Select Bank only for a banking transaction and provide the Khalti mobile number that will receive the refund. The node safely looks up the transaction ID, submits the documented refund request, and returns the refund response together with the pre-refund lookup details.

Refunds move money and may not be reversible. Test workflows in Sandbox and protect production refund workflows with appropriate n8n access controls.

Screenshots

The operation menu exposes only the three supported public actions:

┌─ Khalti ──────────────────────────────┐
│ Resource   Payment                    │
│ Operation  Initiate Payment           │
│ Amount     1000 paisa                 │
│ Order ID   ORDER-2026-0001            │
│ Return URL https://example.com/return │
└───────────────────────────────────────┘

Initiate Payment → payment_url + pidx → GET Webhook → Lookup Payment

API and security notes

• Uses only the documented Khalti KPG-2 initiation and lookup endpoints and the current merchant refund endpoint.
• Authorization is added server-side as Authorization: Key <secret>.
• API base URLs are fixed by the credential environment; workflow users cannot override them.
• Khalti recommends lookup as the final source of truth. Only Completed means payment success.

Official documentation: KPG-2 Web Checkout · Refund API

Development

npm install
npm run build
npm test
npm pack

License

MIT