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.

Payment buttons are embeddable checkout widgets that let customers pay directly from your website. You configure everything in the dashboard and embed a single <script> tag - the button fetches its settings live from PayBridgeNP, so changes you make in the dashboard take effect on the next page load without re-embedding.

​
Use cases

  • E-commerce - add a Buy Now button to a product page
  • Donations - accept fixed or custom-amount contributions
  • SaaS - quick one-time payments from a landing page
  • Invoicing - embed a Pay button in an email template or hosted invoice

​
How it works

1

Create a button in the dashboard

Configure the label, amount, color, customer fields, and return URL.
2

Copy the embed snippet

You get a single <script> tag containing only a button ID.
3

Paste it on your site

The script loads the button, which fetches its latest config from the API automatically.
4

Customer clicks and pays

A secure modal opens, collects any required information, creates a checkout session, and redirects to the provider (eSewa, Khalti, or Fonepay).

​
Creating a button

  1. Go to Buttons in the dashboard
  2. Click New button
  3. Configure the button:
FieldRequiredDescription
Internal nameYesFor your reference only - not shown to customers
Button labelYesText displayed on the button (e.g. “Pay Now”, “Donate”, “Buy”)
ColorNoHex color for the button background (default: #5C2D91)
AmountYesFixed amount in NPR, or “Customer enters amount” for open-amount
DescriptionNoShown on the checkout page
Return URLYesWhere the customer is redirected after payment
Cancel URLNoWhere the customer is redirected if they cancel
ProviderNoPre-select a payment provider (eSewa, Khalti, or Fonepay) - or let the customer choose
Collect nameNoShow a “Full name” field before checkout
Collect emailNoShow an “Email address” field before checkout
Collect phoneNoShow a “Phone number” field before checkout
  1. Click Create button - you will see an embed snippet.

​
Embedding the button

Copy the snippet and paste it anywhere inside your page’s <body>: 
<script
  src="https://api.paybridgenp.com/js/v1/button.js"
  data-button-id="btn_xxx">
</script>
The button renders inline, right where the script tag is placed. No additional CSS or JavaScript is required.
The snippet only contains a button ID. All configuration (label, color, amount, collect fields) is fetched live from the API on each page load. If you change a setting in the dashboard, every page using that button updates automatically - you never need to re-embed.

​
Multiple buttons on one page

You can embed multiple buttons on the same page. Each script tag renders independently: 
<!-- Product A -->
<script
  src="https://api.paybridgenp.com/js/v1/button.js"
  data-button-id="btn_aaa">
</script>

<!-- Product B -->
<script
  src="https://api.paybridgenp.com/js/v1/button.js"
  data-button-id="btn_bbb">
</script>

​
Inline overrides

In rare cases, you may want the same button to behave differently on different pages (e.g. different amounts for different products). You can override settings with data-* attributes on the script tag: 
<script
  src="https://api.paybridgenp.com/js/v1/button.js"
  data-button-id="btn_xxx"
  data-amount="150000"
  data-label="Buy Premium">
</script>
AttributeDescription
data-amountOverride the amount (in paisa, e.g. 150000 = NPR 1,500.00)
data-labelOverride the button label text
data-colorOverride the button color (hex, e.g. #1e00ff)
data-collect-nameOverride collect name setting ("true" or "false")
data-collect-emailOverride collect email setting ("true" or "false")
data-collect-phoneOverride collect phone setting ("true" or "false")
Inline overrides take precedence over dashboard settings. If an attribute is not present, the dashboard setting is used.

​
Customer experience

When a customer clicks the button:
  1. A secure modal opens with the PayBridgeNP branding and the button’s color
  2. If collect fields are enabled, the customer fills in their name, email, or phone
  3. For custom-amount buttons, the customer enters the amount in NPR
  4. The customer clicks the pay button inside the modal
  5. A checkout session is created and the customer is redirected to the selected payment provider
  6. After payment, the customer is redirected to your return URL with session_id, status, and payment_id query parameters

​
Return URL parameters

After payment, your return URL receives these query parameters: 
https://yoursite.com/thank-you?session_id=cs_xxx&status=success&payment_id=pay_xxx
ParameterDescription
session_idThe checkout session ID
statussuccess or failed
payment_idThe payment ID (only present on success)
Do not rely solely on the return URL parameters to confirm payment. A customer can modify the URL. Always verify payment status server-side using a webhook or the payment status API.

​
Validation

The payment button validates customer input before submitting:
FieldValidation
Full nameAt least 2 characters
EmailValid email format (e.g. user@example.com)
Phone7-15 digits, optional + prefix
Amount (custom)Positive number in NPR
These rules are enforced both in the client-side modal and on the API. Invalid input will not create a checkout session.

​
Webhooks

Payment button transactions fire the same webhooks as API-created checkout sessions. The webhook payload includes the payment_button_id field in the checkout session data. Set up a webhook endpoint in the dashboard to receive payment.succeeded events. See Webhook verification for details.

​
Managing buttons

​
Enable / disable

Toggle a button on or off from the dashboard table. Disabled buttons are invisible - the script tag renders nothing on your page, so visitors see a blank space instead of a broken button.

​
Editing

Click the edit icon on any button to change its settings. Since the button fetches config live, changes take effect on the next page load. No action is needed on your website.

​
Deleting

Deleting a button is permanent. Any pages still using its embed snippet will render nothing.

​
Stats

The dashboard table shows per-button stats:
ColumnDescription
PaymentsNumber of successful payments through this button
VolumeTotal NPR amount collected through this button

​
Sandbox testing

Payment buttons respect the mode of the project they belong to. Buttons on a sandbox project will use sandbox credentials and test payment flows. Buttons on a live project will process real payments. See Sandbox testing for provider-specific test credentials.

​
Limitations

  • Payment buttons are created and managed from the dashboard only - there is no API to create them programmatically
  • Each project can have up to 200 buttons
  • The button script requires JavaScript to be enabled in the customer’s browser
  • The button renders as an inline-block element with a max width of 340px
  • Custom CSS cannot be applied to the button (styling is self-contained to prevent conflicts with your site)