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 the overlay is opening, and false with a console.warn explaining why when it is not - an unknown id, config still loading, or a checkout already in flight. Loading is worth handling: a shopper can tap your button before our script has fetched the button’s config, so either disable your button until window.PayBridgeNP exists or retry on a short delay when open() returns false.
• open() works on rendered buttons too. data-render="none" only controls whether we inject our element, not whether the API exists.

​

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: Enter full origins such as https://shop.example.com or http://localhost:3000. Do not include paths (/checkout), query parameters (?ref=1), fragment identifiers, or trailing slashes. Wildcards (like *.example.com) are not permitted.
• Apex and WWW are distinct: https://example.com and https://www.example.com are two separate web origins. If your customers access your shop on both forms, register both origins in your allowlist.
• Scheme and environment rules: Live mode requires secure https:// origins. Unencrypted http:// schemes and private or loopback IP addresses are rejected in Live mode. Sandbox mode permits https:// as well as http:// for local testing on localhost and 127.0.0.1.
• Domain capacity: Each project can register up to 25 allowed embed domain origins per mode (Sandbox and Live).
• The two-key system: Registering your origin in the embed domain allowlist is required, but it is only half of enabling embedded checkout. The payment button itself ALSO needs Open over my own page ticked in its button settings. Both conditions must be met for the frame to render.

​

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 not recognised until they enter their mobile number. Hosted Checkout greets them on arrival; the overlay cannot.
• A button’s amount is fixed, so a button suits a fixed price. Never drive a cart total from a custom-amount button: it takes its amount from the page, which means the browser can change it. For carts and per-product prices, have your server create the session with embedOrigin instead, as described in Cart totals and per-product prices.
• Platform plugins (WooCommerce, Shopify) use Hosted Checkout and cannot open the overlay.