@paybridgejs/khalti

Type-safe Khalti payment gateway integration for Node.js and browsers. Simplify Khalti payments with automatic error handling, payment verification, and built-in retry logic.

Features

✅ Type-safe API - Full TypeScript support with auto-generated types
✅ Payment Initiation - Create payment sessions with a single method call
✅ Payment Verification - Verify transaction status securely
✅ Error Handling - Comprehensive error handling with custom error classes
✅ Easy Integration - Simple API designed for rapid integration

Installation

npm install paybridgejs/khalti
# or
pnpm add paybridgejs/khalti
# or
yarn add paybridgejs/khalti

Quick Start

1. Initialize the Client

import { khalti } from "paybridgejs/khalti";

const client = new khalti({
  secretKey: process.env.KHALTI_SECRET_KEY!,
});

2. Initiate a Payment

const payment = await client.initiate({
  amount: 10000, // NPR 100 (in paisa, 1 NPR = 100 paisa)
  purchase_order_id: "ORDER-123",
  purchase_order_name: "iPhone 15",
  return_url: "https://yoursite.com/success",
  website_url: "https://yoursite.com",
});

console.log(payment.payment_url); // Redirect user to this URL
console.log(payment.pidx); // Store for later verification

3. Verify Payment

const result = await client.verify({
  pidx: "storedPidxFromInitiation",
});

if (result.status === "Completed") {
  console.log("✅ Payment successful!");
  console.log("Transaction ID:", result.transaction_id);
  console.log("Amount:", result.total_amount);
}

API Reference

KhaltiClient

Constructor

new khalti({
  secretKey: string; // Khalti API secret key (required)
})

Methods

initiate(payload)

Initiates a new payment transaction.

Parameters:

• amount (number) - Amount in paisa (1 NPR = 100 paisa)
• purchase_order_id (string) - Unique order identifier
• purchase_order_name (string) - Display name for the order
• return_url (string) - URL to redirect after payment completion
• website_url (string) - Your website URL

Returns:

{
  pidx: string; // Payment index for tracking
  payment_url: string; // URL to redirect user for payment
  expires_at: string; // Expiration timestamp
  expires_in: number; // Expiration time in seconds
}

verify(payload)

Verifies the status of a payment transaction.

Parameters:

• pidx (string) - Payment index from initiation

Returns:

{
  pidx: string;
  total_amount: number;
  status: "Completed" |
    "Pending" |
    "Initiated" |
    "Refunded" |
    "Expired" |
    "User canceled" |
    "Partially Refunded";
  transaction_id: string | null;
  fee: number;
  refunded: boolean;
}

Common Patterns

Store Payment References

Always store the pidx for later verification:

// When initiating payment
const payment = await client.initiate({...});
await db.payments.create({
  pidx: payment.pidx,
  orderId: "ORDER-123",
  amount: 10000,
  status: "pending",
  expiresAt: payment.expires_at,
});

// Later, when verifying
const result = await client.verify({ pidx });
await db.payments.update(pidx, {
  status: result.status,
  transactionId: result.transaction_id
});

Handle Different Payment States

const result = await client.verify({ pidx });

switch (result.status) {
  case "Completed":
    console.log("Payment successful");
    break;
  case "Pending":
  case "Initiated":
    console.log("Payment awaiting completion");
    break;
  case "Expired":
    console.log("Payment link expired");
    break;
  case "User canceled":
    console.log("User cancelled the payment");
    break;
  case "Refunded":
  case "Partially Refunded":
    console.log("Payment refunded");
    break;
}

Khalti Payment Gateway Features

Khalti is Nepal's leading payment gateway with support for:

• 🏦 Bank Transfers - Direct bank payments
• 📱 Mobile Banking - Internet banking via mobile
• 💰 Mobile Wallet - KhaltiPay digital wallet
• 🎫 QR Codes - QR-based payments
• ⚡ Instant Settlement - Fast fund transfers
• 💳 Low Fees - Competitive transaction fees

Documentation

For more detailed documentation, visit:

• Full Khalti Documentation
• Khalti Official Website

Error Handling

The package includes custom error classes for different scenarios:

import { khalti } from "paybridgejs/khalti";

try {
  const payment = await client.initiate({...});
} catch (error) {
  console.error("Payment initiation failed:", error.message);
}

License

MIT © 2024 PayBridge Contributors

Support

For issues, questions, or contributions, please visit:

• PayBridge GitHub Repository
• Documentation