Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paybridgenp.com/llms.txt

Use this file to discover all available pages before exploring further.

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

Sign up at dashboard.paybridgenp.com and copy your API key from Settings → 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

​
3. Create a checkout session

Call this from your server when a customer is ready to pay. 
import { PayBridge } from "@paybridge-np/sdk";

const paybridge = new PayBridge({
  apiKey: process.env.PAYBRIDGE_API_KEY!, // sk_test_... or sk_live_...
});

const session = await paybridge.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);
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
ParameterValue
session_idThe checkout session ID
statussuccess, failed, or cancelled
payment_idThe 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/paybridge", async (req) => {
  const body = await req.text(); // raw body string
  const sig = req.headers.get("x-paybridge-signature");

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

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

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