eSewa, Khalti & ConnectIPS — @itzsa/nepal-pay

// One form → eSewa | Khalti | connectIPS
// Fields: name, amount, orderId, description, success/failure URLs,
//         tax, service, delivery → total
//
// eSewa      → POST /api/nepal-pay/esewa/initiate
//              → HTML form POST → /nepal-pay/return?data=…
// Khalti     → POST /api/nepal-pay/khalti/initiate
//              → payment_url → /nepal-pay/khalti-return?pidx=…
// connectIPS → POST /api/nepal-pay/connectips/initiate
//              → HTML form POST → /nepal-pay/connectips-return?TXNID=…
//
// eSewa UAT: 9711111111 / Nepal@123 / 123456 · secret 8gBm/:&EnhH.1/q
// Khalti:    9800000000–05 / MPIN 1111 / OTP 987654 · merchant test secret
// connectIPS: NCHL merchant + CREDITOR.pfx (docs mock drafts signed payload)

{
  "ok": true,
  "gateway": "esewa",
  "mode": "sandbox",
  "initiate": {
    "redirectUrl": "https://rc-epay.esewa.com.np/api/epay/main/v2/form",
    "providerRef": "241028",
    "method": "POST",
    "formFields": {
      "amount": "110",
      "tax_amount": "0",
      "product_service_charge": "0",
      "product_delivery_charge": "0",
      "total_amount": "110",
      "transaction_uuid": "241028",
      "product_code": "EPAYTEST",
      "success_url": "https://example.com/pay/esewa/return",
      "failure_url": "https://example.com/pay/failed",
      "signed_field_names": "total_amount,transaction_uuid,product_code",
      "signature": "i94zsd3oXF6ZsSr/kGqT4sSzYQzjj1W/waxjWyRwaME="
    }
  }
}

{
  "transaction_code": "000AWEO",
  "status": "COMPLETE",
  "total_amount": 1000.0,
  "transaction_uuid": "250610-162413",
  "product_code": "EPAYTEST",
  "signed_field_names": "transaction_code,status,total_amount,transaction_uuid,product_code,signed_field_names",
  "signature": "<hmac-base64>"
}

{
  "product_code": "EPAYTEST",
  "transaction_uuid": "240508-10108",
  "total_amount": 100.0,
  "status": "COMPLETE",
  "ref_id": "0007G36"
}

{
  "product_code": "EPAYTEST",
  "transaction_uuid": "240508-102939",
  "total_amount": 10.0,
  "status": "CANCELED",
  "ref_id": "0KDL6NA"
}

{
  "ok": false,
  "error": {
    "code": "SIGNATURE_MISMATCH",
    "name": "SignatureMismatchError",
    "message": "eSewa callback signature mismatch — possible tampering"
  }
}

{
  "return_url": "https://example.com/pay/khalti/return",
  "website_url": "https://example.com",
  "amount": 1050,
  "purchase_order_id": "order-42",
  "purchase_order_name": "Pro plan",
  "customer_info": {
    "name": "Test User",
    "email": "test@example.com",
    "phone": "9800000000"
  }
}

{
  "pidx": "bZQLD9wbdAi789cZ5GvUdF",
  "payment_url": "https://test-pay.khalti.com/?pidx=bZQLD9wbdAi789cZ5GvUdF",
  "expires_at": "2026-07-23T12:30:00.000000+05:45",
  "expires_in": 1800
}

{
  "pidx": "bZQLD9wbdAi789cZ5GvUdF",
  "txnId": "4d5kjnABpA2n7LLxLh9cDP",
  "amount": 1050,
  "total_amount": 1050,
  "status": "Completed",
  "mobile": "98XXXXX000",
  "purchase_order_id": "order-42",
  "purchase_order_name": "Pro plan",
  "transaction_id": "4d5kjnABpA2n7LLxLh9cDP"
}

{
  "pidx": "bZQLD9wbdAi789cZ5GvUdF",
  "total_amount": 1050,
  "status": "Completed",
  "transaction_id": "4d5kjnABpA2n7LLxLh9cDP",
  "fee": 0,
  "refunded": false
}

{
  "ok": false,
  "error": {
    "code": "GATEWAY_API",
    "name": "GatewayApiError",
    "message": "Lookup failed with HTTP 401",
    "gateway": "khalti",
    "statusCode": 401,
    "body": { "detail": "Invalid token." }
  }
}

{
  "ok": false,
  "error": {
    "code": "GATEWAY_API",
    "name": "GatewayApiError",
    "message": "Initiate failed with HTTP 400",
    "gateway": "khalti",
    "statusCode": 400,
    "body": {
      "amount": ["Amount should be greater than 1000 (Rs. 10)."],
      "return_url": ["This field is required."]
    }
  }
}

{
  "ok": true,
  "gateway": "connectips",
  "mode": "sandbox",
  "amountNpr": 10.5,
  "amountPaisa": 1050,
  "loginTokenMessage": "MERCHANTID=902,APPID=MER-902-APP-1,APPNAME=Demo,TXNID=ord42txn001,TXNDATE=22-07-2026,TXNCRNCY=NPR,TXNAMT=1050,REFERENCEID=ord42txn001,REMARKS=Pro plan,PARTICULARS=Pro plan,TOKEN=TOKEN",
  "initiate": {
    "redirectUrl": "https://uat.connectips.com/connectipswebgw/loginpage",
    "providerRef": "ord42txn001",
    "method": "POST",
    "formFields": {
      "MERCHANTID": "902",
      "APPID": "MER-902-APP-1",
      "APPNAME": "Demo",
      "TXNID": "ord42txn001",
      "TXNDATE": "22-07-2026",
      "TXNCRNCY": "NPR",
      "TXNAMT": "1050",
      "REFERENCEID": "ord42txn001",
      "REMARKS": "Pro plan",
      "PARTICULARS": "Pro plan",
      "TOKEN": "<SHA256withRSA Base64>"
    }
  }
}

{
  "TXNID": "ord42txn001"
}

{
  "merchantId": 902,
  "appId": "MER-902-APP-1",
  "referenceId": "ord42txn001",
  "txnAmt": 1050,
  "token": "<SHA256withRSA over MERCHANTID=…,APPID=…,REFERENCEID=…,TXNAMT=…>"
}

{
  "merchantId": 902,
  "appId": "MER-902-APP-1",
  "referenceId": "ord42txn001",
  "txnAmt": "1050",
  "token": null,
  "status": "SUCCESS",
  "statusDesc": "Transaction successful."
}

{
  "kind": "callback_received",
  "providerRef": "bZQLD9wbdAi789cZ5GvUdF",
  "raw": { "pidx": "bZQLD9wbdAi789cZ5GvUdF", "status": "Completed" }
}

{
  "status": "confirmed",
  "providerRef": "bZQLD9wbdAi789cZ5GvUdF",
  "amount": 10.5,
  "transactionId": "4d5kjnABpA2n7LLxLh9cDP",
  "raw": { "status": "Completed", "total_amount": 1050 }
}

{
  "status": "failed",
  "providerRef": "bZQLD9wbdAi789cZ5GvUdF",
  "amount": 10.5,
  "raw": { "status": "User canceled", "total_amount": 1050 }
}

const esewa = pay.gateway("esewa");
const { initiate } = await service.start({ /* … */ });

// eSewa is HTML form POST — auto-submit on the server or client:
const html = `<!doctype html><html><body>
<form id="esewa" action="${initiate.redirectUrl}" method="POST">
${Object.entries(initiate.formFields!)
  .map(([k, v]) => `<input type="hidden" name="${k}" value="${v}" />`)
  .join("")}
</form>
<script>document.getElementById("esewa").submit()</script>
</body></html>`;

const { initiate } = await service.start({
  amount: 10.5,          // → 1050 paisa inside KhaltiGateway
  orderId: "order-42",
  orderName: "Pro plan",
  returnUrl: "https://example.com/pay/khalti/return",
  websiteUrl: "https://example.com",
});

// 302 / client navigate to initiate.redirectUrl (GET)
res.redirect(initiate.redirectUrl);

const connectips = pay.gateway("connectips");
const service = createPaymentService(connectips, store, {
  successUrl: "https://example.com/pay/success",
  failureUrl: "https://example.com/pay/failed",
});

const { initiate } = await service.start({
  amount: 10.5, // → 1050 paisa in TXNAMT
  orderId: "order-42",
  orderName: "Pro plan",
  returnUrl: "https://example.com/pay/connectips/return", // NCHL registers static URLs
  websiteUrl: "https://example.com",
});

// Same HTML form POST pattern as eSewa (loginpage)
const html = `<!doctype html><html><body>
<form id="cips" action="${initiate.redirectUrl}" method="POST">
${Object.entries(initiate.formFields!)
  .map(([k, v]) => `<input type="hidden" name="${k}" value="${v}" />`)
  .join("")}
</form>
<script>document.getElementById("cips").submit()</script>
</body></html>`;

// Return URL gets ?TXNID=… only — always call verify() / handleReturn
// Point NCHL failure URL at …/return?outcome=failure

import { createReturnUrlHandler } from "@itzsa/nepal-pay";

const handleReturn = createReturnUrlHandler(gateway, store, {
  successUrl: "https://example.com/pay/success",
  failureUrl: "https://example.com/pay/failed",
  onConfirmed: async (id) => fulfillOrder(id),
});

// 1) handleCallback (untrusted)
// 2) cancel → failed
// 3) callback_received → verifying → verify()
// 4) confirmed (idempotent) → successUrl
// 5) else → failureUrl

import express from "express";
import { createNepalPay, createPaymentService, MemoryPaymentStore } from "@itzsa/nepal-pay";

const app = express();
const pay = createNepalPay({ /* config */ });
const store = new MemoryPaymentStore();
const service = createPaymentService(pay.gateway("khalti"), store, {
  successUrl: "https://example.com/ok",
  failureUrl: "https://example.com/fail",
  onConfirmed: fulfillOrder,
});

app.get("/pay/khalti/return", async (req, res) => {
  const query = Object.fromEntries(
    Object.entries(req.query).map(([k, v]) => [k, String(v)]),
  );
  const { redirectTo } = await service.handleReturn(query);
  res.redirect(redirectTo);
});

// app/api/pay/khalti/return/route.ts
import { createNepalPay, createPaymentService, MemoryPaymentStore } from "@itzsa/nepal-pay";

const pay = createNepalPay({ /* config from env */ });
const store = new MemoryPaymentStore(); // use a shared store in real apps
const service = createPaymentService(pay.gateway("khalti"), store, {
  successUrl: "https://example.com/ok",
  failureUrl: "https://example.com/fail",
  onConfirmed: fulfillOrder,
});

export async function GET(request: Request) {
  const url = new URL(request.url);
  const query = Object.fromEntries(url.searchParams.entries());
  const { redirectTo } = await service.handleReturn(query);
  return Response.redirect(redirectTo);
}

MERCHANTID=902,APPID=MER-902-APP-1,APPNAME=Demo,TXNID=ord42txn001,TXNDATE=22-07-2026,TXNCRNCY=NPR,TXNAMT=1050,REFERENCEID=ord42txn001,REMARKS=Pro plan,PARTICULARS=Pro plan,TOKEN=TOKEN
// → SHA256withRSA(privateKey) → Base64 → form field TOKEN

import { registerGateway, type PaymentGateway } from "@itzsa/nepal-pay";

registerGateway("fonepay", (ctx) => {
  // Implement PaymentGateway against Fonepay docs
  const gateway: PaymentGateway = {
    name: "fonepay",
    async initiate(req) { /* … */ },
    async handleCallback(query) { /* never return confirmed */ },
    async verify(ref) { /* only path to confirmed */ },
    async refund() { /* … */ },
  };
  return gateway;
});

const fonepay = pay.gateway("fonepay");

import { PrismaPaymentStore } from "@itzsa/nepal-pay";
import { prisma } from "./db"; // your PrismaClient

const store = new PrismaPaymentStore(prisma);

// schema:
// model Payment {
//   id          String   @id @default(cuid())
//   gateway     String
//   providerRef String
//   orderId     String
//   amount      Float
//   status      String
//   metadata    Json?
//   createdAt   DateTime @default(now())
//   updatedAt   DateTime @updatedAt
//   @@unique([gateway, providerRef])
// }