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 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 by clicking the Download module button, or find us on the WHMCS Marketplace. 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.

If you prefer to pull it from the command line:

curl -LO https://paybridgenp.com/downloads/paybridgenp-whmcs-latest.zip

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.):

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

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.

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

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:

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
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, 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
   
   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.

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. 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:

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.

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 [phone], PIN 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:

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 or the WHMCS Marketplace
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 - payment flow, invoice state transitions, security model
• Troubleshooting - common issues and how to fix them