TypeScript / JavaScript SDK

Installation

npm install @paybridge-np/sdk

yarn add @paybridge-np/sdk

bun add @paybridge-np/sdk

Initialization

import { PayBridgeNP } from "@paybridge-np/sdk";

const paybridgenp = new PayBridgeNP({
  apiKey: process.env.PAYBRIDGENP_API_KEY!,  // sk_test_... or sk_live_...
  baseUrl: "https://api.paybridgenp.com",  // optional, this is the default
  timeout: 30_000,                         // optional, ms. default: 30000
  maxRetries: 2,                           // optional. default: 2
});

Idempotency keys for write calls

Every resource create, update, delete, and action method that writes accepts an optional final idempotencyKey string. Reuse the same value when retrying the same business operation; the SDK sends it as Idempotency-Key.

await paybridgenp.refunds.create(
  { paymentId: "pay_123", amount: 10000, reason: "customer_request" },
  "refund-order-123",
);

`paybridgenp.checkout`

`checkout.create(params)`

Creates a checkout session.

const session = await paybridgenp.checkout.create({
  amount: 10000,                              // required - paisa (NPR × 100)
  returnUrl: "https://yoursite.com/success", // required
  cancelUrl: "https://yoursite.com/cart",    // optional
  provider: "khalti",                        // optional - omit to let customer pick
  currency: "NPR",                           // optional, default: "NPR"
  metadata: { orderId: "ORD-001" },          // optional
});

console.log(session.checkout_url);  // redirect customer here
console.log(session.id);            // cs_...
console.log(session.expires_at);    // ISO timestamp

Parameters:

Name	Type	Required	Description
`amount`	`number`	Yes	In paisa. NPR 100.00 = `10000`
`returnUrl`	`string`	Yes	Redirect URL after payment
`cancelUrl`	`string`	No	Redirect URL on cancellation
`provider`	`"esewa" \| "khalti" \| "fonepay"`	No	Pre-select provider
`currency`	`string`	No	Default: `"NPR"`
`metadata`	`object`	No	Passed through to webhooks and payment records

`checkout.expire(id)`

Marks a session as expired so it can no longer accept payment. Use this when you mint a fresh session for a logical purchase that already had one outstanding (e.g. a customer requesting a new payment link), so the old URL stops being payable immediately rather than waiting for its 30-minute TTL.

await paybridgenp.checkout.expire("cs_6f2jHn2…");

Idempotent: calling on an already-terminal session is a no-op that returns the current row state without error. If an active eSewa Intent booking cannot be confirmed cancelled, this returns a 409 error with code: "provider_cancel_unconfirmed"; retry before creating another payable session.

`checkout.retrieve(id)`

Fetches a checkout session by ID: its current status, amount, customer, and any collected address. Read-only (sessions are created with checkout.create).

const session = await paybridgenp.checkout.retrieve("cs_6f2jHn2…");
console.log(session.status);        // "pending" | "initiated" | "success" | ...
console.log(session.amount);        // paisa
console.log(session.customerName);  // camelCase on the read shape

Note: the read shape uses camelCase keys (customerName, expiresAt, …), unlike the snake_case checkout.create response.

`checkout.list(params?)`

Lists checkout sessions for the project, newest first.

const { data, meta } = await paybridgenp.checkout.list({
  limit: 20,          // optional, 1 to 100 (default 25)
  offset: 0,          // optional
  status: "success",  // optional filter
});
console.log(meta.total, data.length);

`paybridgenp.paymentLinks`

Reusable hosted payment pages. Methods need an API key with the links:read or links:write scope.

`paymentLinks.create(params)`

const link = await paybridgenp.paymentLinks.create({
  title: "Donation",  // required
  amount: 50000,      // paisa. Omit for a customer-entered amount (use minAmount/maxAmount)
  maxUses: 100,       // optional
});
console.log(link.url); // public hosted payment page

`paymentLinks.list(params?)`

const { data, meta } = await paybridgenp.paymentLinks.list({
  active: true, // optional filter
  limit: 20,    // optional
});

`paymentLinks.retrieve(id)`

Returns the link plus aggregated view and conversion stats.

const link = await paybridgenp.paymentLinks.retrieve("lnk_…");
console.log(link.stats); // { views, used_count, conversion_rate }

`paymentLinks.update(id, params)`

Updates editable fields. Only the keys you pass are changed.

await paybridgenp.paymentLinks.update("lnk_…", { active: false });

`paymentLinks.cancel(id)`

Deactivates a link so it can no longer accept payments, while keeping it and its history for your records. The recommended way to retire a link that has already been used.

await paybridgenp.paymentLinks.cancel("lnk_…");

`paymentLinks.delete(id)`

Permanently deletes a link. Allowed only when the link has never been used. Otherwise it returns 422; cancel it instead.

await paybridgenp.paymentLinks.delete("lnk_…");

`paybridgenp.payments`

`payments.list(params?)`

const { data, meta } = await paybridgenp.payments.list({
  limit: 20,   // optional, default 10, max 100
  offset: 0,   // optional, default 0
});

console.log(meta.total);  // total count
data.forEach((payment) => {
  console.log(payment.id, payment.amount, payment.status);
});

`payments.retrieve(id)`

const payment = await paybridgenp.payments.retrieve("pay_6f2jHn2...");

console.log(payment.status);      // "success" | "failed"
console.log(payment.amount);      // paisa
console.log(payment.provider);    // "esewa" | "khalti" | "fonepay"
console.log(payment.providerRef); // provider's transaction reference
console.log(payment.metadata);    // whatever you passed at checkout

`paybridgenp.webhooks`

`webhooks.create(params)`

const endpoint = await paybridgenp.webhooks.create({
  url: "https://yoursite.com/webhooks/paybridgenp",
  events: ["payment.succeeded", "payment.failed"], // optional - omit for all events
});

console.log(endpoint.signing_secret); // save this! shown only once

`webhooks.list()`

const { data } = await paybridgenp.webhooks.list();
data.forEach((wh) => console.log(wh.id, wh.url, wh.enabled));

`webhooks.delete(id)`

await paybridgenp.webhooks.delete("wh_...");

`PayBridgeNP.webhooks.constructEvent(body, signature, secret)` (static)

Verifies a webhook signature and parses the event. Use this in your webhook handler.

import { PayBridgeNP } from "@paybridge-np/sdk";

// This is a static method - no instance needed
const event = await PayBridgeNP.webhooks.constructEvent(
  rawBodyString,           // raw request body - do NOT parse as JSON first
  signatureHeader,         // value of X-PayBridgeNP-Signature header
  process.env.PAYBRIDGENP_WEBHOOK_SECRET!,
);

switch (event.type) {
  case "payment.succeeded":
    // event.data: { id, amount, currency, provider, provider_ref, session_id, metadata }
    await fulfillOrder(event.data.metadata?.orderId);
    break;

  case "payment.failed":
    await notifyOrderFailed(event.data.session_id);
    break;
}

Throws SignatureVerificationError if:

The signature header is missing or malformed
The HMAC doesn’t match
The timestamp is more than 5 minutes old (replay attack protection)

`paybridgenp.billing`

The billing namespace provides access to plans, customers, subscriptions, and invoices. Live-mode Billing API access requires Growth or higher; sandbox Billing is available on every plan.

`billing.plans`

// Create a plan
const plan = await paybridgenp.plans.create({
  name: "Pro Monthly",
  amount: 99900,         // paisa - NPR 999/month
  intervalUnit: "month",
  intervalCount: 1,
  trialDays: 14,         // optional
});

// List plans
const { data } = await paybridgenp.plans.list();

// Get a plan
const plan = await paybridgenp.plans.get("plan_...");

// Update a plan
const updated = await paybridgenp.plans.update("plan_...", { name: "Pro Monthly v2" });

`billing.customers`

// Create a customer
const customer = await paybridgenp.customers.create({
  name: "Aarav Sharma",
  email: "aarav@example.com",
  externalCustomerId: "user_123",   // optional - your internal user ID
});

// List customers
const { data } = await paybridgenp.customers.list();

// Get a customer
const customer = await paybridgenp.customers.get("cus_...");

// Update a customer
const updated = await paybridgenp.customers.update("cus_...", { email: "new@example.com" });

// Delete a customer
await paybridgenp.customers.delete("cus_...");

`billing.subscriptions`

// Create a subscription
const subscription = await paybridgenp.subscriptions.create({
  customerId: "cus_...",
  planId: "plan_...",
});

// List subscriptions
const { data } = await paybridgenp.subscriptions.list();

// Get a subscription
const sub = await paybridgenp.subscriptions.get("sub_...");

// Lifecycle actions
await paybridgenp.subscriptions.pause("sub_...");
await paybridgenp.subscriptions.resume("sub_...");
await paybridgenp.subscriptions.cancel("sub_...");

// Change plan
await paybridgenp.subscriptions.changePlan("sub_...", { newPlanId: "plan_..." });

`billing.invoices`

// List invoices (optionally filter by subscription or customer)
const { data } = await paybridgenp.invoices.list({
  subscriptionId: "sub_...",   // optional
});

// Get an invoice
const invoice = await paybridgenp.invoices.get("inv_...");

console.log(invoice.status);     // "open" | "paid" | "overdue" | "void" | "uncollectible" | "write_off"
console.log(invoice.amount_due); // paisa
console.log(invoice.due_at);     // ISO timestamp
console.log(invoice.hosted_invoice_url); // hosted payment link sent to customer

Account, analytics, providers, and SMS

const account = await paybridgenp.account.get();
const overview = await paybridgenp.analytics.overview(30); // `days` is optional (1–90)
const { providers } = await paybridgenp.providers.list();

await paybridgenp.sms.notifyPendingPayment({
  customerPhone: "9801234567",
  shopName: "Acme Store",
  orderName: "#1042",
  amountMinor: 10000,
  currency: "NPR",
  checkoutUrl: "https://checkout.paybridgenp.com/checkout/cs_...",
}, "pending-payment-1042");

account.get() requires account:read; analytics.overview() requires analytics:read. providers.list() returns only enabled, configured providers for the key’s project. sms.notifyPendingPayment() requires payments:write; its optional idempotency key is sent for SDK consistency, but the server does not currently deduplicate this route.

Error handling

All SDK methods throw typed errors you can catch and inspect:

import { PayBridgeNP, PayBridgeError, AuthenticationError } from "@paybridge-np/sdk";

try {
  await paybridgenp.checkout.create({ amount: 1000, returnUrl: "..." });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid API key
    console.error("Check your PAYBRIDGENP_API_KEY");
  } else if (err instanceof PayBridgeError) {
    console.error(err.message);     // human-readable message
    console.error(err.statusCode);  // HTTP status
    console.error(err.code);        // machine-readable code
  }
}

Error classes

Class	Status	When
`AuthenticationError`	401	Invalid or missing API key
`InvalidRequestError`	400, 404, 409, 422	Malformed request, resource not found, or a business rule blocked it
`RateLimitError`	429	Too many requests
`ApiError`	5xx	Server error - safe to retry
`SignatureVerificationError`	-	Webhook HMAC mismatch or replay

The base class is PayBridgeError; every error above extends it. See the Errors reference for the full list.

TypeScript types

All types are exported from @paybridge-np/sdk:

import type {
  CheckoutSession,
  Payment,
  PaymentStatus,
  Provider,
  WebhookEvent,
  WebhookEventType,
  WebhookEndpoint,
  CreateCheckoutParams,
  PaginatedResponse,
  Plan,
  BillingCustomer,
  Subscription,
  Invoice,
  CreatePlanParams,
  CreateCustomerParams,
  CreateSubscriptionParams,
} from "@paybridge-np/sdk";

Framework examples

Next.js App Router

// app/api/checkout/route.ts
import { NextRequest } from "next/server";
import { PayBridgeNP } from "@paybridge-np/sdk";

const paybridgenp = new PayBridgeNP({
  apiKey: process.env.PAYBRIDGENP_API_KEY!,
});

export async function POST(req: NextRequest) {
  const { orderId } = await req.json();
  const order = await loadOrderFromDatabase(orderId);
  if (!order) return Response.json({ error: "Order not found" }, { status: 404 });

  const session = await paybridgenp.checkout.create({
    amount: order.amountPaisa,
    currency: order.currency,
    returnUrl: `${process.env.NEXT_PUBLIC_URL}/thank-you`,
    cancelUrl: `${process.env.NEXT_PUBLIC_URL}/cart`,
    metadata: { orderId: order.id },
  }, `checkout-${order.id}`);

  return Response.json({ checkoutUrl: session.checkout_url });
}

// app/api/webhooks/paybridgenp/route.ts
import { NextRequest } from "next/server";
import { PayBridgeNP } from "@paybridge-np/sdk";

type PaymentSucceeded = {
  id: string;
  amount: number;
  currency: string;
  metadata?: { orderId?: string };
};

export async function POST(req: NextRequest) {
  const body = await req.text();
  const sig = req.headers.get("x-paybridgenp-signature");

  let event;
  try {
    event = await PayBridgeNP.webhooks.constructEvent<PaymentSucceeded>(
      body, sig, process.env.PAYBRIDGENP_WEBHOOK_SECRET!,
    );
  } catch {
    return Response.json({ error: "Invalid signature" }, { status: 400 });
  }

  if (event.type === "payment.succeeded") {
    const payment = event.data;
    const order = await loadOrderFromDatabase(payment.metadata?.orderId);

    if (!order || payment.amount !== order.amountPaisa || payment.currency !== order.currency) {
      return Response.json({ error: "Payment does not match order" }, { status: 409 });
    }

    await fulfillOrderOnce(order.id, payment.id);
  }

  return Response.json({ received: true });
}

Express

import express from "express";
import { PayBridgeNP } from "@paybridge-np/sdk";

const app = express();
const paybridgenp = new PayBridgeNP({ apiKey: process.env.PAYBRIDGENP_API_KEY! });

type PaymentSucceeded = {
  id: string;
  amount: number;
  currency: string;
  metadata?: { orderId?: string };
};

// Register the webhook before express.json() so the signature sees raw bytes.
app.post(
  "/webhooks/paybridgenp",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    let event;
    try {
      event = await PayBridgeNP.webhooks.constructEvent<PaymentSucceeded>(
        req.body.toString(),
        req.headers["x-paybridgenp-signature"] as string,
        process.env.PAYBRIDGENP_WEBHOOK_SECRET!,
      );
    } catch {
      return res.status(400).json({ error: "Invalid signature" });
    }

    if (event.type === "payment.succeeded") {
      const payment = event.data;
      const order = await loadOrderFromDatabase(payment.metadata?.orderId);

      if (!order || payment.amount !== order.amountPaisa || payment.currency !== order.currency) {
        return res.status(409).json({ error: "Payment does not match order" });
      }

      await fulfillOrderOnce(order.id, payment.id);
    }

    return res.json({ received: true });
  },
);

app.use(express.json());

app.post("/create-checkout", async (req, res) => {
  const order = await loadOrderFromDatabase(req.body.orderId);
  if (!order) return res.status(404).json({ error: "Order not found" });

  const session = await paybridgenp.checkout.create({
    amount: order.amountPaisa,
    currency: order.currency,
    returnUrl: "https://yoursite.com/success",
    metadata: { orderId: order.id },
  }, `checkout-${order.id}`);

  return res.json({ checkoutUrl: session.checkout_url });
});

SDKs

Tools

TypeScript / JavaScript SDK

Installation

Initialization

Idempotency keys for write calls

`paybridgenp.checkout`

`checkout.create(params)`

`checkout.expire(id)`

`checkout.retrieve(id)`

`checkout.list(params?)`

`paybridgenp.paymentLinks`

`paymentLinks.create(params)`

`paymentLinks.list(params?)`

`paymentLinks.retrieve(id)`

`paymentLinks.update(id, params)`

`paymentLinks.cancel(id)`

`paymentLinks.delete(id)`

`paybridgenp.payments`

`payments.list(params?)`

`payments.retrieve(id)`

`paybridgenp.webhooks`

`webhooks.create(params)`

`webhooks.list()`

`webhooks.delete(id)`

`PayBridgeNP.webhooks.constructEvent(body, signature, secret)` (static)

`paybridgenp.billing`

`billing.plans`

`billing.customers`

`billing.subscriptions`

`billing.invoices`

Account, analytics, providers, and SMS

Error handling

Error classes

TypeScript types

Framework examples

​Installation

​Initialization

​Idempotency keys for write calls

​paybridgenp.checkout

​checkout.create(params)

​checkout.expire(id)

​checkout.retrieve(id)

​checkout.list(params?)

​paybridgenp.paymentLinks

​paymentLinks.create(params)

​paymentLinks.list(params?)

​paymentLinks.retrieve(id)

​paymentLinks.update(id, params)

​paymentLinks.cancel(id)

​paymentLinks.delete(id)

​paybridgenp.payments

​payments.list(params?)

​payments.retrieve(id)

​paybridgenp.webhooks

​webhooks.create(params)

​webhooks.list()

​webhooks.delete(id)

​PayBridgeNP.webhooks.constructEvent(body, signature, secret) (static)

​paybridgenp.billing

​billing.plans

​billing.customers

​billing.subscriptions

​billing.invoices

​Account, analytics, providers, and SMS

​Error handling

​Error classes

​TypeScript types

​Framework examples

Installation

Initialization

Idempotency keys for write calls

`paybridgenp.checkout`

`checkout.create(params)`

`checkout.expire(id)`

`checkout.retrieve(id)`

`checkout.list(params?)`

`paybridgenp.paymentLinks`

`paymentLinks.create(params)`

`paymentLinks.list(params?)`

`paymentLinks.retrieve(id)`

`paymentLinks.update(id, params)`

`paymentLinks.cancel(id)`

`paymentLinks.delete(id)`

`paybridgenp.payments`

`payments.list(params?)`

`payments.retrieve(id)`

`paybridgenp.webhooks`

`webhooks.create(params)`

`webhooks.list()`

`webhooks.delete(id)`

`PayBridgeNP.webhooks.constructEvent(body, signature, secret)` (static)

`paybridgenp.billing`

`billing.plans`

`billing.customers`

`billing.subscriptions`

`billing.invoices`

Account, analytics, providers, and SMS

Error handling

Error classes

TypeScript types

Framework examples