Paymentsnp for WHMCS
Version 3.0.0 of the gateway module adds a Pay now button to unpaid WHMCS invoices. Customers pay with the eSewa, Khalti and Fonepay gateways connected to your workspace, the money settles to your provider accounts, and WHMCS stores only your Paymentsnp API key.
- Gateway id paymentnpv2
- Upgrades v2 in place
- Cron re-check as a fallback
| Shared hosting, 12 months | NPR 6,000.00 |
| Domain renewal, 1 year | NPR 1,500.00 |
| Total due | NPR 7,500.00 |
Payment method: eSewa, Khalti or Fonepay
Requirements. Check these first.
| WHMCS | 8.x, on PHP 7.4 to 8.3 with the cURL and JSON extensions and a MySQL or MariaDB database |
|---|---|
| System URL | A public HTTPS System URL in WHMCS |
| Cron | The WHMCS cron running. It re-checks payments when a customer closes the browser before returning |
| Database user | Permission to create tables. The module creates mod_paymentnp_v2_attempts and mod_paymentnp_v2_events on first use |
| Paymentsnp | A workspace with at least one gateway enabled and ready in the environment you use |
| NPR rate | If your invoices are not in NPR, an NPR currency with a correct exchange rate under Configuration > System Settings > Currencies |
Install. Three steps in WHMCS.
Download the module from Dashboard > Downloads in Paymentsnp. Downloads are open to verified owner, administrator and developer users.
Copy the files
Copy both folders from the package into your WHMCS root: modules/ into <whmcs>/modules/ and includes/ into <whmcs>/includes/.
Activate the gateway
Open Configuration > Apps & Integrations > Payments > Payment Gateways and activate Paymentsnp.
Fill in the settings and save
Saving runs a connection test. A failure is shown on screen and written to the Gateway Log.
Settings. One key per environment.
API key scopes
checkout:create, to create checkoutscheckout:read, to check checkout status on return and from cronpayments:read, to read the verified payment before crediting the invoice
If the key has an IP allowlist, add your WHMCS server's outbound IP address. Rolling a key keeps the old one working for the grace period you pick, so you can paste the new one in without downtime.
Allowed return origins
Add the origin of your WHMCS System URL, for example https://billing.example.com, under Settings > Allowed return origins in Paymentsnp. Without it, checkout creation fails with return_url_not_allowed. If you verified a custom checkout domain, customers are sent to it automatically.
| Environment | Test while you try it, Live to take real payments |
|---|---|
| Test or Live API Key | A key from Paymentsnp > API keys in that environment (np_test_… or np_live_…). Only the selected environment's key is used |
| Test or Live API URL | Leave as https://api.paymentnp.com/v1 |
| Webhook Secret | Optional. The whsec_… secret of the webhook endpoint in that environment |
How a payment is confirmed. Three routes, one check.
Return pages are never treated as proof. Every route ends with the module asking the Paymentsnp API for the payment.
Webhook, at once
With a webhook endpoint set up, the invoice is marked paid as soon as Paymentsnp confirms the payment.
Return, when the customer comes back
Returning to WHMCS triggers a status check against the API.
Cron, as the fallback
If the customer closed the browser, the next cron run re-checks open payments.
What the module accepts
- A valid signature
- Less than 5 minutes old, so keep the server clock in sync with NTP
- Not seen before
Even then, the module never trusts the webhook body. It fetches the payment and credits the invoice only when the order, the exact amount, the currency and the environment all match. If processing fails, it answers with an error and Paymentsnp retries.
https://<your WHMCS>/modules/gateways/callback/paymentnpv2.phpHow payments behave. No double charges.
| Pay now twice | A second click or a second tab gets the same checkout. If a payment is in progress, checkout says so instead of starting another |
|---|---|
| Balance changes | If the invoice balance changes, a new Paymentsnp order is used for the new amount |
| Currency | Amounts are converted to NPR at your WHMCS rate when the customer clicks Pay now |
| Test mode | Use an np_test_ key and the Sandbox gateway. The button shows a TEST badge and the transaction id looks like PAYMENTNP-SANDBOX-… |
| Environments | Checkouts started in one environment are never credited while the gateway is set to the other |
Upgrade from v2. In place, no deactivation.
Upload the v3 files over v2, overwriting the existing files. You don't need to deactivate the gateway.
- The gateway id paymentnpv2, settings, payment table and transaction id format are unchanged
- Saved keys, existing invoices and payment history keep working
- Payments already credited by v2 are recognised, so they are never credited twice
- Checkouts that v2 started keep working
- New optional settings: Test and Live Webhook Secret
Troubleshooting. Look in the Gateway Log first.
Errors are written to Billing > Gateway Log under Paymentsnp, with the API error code, what to do and a request id you can quote.
| Error code | Meaning | Fix |
|---|---|---|
not_configured | No key for the selected environment, or the key does not match it | Paste an np_test_ key for Test or an np_live_ key for Live |
insufficient_scope | The key is missing a scope | Use a key with checkout:create, checkout:read and payments:read |
api_key_ip_denied | The WHMCS server IP is not in the key's allowlist | Add the server's outbound IP, or clear the allowlist |
return_url_not_allowed | The WHMCS origin is not allowed | Add it under Settings > Allowed return origins |
no_available_methods | No enabled, ready gateway in this environment | Connect or enable one under Gateways |
network_error | WHMCS could not reach the API | Check outbound HTTPS on port 443, DNS and the firewall |
| Invoice not marked paid | The customer did not return and cron has not run yet | Check that the WHMCS cron runs, or set up webhooks |
Questions about the module.
Do I need webhooks?
No, but they help. Without them, invoices are marked paid when the customer returns to WHMCS or on the next cron run. A webhook marks them paid as soon as Paymentsnp confirms the payment.
My invoices are in US dollars. Will it work?
Yes, if WHMCS has an NPR currency with a correct exchange rate. The amount is converted to NPR when the customer clicks Pay now.
Does upgrading from v2 lose payment history?
No. The gateway id paymentnpv2, settings, payment table and transaction id format are unchanged, and payments v2 already credited are never credited twice.
What does WHMCS store?
Only your Paymentsnp API key, and the optional webhook secret. Provider credentials stay in Paymentsnp.