Quickstart

This guide walks through the full payment flow - from creating a checkout session on your server to receiving a webhook when payment succeeds.

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

const session = await paybridgenp.checkout.create({
  amount: 10000,                              // NPR 100.00 - always in paisa (NPR × 100)
  returnUrl: "https://yoursite.com/success",
  cancelUrl: "https://yoursite.com/cart",    // optional
  metadata: { orderId: "ORD-001" },          // optional, returned in webhook
});

// Redirect the customer
redirect(session.checkout_url);

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,
    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`, or `cancelled`
`payment_id`	The payment ID (only on success)

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

// In your webhook handler
app.post("/webhooks/paybridgenp", async (req) => {
  const body = await req.text(); // raw body string
  const sig = req.headers.get("x-paybridgenp-signature");

  const event = await PayBridgeNP.webhooks.constructEvent(
    body,
    sig,
    process.env.PAYBRIDGENP_WEBHOOK_SECRET!,
  );

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

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

if (payment.status === "success") {
  await fulfillOrder(payment.metadata?.orderId);
}

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