> ## 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.
# Install the WooCommerce plugin
> Download, upload, activate, and configure PayBridgeNP for WooCommerce.
Installing the PayBridgeNP WooCommerce plugin takes about 5 minutes. The plugin is published on the [WordPress.org plugin directory](https://wordpress.org/plugins/paybridgenp-for-woocommerce/), so the fastest path is searching "PayBridgeNP" from your WordPress admin. ZIP upload and source install are also supported.
## 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](https://dashboard.paybridgenp.com) 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 - Install the plugin
Pick whichever path suits your setup:
### Method A - From WordPress.org (recommended)
1. In your WordPress admin, go to **Plugins → Add New**
2. In the search box, type **PayBridgeNP**
3. Find **PayBridgeNP for WooCommerce** and click **Install Now**
4. Click **Activate**
That's it. WordPress will handle future auto-updates for you.
### Method B - ZIP upload
Use this if your host blocks WordPress.org's plugin search, or if you need a specific version.
1. Download the latest release from [paybridgenp.com/integrations/woocommerce](https://paybridgenp.com/integrations/woocommerce) by clicking the **Download ZIP** button. You'll get a file named `paybridge-np-woocommerce.zip` (about 2 MB; PHP SDK bundled, no Composer needed).
2. In your WordPress admin, go to **Plugins → Add New → Upload Plugin**
3. Click **Choose File** and select the ZIP
4. Click **Install Now**, then **Activate Plugin**
The direct download URL is `https://paybridgenp.com/downloads/paybridge-np-woocommerce.zip`. You can link to it from your deployment scripts or fetch it via `curl` / `wget` if you prefer.
### Method C - From source (developers)
```bash theme={null}
cd wp-content/plugins
git clone https://github.com/paybridgenp/woocommerce.git paybridge-np-woocommerce
cd paybridge-np-woocommerce
composer install --no-dev --optimize-autoloader
```
Then activate the plugin in **Plugins → Installed Plugins**. Source clones don't get auto-updates - pull manually when a new release tag ships.
WooCommerce must be installed and active before you activate this plugin. The `Requires Plugins: woocommerce` header on this plugin means WordPress 6.5+ will block activation outright until WooCommerce is present.
## Step 2 - 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 3 - 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](https://dashboard.paybridgenp.com), 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**
## Step 4 - Place a test order
**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.
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 fulfillment)
If the order stays **On hold** longer than 30 seconds, the webhook didn't arrive - jump to [Troubleshooting](/integrations/woocommerce/troubleshooting#orders-stuck-in-on-hold).
### Sandbox test credentials
If you used a `sk_test_…` key, use these built-in test credentials on the PayBridgeNP hosted checkout:
| Provider | Credential |
| ---------- | ---------------------------------------------------------------- |
| **eSewa** | ID `9806800001`, password `Nepal@123`, MPIN `1122`, OTP `123456` |
| **Khalti** | Phone `9800000001`, MPIN `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:
```bash theme={null}
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
If you installed via **Method A** (WordPress.org), updates are automatic. WordPress will show an update notice on **Dashboard → Updates** within \~24 hours of each release; click **Update Now**.
If you installed via **Method B** (ZIP upload):
1. Download the latest ZIP from [paybridgenp.com/integrations/woocommerce](https://paybridgenp.com/integrations/woocommerce) (or from the WP.org listing)
2. In WordPress admin, go to **Plugins → Add New → Upload Plugin**
3. Choose the new ZIP and click **Install Now** - WordPress will ask if you want to **Replace current with uploaded**. Say yes.
If you installed via **Method C** (source):
```bash theme={null}
cd wp-content/plugins/paybridge-np-woocommerce
git pull
composer install --no-dev --optimize-autoloader
```
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](/integrations/woocommerce/how-it-works) - payment flow, order state transitions, webhook handling
* [Troubleshooting](/integrations/woocommerce/troubleshooting) - common install and runtime issues