Embedded Checkout

​

Hosted or Embedded

​

How it works

<script
  src="https://api.paybridgenp.com/js/v1/button.js"
  data-button-id="btn_your_button_id"
></script>

​

If your shopper is already signed in

<script
  src="https://api.paybridgenp.com/js/v1/button.js"
  data-button-id="btn_your_button_id"
  data-customer-name="Ramesh Shrestha"
  data-customer-email="ramesh@example.com"
  data-customer-phone="9812345678"
></script>

​

Use your own button

<button class="your-button" id="pay">Buy now</button>

<script
  src="https://api.paybridgenp.com/js/v1/button.js"
  data-button-id="btn_your_button_id"
  data-render="none"
></script>
<script>
  document.getElementById("pay").addEventListener("click", function () {
    window.PayBridgeNP.open();
  });
</script>

• With several buttons on one page, pass the id: window.PayBridgeNP.open("btn_your_button_id").
• open() returns true when it starts checkout, not when the overlay has finished loading. It returns false when the button is unavailable (unknown id, config still loading, button disabled) or a checkout is already open; the console usually says why. The config can still be loading after window.PayBridgeNP exists, so handle false and retry shortly.
• open() works on rendered buttons too. data-render="none" only stops us adding our element.

​

Cart totals and per-product prices

curl -X POST https://api.paybridgenp.com/v1/checkout \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 249900,
    "currency": "NPR",
    "returnUrl": "https://your-shop.com/order/complete",
    "embedOrigin": "https://your-shop.com",
    "customer": { "name": "Sita Sharma", "email": "sita@example.com", "phone": "9812345678" }
  }'

<button id="buy">Buy now</button>

<script src="https://api.paybridgenp.com/js/v1/button.js"></script>
<script>
  document.getElementById("buy").addEventListener("click", async function () {
    const res = await fetch("/api/start-checkout", { method: "POST" });
    const { checkout_url } = await res.json();
    window.PayBridgeNP.openSession(checkout_url);
  });
</script>

• embedOrigin cannot be combined with flow: "redirect". Pick one.
• The stored origin is re-checked against your current allowlist every time the page renders. Remove a domain and sessions already open stop framing, so it is a marker you can revoke rather than a standing grant.
• Live mode requires Growth or higher; sandbox is available on every plan.

​

Registering allowed embed domains

​

The symptom of an unallowed domain

• The checkout overlay opens as a blank frame and silently refuses to load.
• Your browser developer console displays a Content Security Policy error: Refused to frame 'https://checkout.paybridgenp.com/' because an ancestor violates the following Content Security Policy directive: "frame-ancestors ..."

​

Domain allowlist rules

• Exact origins only, such as https://shop.example.com or http://localhost:3000. No paths, query strings, fragments, trailing slashes or wildcards.
• example.com and www.example.com are different origins. Register both if your shop uses both.
• Live needs https://. http://, private and loopback addresses are refused in live. Sandbox also allows http:// on localhost and 127.0.0.1.
• Up to 25 origins per project, per mode.
• Two switches. The origin must be registered and the button must have Open over my own page ticked.

​

Paying with a wallet

• On a phone, the wallet opens in place and returns to the checkout when it is done.
• On a desktop, the wallet may open in a separate window that closes itself once the payment lands. The overlay shows a waiting state until it does.
• In an in-app browser (a link opened inside Instagram, Facebook, or a similar app), the wallet always opens in place. Separate windows are unreliable there.

​

Closing and reopening is safe

​

PayBridgeNP ID inside the overlay

​

What you still handle

​

Verifying the payment

• Listen for the payment.succeeded webhook, which is signed and retried until you acknowledge it.
• Or read the session back through the API.

​

Limits

• Each button opts in separately. A button you have not ticked keeps redirecting.
• The overlay renders only on allowed origins registered for your project in the active mode.
• Wallet payments briefly leave the overlay, by design.
• Returning customers are recognised only after they enter their mobile number. Hosted Checkout greets them on arrival; the overlay cannot.
• Buttons suit fixed prices. Never use a custom-amount button for a cart total: the browser can change it. For carts, create the session on your server with embedOrigin (Cart totals and per-product prices).
• Shopify uses Hosted Checkout. WooCommerce can also open the overlay; see its overview.