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
});

`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.

`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. Billing API access requires the Growth plan or higher.

`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

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, amount } = await req.json();

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

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

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

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(
      body, sig, process.env.PAYBRIDGENP_WEBHOOK_SECRET!,
    );
  } catch {
    return Response.json({ error: "Invalid signature" }, { status: 400 });
  }

  if (event.type === "payment.succeeded") {
    await db.orders.update({ status: "paid" }, {
      where: { id: event.data.metadata?.orderId },
    });
  }

  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! });

app.use(express.json());

app.post("/create-checkout", async (req, res) => {
  const session = await paybridgenp.checkout.create({
    amount: req.body.amount,
    returnUrl: "https://yoursite.com/success",
    metadata: { orderId: req.body.orderId },
  });
  res.json({ checkoutUrl: session.checkout_url });
});

// Webhook route - must use raw body
app.post(
  "/webhooks/paybridgenp",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const event = await PayBridgeNP.webhooks.constructEvent(
      req.body.toString(),
      req.headers["x-paybridgenp-signature"] as string,
      process.env.PAYBRIDGENP_WEBHOOK_SECRET!,
    );

    if (event.type === "payment.succeeded") {
      // handle success
    }

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

​Installation

​Initialization

​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

​Error handling

​Error classes

​TypeScript types

​Framework examples