Quickstart

Create a hosted checkout, redirect the customer, and confirm the payment on your server.

Keep your order amount in your database. The browser should send an order ID, not the amount to charge.

1. Get your API keys

Sandbox keys start with sk_test_ - use these for testing
Live keys start with sk_live_ - use these for real payments

Never expose your API key in client-side code or commit it to version control. Use environment variables.

2. Install the SDK

npm install @paybridge-np/sdk

yarn add @paybridge-np/sdk

bun add @paybridge-np/sdk

3. Create a checkout session

Call this from your server when a customer is ready to pay.

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

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

export async function startCheckout(orderId: string) {
  const order = await loadOrderFromDatabase(orderId);
  if (!order) throw new Error("Order not found");

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

  return Response.redirect(session.checkout_url, 303);
}

const res = await fetch("https://api.paybridgenp.com/v1/checkout", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PAYBRIDGENP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 10000, // load this from your order on the server
    returnUrl: "https://yoursite.com/success",
    cancelUrl: "https://yoursite.com/cart",
    metadata: { orderId: "ORD-001" },
  }),
});

const session = await res.json();
// Redirect customer to session.checkout_url

The response looks like:

{
  "id": "cs_01j9x2k3m4n5p6q7r8s9t0u1v2",
  "checkout_url": "https://checkout.paybridgenp.com/checkout/cs_01j9x2k3m...",
  "flow": "hosted",
  "provider": null,
  "expires_at": "2026-03-31T12:30:00.000Z"
}

Redirect your customer to checkout_url. They’ll see the PayBridgeNP hosted checkout page and can pay with any provider you’ve configured.

cancelUrl is optional. If you omit it, cancellations fall back to your returnUrl with ?status=cancelled appended - and the hosted picker hides its “Cancel” link. Set cancelUrl only if you want a dedicated cancel page and a visible Cancel link on the picker.

4. Handle the return redirect

After the customer pays (or cancels), they’re redirected to your returnUrl (or cancelUrl if set and the customer cancelled) with query parameters:

https://yoursite.com/success?session_id=cs_xxx&status=success&payment_id=pay_xxx

Parameter	Value
`session_id`	The checkout session ID
`status`	`success`, `failed`, `cancelled`, or `expired`
`payment_id`	The payment ID (only on success)

expired means the customer never finished and the session timed out. Treat it the same as failed for fulfilment purposes: no money moved. Branch on success and treat everything else as not-paid, rather than listing the failure values, so a future status can never be read as a payment.

Do not fulfill orders based solely on the redirect. The customer could manipulate query parameters. Always verify payment server-side using webhooks or GET /v1/payments/:id.

5. Verify payment server-side

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

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

  let event;
  try {
    event = await PayBridgeNP.webhooks.constructEvent<PaymentSucceeded>(
      body,
      signature,
      process.env.PAYBRIDGENP_WEBHOOK_SECRET!,
    );
  } catch {
    return new Response("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 new Response("Payment does not match order", { status: 409 });
    }

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

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

const order = await loadOrderFromDatabase("ORD-001");
const payment = await paybridgenp.payments.retrieve("pay_xxx");

if (
  payment.status === "success" &&
  payment.amount === order.amountPaisa &&
  payment.currency === order.currency
) {
  await fulfillOrderOnce(order.id, payment.id);
}

Replace the example data-access helpers with your own database calls. Make fulfillment idempotent by storing the PayBridgeNP payment ID and ignoring a repeat you already processed. Only have the session_id from the redirect? Fetch the session - once it’s paid, the response includes paymentId:

curl https://api.paybridgenp.com/v1/sessions/cs_xxx \
  -H "Authorization: Bearer sk_live_your_key"
# → { "id": "cs_xxx", "status": "success", "paymentId": "pay_xxx", ... }

See Get a checkout session.

6. Set up a webhook endpoint

Go to Webhooks in the dashboard, click Add endpoint, enter your URL, and select the events you want to receive. Save the signing secret - it’s shown only once. See the webhook verification guide for full details on signature verification.

Next steps

Sandbox Testing

Test the full flow with built-in test credentials before going live.

Provider Setup

Add your real eSewa, Khalti, and Fonepay credentials.

Idempotency

Make retries safe - avoid duplicate payments on network failures.

Billing

Set up recurring subscriptions and automated invoicing.

Getting Started

Accepting Payments

Checkout

Providers

Subscriptions & Billing

Branding

Operations

Integrations

1. Get your API keys

2. Install the SDK

3. Create a checkout session

4. Handle the return redirect

5. Verify payment server-side

6. Set up a webhook endpoint

Next steps

Sandbox Testing

Provider Setup

Idempotency

Billing

​1. Get your API keys

​2. Install the SDK

​3. Create a checkout session

​4. Handle the return redirect

​5. Verify payment server-side

​6. Set up a webhook endpoint

​Next steps

Sandbox Testing

Provider Setup

Idempotency

Billing

1. Get your API keys

2. Install the SDK

3. Create a checkout session

4. Handle the return redirect

5. Verify payment server-side

6. Set up a webhook endpoint

Next steps