Skip to main content
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:
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:

​
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.):
The archive adds three things under modules/gateways/:
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
PayBridgeNP tile inside WHMCS Apps & Integrations

The PayBridgeNP listing inside Apps & Integrations - logo, description, category, and developer links.

  1. 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:
PayBridgeNP WHMCS gateway configuration form

Gateway configuration form with all fields populated.

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:
    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
  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:
Client-area invoice with Pay Now button

Client-side invoice view - the Pay Now button invokes the PayBridgeNP gateway.

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

​
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