WHMCS gateway

Before you install#

• An approved NuePay business account with API access.
• WHMCS, PHP 8.2–8.4 in a supported combination, cURL, MySQL/MariaDB and a valid HTTPS System URL.
• UGX invoices and the normal WHMCS automation cron.

The gateway uses PHP and a reconciliation hook. No addon, Node service or Composer installation is required on your hosting account.

Install and activate#

1. Download NuePay WHMCS from NuePay → Integrations → Plugins.
2. Back up your WHMCS files and database. Extract the ZIP into the WHMCS root, merging modules and includes.
3. Activate NuePay under System Settings → Payment Gateways or Apps & Integrations.

The package includes its callback and cron hook. It creates only its own mod_nuepay_* tables; no core WHMCS files are replaced.

Connect your account#

Create a dedicated key in API Keys, with a nickname such as “WHMCS — My Hosting Company”. Set its Web Hook URL to:

https://YOUR-BILLING-HOST/modules/gateways/callback/nuepay.php

Include your WHMCS subdirectory where applicable. Reveal the separate signing secret with your PIN.

No account number or WHMCS API credentials are required. The key identifies the account and application.

Test, then go live#

Start in Test Mode. Open an unpaid UGX invoice, choose NuePay and submit a supported number. Use the sandbox Success, Failed and Timeout buttons. Enable sandbox webhook delivery on the key when testing callbacks.

For real payments, enter the live secret and turn off Test Mode. The customer approves the invoice amount plus the quoted fee on their phone. WHMCS records the principal after a confirmed live success.

Confirmations and recovery#

Keep the included hook and WHMCS cron running. Webhooks and status checks confirm payments even when the customer closes the browser. An uncertain retry reuses the saved request; it does not start a second charge.

For a payment marked for review, compare the exact NuePay reference with the invoice’s transactions and Billing → Gateway Log. Check both systems before recording any manual payment. The bundled installation guide covers interrupted posting and recovery.

Supported payments#

This release supports individual UGX invoices. Leave WHMCS currency conversion disabled. Payments start only when a customer selects NuePay and clicks Pay. Product expiry does not trigger a charge or prompt. The hook resolves existing payment attempts; it does not start scheduled payments or send reminders. Other gateways’ automatic billing stays under WHMCS configuration.

Recurring debits, automatic refunds, mass payments and an addon dashboard are outside this release. Back up before upgrading and replace all gateway and hook files together. Resolve pending payments before removing callbacks. Keep payment history after deactivation.