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
Invoice #1042Unpaid
Shared hosting, 12 monthsNPR 6,000.00
Domain renewal, 1 yearNPR 1,500.00
Total dueNPR 7,500.00

Payment method: eSewa, Khalti or Fonepay

Pay now

Requirements. Check these first.

WHMCS8.x, on PHP 7.4 to 8.3 with the cURL and JSON extensions and a MySQL or MariaDB database
System URLA public HTTPS System URL in WHMCS
CronThe WHMCS cron running. It re-checks payments when a customer closes the browser before returning
Database userPermission to create tables. The module creates mod_paymentnp_v2_attempts and mod_paymentnp_v2_events on first use
PaymentsnpA workspace with at least one gateway enabled and ready in the environment you use
NPR rateIf 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.

  1. Copy the files

    Copy both folders from the package into your WHMCS root: modules/ into <whmcs>/modules/ and includes/ into <whmcs>/includes/.

  2. Activate the gateway

    Open Configuration > Apps & Integrations > Payments > Payment Gateways and activate Paymentsnp.

  3. 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 checkouts
  • checkout:read, to check checkout status on return and from cron
  • payments: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.

Gateway settings
EnvironmentTest while you try it, Live to take real payments
Test or Live API KeyA 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 URLLeave as https://api.paymentnp.com/v1
Webhook SecretOptional. 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.

  1. Webhook, at once

    With a webhook endpoint set up, the invoice is marked paid as soon as Paymentsnp confirms the payment.

  2. Return, when the customer comes back

    Returning to WHMCS triggers a status check against the API.

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

Webhook endpoint URL
https://<your WHMCS>/modules/gateways/callback/paymentnpv2.php
Add it in Paymentsnp > Webhooks, in the same environment as the gateway.

How payments behave. No double charges.

Pay now twiceA second click or a second tab gets the same checkout. If a payment is in progress, checkout says so instead of starting another
Balance changesIf the invoice balance changes, a new Paymentsnp order is used for the new amount
CurrencyAmounts are converted to NPR at your WHMCS rate when the customer clicks Pay now
Test modeUse an np_test_ key and the Sandbox gateway. The button shows a TEST badge and the transaction id looks like PAYMENTNP-SANDBOX-…
EnvironmentsCheckouts 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.

Common WHMCS module errors
Error codeMeaningFix
not_configuredNo key for the selected environment, or the key does not match itPaste an np_test_ key for Test or an np_live_ key for Live
insufficient_scopeThe key is missing a scopeUse a key with checkout:create, checkout:read and payments:read
api_key_ip_deniedThe WHMCS server IP is not in the key's allowlistAdd the server's outbound IP, or clear the allowlist
return_url_not_allowedThe WHMCS origin is not allowedAdd it under Settings > Allowed return origins
no_available_methodsNo enabled, ready gateway in this environmentConnect or enable one under Gateways
network_errorWHMCS could not reach the APICheck outbound HTTPS on port 443, DNS and the firewall
Invoice not marked paidThe customer did not return and cron has not run yetCheck 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.