Skip to main content
Embedded Checkout opens the PayBridgeNP checkout in an overlay on your own page instead of sending the customer to a payment page. Your page stays behind it and its address bar never changes, and when the payment finishes the overlay closes and hands the customer back to you. Paying still involves the wallet the customer picks. Fonepay is completed inside the overlay, and so is eSewa when your project is on the eSewa Intent rail. Khalti sends the customer to its own app or website and brings them back. So the overlay removes the redirect to us, not every hand-off to a wallet. It is the same checkout you get from the quickstart, the same providers, and the same verification. Only the way the customer reaches it differs.
Embedded Checkout requires a Growth plan or higher, because it is delivered through a payment button and those are not available on the Free plan.
Embedded Checkout is live. Nothing changes for an existing button until you tick Open over my own page on it and add your origin to the embed allowlist, so buttons keep redirecting until you opt them in.

​
Hosted or Embedded

​
How it works

1

Create a payment button and turn the overlay on

Configure it as you would a normal payment button, then tick Open over my own page under “Where the checkout opens”. Buttons redirect to a PayBridgeNP checkout page until you do, so an existing button never changes behaviour on its own.
2

Add your origin to the allowlist

Register your web page origin under Project -> Embed domains in your merchant dashboard.
3

Add the script to your page

The same one-line embed. No separate SDK.
4

The customer taps it

The overlay opens over your page. Your page is never navigated.
5

They pay and come back

The overlay closes and returns them to your return URL at the top level, not inside the frame.

​
If your shopper is already signed in

Pass what you know and the overlay opens with it filled in:
This matters more in the overlay than anywhere else. The overlay collects contact details itself, so without this a signed-in shopper would retype details your site already had. See payment buttons for the full rules.

​
Registering allowed embed domains

To protect your site and your customers from clickjacking, Embedded Checkout uses an explicit origin allowlist. A page attempting to embed your checkout whose origin is not registered on your allowlist will be blocked by the browser.

​
The symptom of an unallowed domain

If your site origin is not registered on your project allowlist:
  • 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 ..."
To fix this, register your page’s exact web origin under Project -> Embed domains in your merchant dashboard.

​
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

eSewa and Khalti authenticate inside their own app or website. That is what keeps the customer’s PIN away from your site and from ours, so the overlay hands off rather than trying to contain it.
  • 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.
Fonepay is the exception: its QR is displayed and confirmed inside the overlay with no hand-off at all. While the customer is away, the overlay shows a waiting screen with a manual status check. If a payment completes but the provider’s confirmation never reaches us, that check asks the provider directly rather than only re-reading our own records.

​
Closing and reopening is safe

If the customer closes the overlay and opens it again, they resume the same payment, not a new one. Anything they had already typed is still there. This matters for more than convenience: it means one order can never produce two live payment sessions, so a customer cannot accidentally pay twice for the same thing.

​
PayBridgeNP ID inside the overlay

PayBridgeNP ID works in the overlay, with one difference worth planning around. What works. A returning customer types their mobile number, we tell them we have their details, they enter a one-time code, and their name, email and phone fill in. Same as hosted checkout. What does not. They are not recognised before they type. On hosted checkout a returning customer is greeted by name on arrival; in the overlay they always start by entering their number. The reason is the browser, not a missing feature. Silent recognition depends on a cookie on the PayBridgeNP domain, and browsers deliberately withhold that cookie from a page running inside another site. The overlay is exactly that. For the same reason, “remember me on this device” is offered only on hosted checkout. The overlay does not show it, because the grant it creates could not be delivered.

​
What you still handle

The overlay is the payment step only. Your cart, your prices, your discounts, and your order records stay yours. PayBridgeNP creates a session for an amount you give it and tells you when that amount is paid. Discount codes are a good example: apply them in your own cart and send us the final amount. There is no promo-code field in the checkout.

​
Verifying the payment

Do not treat the overlay closing as proof of payment. Confirm it the same way you would for any other PayBridgeNP integration:
  • Listen for the payment.succeeded webhook, which is signed and retried until you acknowledge it.
  • Or read the session back through the API.
See Confirming payments for the full contract.

​
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.
  • The amount comes from the button, so the overlay suits a fixed price. A custom-amount button takes its amount from the page, which means the browser can change it. Never drive a cart total that way. Carts belong on Hosted Checkout, where your server states the amount.
  • Platform plugins (WooCommerce, Shopify) use Hosted Checkout and cannot open the overlay.