Troubleshooting

Common issues when setting up and running the PayBridgeNP for WHMCS module, and how to fix them.

If something isn’t working, check the Utilities → Logs → Gateway Log inside WHMCS admin first. Every API call, webhook delivery, and refund attempt is recorded there with a structured payload. Most issues in this guide point you at the matching Gateway Log entry.

Webhook returns 200 but invoice stays Unpaid

Symptom: The PayBridgeNP dashboard shows a payment.succeeded webhook delivered with a 200 response, but the WHMCS invoice never flips to Paid.

Almost always the cause: the webhook URL in the PayBridgeNP dashboard was registered as just the domain root instead of the full callback path. PayBridgeNP POSTs to https://your-whmcs-url/ (your WHMCS homepage), which returns 200 but ignores the payload.

Fix: In the PayBridgeNP dashboard, edit the webhook endpoint and change the URL to the full callback path:

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

Then click Replay on the original delivery - our callback will verify the HMAC, resolve the invoice from metadata, and flip it to Paid.

Refund fails with “reason must be one of…”

Symptom: Clicking Refund via Gateway shows “Refund Failed” and the Gateway Log contains:

event => refund.api_error
message => reason must be one of: customer_request, duplicate, fraudulent, other

Cause: You’re running module version 0.1.0 or earlier, which sent a freeform string as the reason field.

Fix: Upgrade to 0.1.1 or later. Version 0.1.1 sends reason=other and puts the WHMCS context in the notes field, matching the PayBridgeNP API’s enum requirement.

Gateway doesn’t show up in Apps & Integrations

Symptom: After extracting the ZIP, PayBridgeNP doesn’t appear in the Apps & Integrations list.

Things to check:

1. The modules/gateways/paybridgenp.php file is present and readable by your web server user

2. The modules/gateways/paybridgenp/vendor/autoload.php file exists - if you copied only the .php file without the paybridgenp/ directory, the module will throw a fatal on load. Re-extract the full ZIP.

3. PHP version is 7.4 or newer and ionCube Loader is enabled (run php -v on the server - you should see “ionCube PHP Loader”)

4. Clear the WHMCS template cache:

   rm -f /path/to/whmcs/templates_c/*.php
   

“Your license key is invalid” after changing servers

Symptom: WHMCS redirects everything to /admin/licenseerror.php?status=Invalid. The error page shows:

Valid Domains: localhost
Valid IPs: 172.17.0.1

…but your current IP or domain doesn’t match.

Cause: WHMCS licenses are bound to the server’s IP + domain + install directory. When any of those change (e.g. migrating Docker images, moving hosts, renaming domains), the license check fails.

Fix: Log in to clientarea.whmcs.com and click Reissue License on the product detail page. The next request from the new environment re-registers. This applies to dev licenses too.

Invoice payment gets redirected to https://localhost (connection refused)

Symptom: Admin pages redirect to https://localhost/... and the browser shows ERR_CONNECTION_REFUSED.

Cause: During install, WHMCS saved SystemURL as https://localhost/ - now every admin navigation forces HTTPS redirect, but your container only serves HTTP.

Fix: Update tblconfiguration.SystemURL directly in the database:

UPDATE tblconfiguration SET value='http://localhost:8080/' WHERE setting='SystemURL';

Then reload /admin/ without the trailing https://.

Webhook rejected with “Invalid signature”

Symptom: Gateway Log shows webhook.invalid_signature for every incoming webhook.

Cause: The Webhook Signing Secret in your gateway config does not match the secret issued when the webhook endpoint was registered in the PayBridgeNP dashboard.

Fix:

1. In the PayBridgeNP dashboard, delete the webhook endpoint
2. Re-create it - PayBridgeNP shows the new signing secret (whsec_…) exactly once
3. Paste the new secret into the Webhook Signing Secret field in WHMCS and save

Signing secrets can never be retrieved after the initial display - always copy them immediately.

Checkout creation fails with HTTP 400

Symptom: Clicking Pay Now shows “Could not start payment: …” and the Gateway Log shows checkout.api_error.

Common causes:

• Currency is not NPR. The module rejects invoices in any other currency. Change your store default or set the invoice currency to NPR.
• API key is blank or wrong. Confirm you pasted a sk_test_… or sk_live_… key and there’s no stray whitespace.
• Test Mode toggle doesn’t match the key type. If you’re using a sk_test_… key, check Test Mode to on. If you’re using sk_live_…, leave it off.

Invoice stays on the “submitted” state forever

Symptom: Customer completes payment, returns to WHMCS, invoice shows a paybridge_status=submitted in the URL but still says Unpaid, and no webhook shows up in the PayBridgeNP dashboard.

Things to check:

1. Is the webhook endpoint reachable from the internet? For local dev, you need a tunnel (cloudflared or ngrok) and the Public Callback URL field must point at the tunnel URL.
2. Is the webhook endpoint registered with the right events? It must subscribe to payment.succeeded at minimum.
3. Check the PayBridgeNP dashboard’s webhook delivery log for the delivery attempt - if PayBridgeNP is not even trying to deliver, the endpoint might be disabled or the URL might be malformed.

Debug Logging captures too much - noisy Gateway Log

Symptom: Every Pay Now click writes three entries, and the Gateway Log fills up.

Cause: Debug Logging is enabled. That’s fine during setup but overkill in production - debug entries include full API request/response bodies for every checkout and webhook.

Fix: In Configuration → System Settings → Payment Gateways → PayBridgeNP, turn off Debug Logging and save. The module still logs every important event (checkout.created, webhook.payment_applied, refund.success, all error types) - debug entries are only the raw HTTP bodies.

Still stuck?

If none of the above fit your issue:

1. Enable Debug Logging in the gateway config
2. Reproduce the issue
3. Export the matching Gateway Log entries (remove any message / data fields that still contain sensitive info - secrets are scrubbed automatically but always double-check before sharing)
4. Contact us via paybridgenp.com/contact with the payment id (pay_…) or checkout session id (cs_…) and the log excerpts

What’s next

• Back to installation
• How it works - flow + security details