> ## 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 WHMCS module

> Download, extract, activate, and configure PayBridgeNP for WHMCS.

Installing the PayBridgeNP WHMCS module takes about 10 minutes. You'll download a ZIP, extract it into your WHMCS install, activate the gateway from **Apps & Integrations**, and paste your PayBridgeNP test or live key plus the webhook signing secret.

## Before you start

You need:

1. A **WHMCS** installation (version **8.0 or newer**) running on **PHP 7.4 or newer** with the **ionCube Loader** extension enabled
2. Your invoice currency set to **NPR** (Nepalese Rupee) in **Configuration → System Settings → Currencies** - this module only sends NPR amounts
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 WHMCS admin area and SSH / SFTP access to the WHMCS install directory on your server

## Step 1 - Download the module

Download the latest release from [paybridgenp.com/integrations/whmcs](https://paybridgenp.com/integrations/whmcs) by clicking the **Download module** button, or find us on the [WHMCS Marketplace](https://marketplace.whmcs.com/product/8648-paybridgenp). You'll get a file named:

```
paybridgenp-whmcs-<version>.zip
```

This is a \~60 KB archive - the PayBridgeNP PHP SDK is vendored inside, so you don't need Composer on your server.

<Tip>
  If you prefer to pull it from the command line:

  ```bash theme={null}
  curl -LO https://paybridgenp.com/downloads/paybridgenp-whmcs-latest.zip
  ```
</Tip>

## Step 2 - Extract into your WHMCS install

The ZIP is structured to drop into the root of your WHMCS install. From the server's WHMCS directory (the one containing `configuration.php`, `admin/`, `modules/`, etc.):

```bash theme={null}
cd /path/to/whmcs
unzip paybridgenp-whmcs-<version>.zip
```

The archive adds three things under `modules/gateways/`:

```
modules/gateways/
├── paybridgenp.php                      ← main gateway file
├── paybridgenp/                         ← helpers + vendored SDK
│   ├── init.php
│   ├── src/
│   ├── vendor/
│   ├── logo.png
│   └── whmcs.json
└── callback/paybridgenp.php             ← return URL + webhook handler
```

<Warning>
  Do NOT upload the ZIP through the WHMCS admin UI - WHMCS's built-in uploader is for addon modules, not gateway modules. Gateway modules must be placed on the filesystem directly. If you don't have SSH / SFTP access, use your hosting panel's **File Manager** to unzip it in place.
</Warning>

## Step 3 - Activate the gateway

1. Log in to your WHMCS admin area
2. Go to **Configuration → System Settings → Payment Gateways**
3. Click the **All Payment Gateways** tab (or the **→ Visit Apps & Integrations** button)
4. Find **PayBridgeNP** in the list and click the tile

<Frame caption="The PayBridgeNP listing inside Apps & Integrations - logo, description, category, and developer links.">
  <img src="https://mintcdn.com/paybridgenp/cJL91VnZU_QZLvyp/images/integrations/whmcs/01-apps-integrations-tile.png?fit=max&auto=format&n=cJL91VnZU_QZLvyp&q=85&s=f53942b054093e6af05918b53ccce19a" alt="PayBridgeNP tile inside WHMCS Apps & Integrations" width="1524" height="1506" data-path="images/integrations/whmcs/01-apps-integrations-tile.png" />
</Frame>

5. Click **Activate** (or **Manage** if it's already activated)

WHMCS redirects you to the gateway configuration form.

## Step 4 - Configure the gateway

Fill in the form:

<Frame caption="Gateway configuration form with all fields populated.">
  <img src="https://mintcdn.com/paybridgenp/cJL91VnZU_QZLvyp/images/integrations/whmcs/03-gateway-config-filled.png?fit=max&auto=format&n=cJL91VnZU_QZLvyp&q=85&s=7f2b809600038b9b4b2abf66224a39ce" alt="PayBridgeNP WHMCS gateway configuration form" width="2576" height="820" data-path="images/integrations/whmcs/03-gateway-config-filled.png" />
</Frame>

| Field                      | Value                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show on Order Form**     | ✅ check to expose PayBridgeNP on client-facing checkout                                                                                                                            |
| **Display Name**           | `PayBridgeNP` (or whatever you want customers to see, e.g. `Pay with eSewa or Khalti`)                                                                                             |
| **Live Secret Key**        | Paste your `sk_live_…` key. Leave blank while you're testing with `sk_test_…`.                                                                                                     |
| **Test Secret Key**        | Paste your `sk_test_…` key. Used when **Test Mode** is enabled.                                                                                                                    |
| **Test Mode**              | Check while you're testing - routes all API calls to the sandbox using the test key above                                                                                          |
| **Webhook Signing Secret** | Your `whsec_…` - see [Step 5](#step-5-register-the-webhook)                                                                                                                        |
| **Public Callback URL**    | Usually leave blank. Fill only if your WHMCS is behind a load balancer, a different public hostname, or you're using a tunnel in local dev. Example: `https://tunnel.example.com/` |
| **Payment Method**         | Leave as **Let payer choose** - the hosted page shows both eSewa and Khalti. Or force one method if you only want one visible.                                                     |
| **Debug Logging**          | On while testing - writes full API request/response bodies to the Gateway Log. Turn off in production.                                                                             |

Don't click **Save Changes** yet - you still need the webhook signing secret in the next step.

## Step 5 - Register the webhook

The webhook is **required**. Without it, customers can successfully pay on the PayBridgeNP hosted checkout but the WHMCS invoice will stay **Unpaid** - WHMCS has no way to know the payment completed.

1. In your [PayBridgeNP dashboard](https://dashboard.paybridgenp.com), go to **Webhooks → Add endpoint**

2. Set the **URL** to the full callback path on your WHMCS install:

   ```
   https://your-whmcs-url/modules/gateways/callback/paybridgenp.php
   ```

   <Warning>
     **Use the full path, not just the domain.** If you paste only the base URL (`https://your-whmcs-url/`), PayBridgeNP will POST webhooks to your WHMCS homepage, which returns 200 but ignores the payload - the invoice never gets marked paid.
   </Warning>

3. **Events to subscribe to:**
   * `payment.succeeded`
   * `payment.failed`

4. Click **Create endpoint**

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

6. Paste it into the **Webhook Signing Secret** field in the gateway config from Step 4, then click **Save Changes**

## Step 6 - Place a test invoice

Switch to a non-admin browser (or use an incognito window) so you see the client area like a real customer does.

1. In WHMCS admin, go to **Clients → Add New Client** and create a minimal client record
2. Open that client → **Invoices** tab → **Create New Invoice** - add a line item (e.g. `Test` for `Rs. 100.00`), set **Payment Method** to `PayBridgeNP`
3. Click **Publish** - drafts don't show a Pay button on the client side
4. Click **View as Client** (or use the client-area login link)

You should see an invoice with a purple **Pay Now** button:

<Frame caption="Client-side invoice view - the Pay Now button invokes the PayBridgeNP gateway.">
  <img src="https://mintcdn.com/paybridgenp/cJL91VnZU_QZLvyp/images/integrations/whmcs/04-invoice-pay-now.png?fit=max&auto=format&n=cJL91VnZU_QZLvyp&q=85&s=09374c3c9ebbac1396a440fabfe234f6" alt="Client-area invoice with Pay Now button" width="1516" height="1500" data-path="images/integrations/whmcs/04-invoice-pay-now.png" />
</Frame>

### What should happen

1. Clicking **Pay Now** creates a PayBridgeNP checkout session and redirects you to the hosted payment page
2. Pick **eSewa** or **Khalti** on the hosted page and complete the payment (sandbox credentials listed below)
3. PayBridgeNP redirects you back to the WHMCS invoice view
4. Within a few seconds the signed webhook arrives and the invoice flips to **Paid** - a transaction row appears under **Transactions** with the PayBridgeNP payment id (`pay_…`)

If the invoice stays **Unpaid** longer than 30 seconds, the webhook didn't arrive - jump to [Troubleshooting: webhook not applied](/integrations/whmcs/troubleshooting#webhook-returns-200-but-invoice-stays-unpaid).

### Sandbox test credentials

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

| Provider   | Credential                                    |
| ---------- | --------------------------------------------- |
| **eSewa**  | Merchant code `EPAYTEST`, any amount          |
| **Khalti** | Phone `9800000001`, MPIN `1111`, OTP `987654` |

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

## Local development webhook testing

If you're running WHMCS on `http://localhost` (e.g. inside Docker), PayBridgeNP can't reach it directly. Use a tunnel:

```bash theme={null}
cloudflared tunnel --url http://localhost:8080
# or
ngrok http 8080
```

Then paste the public `https://…trycloudflare.com/` URL into the **Public Callback URL** field in your gateway settings. This lets our module generate return/webhook URLs against the tunnel without you having to change the WHMCS **System URL** (which affects admin navigation).

Register the webhook in your PayBridgeNP dashboard against the same tunnel URL - full path, as always:

```
https://<tunnel>.trycloudflare.com/modules/gateways/callback/paybridgenp.php
```

## Updating the module

When a new version ships:

1. Download the latest ZIP from [paybridgenp.com/integrations/whmcs](https://paybridgenp.com/integrations/whmcs) or the [WHMCS Marketplace](https://marketplace.whmcs.com/product/8648-paybridgenp)
2. Extract it into the root of your WHMCS install - files overwrite in place; your gateway config persists because it's stored in `tblpaymentgateways`, not on disk

No deactivation / reactivation dance needed.

## What's next

* [How it works](/integrations/whmcs/how-it-works) - payment flow, invoice state transitions, security model
* [Troubleshooting](/integrations/whmcs/troubleshooting) - common issues and how to fix them