Install the WooCommerce plugin

Download, upload, activate, and configure PayBridgeNP for WooCommerce.

Installing the PayBridgeNP WooCommerce plugin takes about 5 minutes. You’ll download a ZIP, upload it to your WordPress admin, activate it, and paste your PayBridgeNP secret key + webhook signing secret into the gateway settings.

Before you start

You need:

1. A WordPress site (5.8 or newer) running WooCommerce (7.0 or newer) on PHP 7.4 or newer
2. Your store currency set to NPR (Nepalese Rupee) in WooCommerce → Settings → General
3. A PayBridgeNP API key from the PayBridgeNP dashboard under Settings → API Keys (either sk_live_… or sk_test_…)
4. Administrator access to your WordPress admin - the plugin upload requires manage_options capability

Step 1 - Download the plugin

Download the latest release from paybridgenp.com/integrations/woocommerce by clicking the Download plugin button. You’ll get a file named:

paybridge-np-woocommerce.zip

This is a standard WordPress plugin ZIP - about 2 MB in size, includes the PayBridgeNP PHP SDK bundled inside so you don’t need Composer on your server.

The direct download URL is https://paybridgenp.com/downloads/paybridge-np-woocommerce.zip. You can link to it from your deployment scripts or download it via curl / wget if you prefer.

Step 2 - Upload and activate

1. In your WordPress admin, go to Plugins → Add New → Upload Plugin
2. Click Choose File and select the paybridge-np-woocommerce.zip you just downloaded
3. Click Install Now
4. Once the upload finishes, click Activate Plugin

WordPress now shows PayBridgeNP for WooCommerce in your installed plugins list.

If you see a red notice saying “PayBridgeNP for WooCommerce requires WooCommerce to be installed and active”, install WooCommerce first and then activate this plugin. The plugin checks for WooCommerce on load and refuses to register the gateway if it’s missing.

Step 3 - Enable and configure the gateway

1. Go to WooCommerce → Settings → Payments

2. You’ll see PayBridgeNP in the list of available payment methods. Click Manage next to it

3. Fill in the settings:

   Field	Value
   Enable/Disable	Check the box to enable the gateway
   Title	PayBridgeNP (or whatever you want customers to see at checkout, e.g. Pay with eSewa, Khalti, or Fonepay)
   Description	Shown below the title on the checkout page. Defaults to Pay securely with eSewa, Khalti, and more. - edit to taste
   Secret Key	Paste your sk_live_… or sk_test_… key from the PayBridgeNP dashboard
   Webhook Signing Secret	Paste your whsec_… webhook signing secret - see Step 4 below for how to get it

4. Click Save changes

Step 4 - Set up the webhook

The webhook is required. Without it, orders will be created but never move past On hold - they’ll sit there forever because WooCommerce is waiting for PayBridgeNP to confirm the payment server-to-server.

1. In your PayBridgeNP dashboard, go to Webhooks → Add endpoint

2. Set the URL to your store’s webhook endpoint:

   https://yourstore.com/?wc-api=paybridge_webhook
   

   Replace yourstore.com with your actual domain. The ?wc-api=paybridge_webhook query string is how WooCommerce routes the request to our gateway handler - it works regardless of your permalink structure.

3. Events to subscribe to:

   • payment.succeeded
   • payment.failed
   • payment.cancelled

4. Click Create endpoint

5. PayBridgeNP shows you the signing secret (whsec_…) exactly once. Copy it immediately.

6. Go back to WooCommerce → Settings → Payments → PayBridgeNP, paste the signing secret into the Webhook Signing Secret field, and click Save changes

The plugin refuses to process webhooks that aren’t signed. If the Webhook Signing Secret field is empty, any webhook delivery is rejected with a 400 response. This is deliberate - without signature verification, an attacker could forge a payment.succeeded event and get free orders. Configure the signing secret before you go live.

Step 5 - Place a test order

Switch your WordPress admin to a non-admin browser (or use an incognito window) so you’re seeing the storefront as a customer would.

1. Add any product to your cart
2. Proceed to checkout
3. At the payment step, pick PayBridgeNP
4. Click Place order

What should happen

1. WooCommerce redirects you to the PayBridgeNP hosted checkout page
2. You pick a wallet (eSewa, Khalti, or Fonepay) and complete the payment
3. PayBridgeNP redirects you back to your store
4. You land on the Order received page - the order shows as On hold
5. Within a few seconds, the signed webhook arrives, and the order automatically moves to Processing (the normal WooCommerce state for a paid order awaiting fulfilment)

If the order stays On hold longer than 30 seconds, the webhook didn’t arrive - jump to Troubleshooting.

Sandbox test credentials

If you used a sk_test_… key, use these built-in test credentials on the PayBridgeNP hosted checkout:

Provider	Credential
eSewa	Any amount, merchant code EPAYTEST
Khalti	Phone [phone], PIN 1111, OTP 987654

Sandbox payments appear in your PayBridgeNP dashboard under Sandbox - no real money moves.

Local development webhook testing

PayBridgeNP needs a publicly reachable URL to deliver webhooks. If your WordPress is running on http://localhost, you’ll need a tunnel tool to expose it:

ngrok http 80

Then use the generated https://xxx.ngrok.io/?wc-api=paybridge_webhook as your webhook endpoint URL in the PayBridgeNP dashboard. Switch it back to your real domain before going live.

Updating the plugin

When a new version ships:

1. Download the latest ZIP from paybridgenp.com/integrations/woocommerce
2. In WordPress admin, go to Plugins → Installed Plugins
3. Deactivate PayBridgeNP for WooCommerce (don’t delete - your settings will be wiped)
4. Upload the new ZIP via Plugins → Add New → Upload Plugin - WordPress will ask if you want to Replace current with uploaded. Say yes.
5. Reactivate the plugin

Your settings (API key, webhook secret, gateway title, etc.) persist across updates because they’re stored in WordPress’s wp_options table, not in the plugin directory.

What’s next

• How it works - payment flow, order state transitions, webhook handling
• Troubleshooting - common install and runtime issues