# WHMCS gateway

Install NuePay for mobile money hosting invoice payments.

Canonical page: https://docs.nuepay.net/whmcs/

Accept mobile money for hosting invoices with the NuePay 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.
- USD or 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](https://platform.nuepay.net/integration/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.

| WHMCS setting | Value |
| --- | --- |
| API Secret | The application’s test or live secret |
| Webhook Signing Secret | Its separate `whsec_` signing secret |
| Test Mode | On for `np_test_`; off for `np_live_` |

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

## Set your exchange rate

With gateway version **1.1.0** or later, keep hosting prices and invoices in USD while collecting UGX. In the NuePay gateway settings in WHMCS, enter your chosen **USD to UGX Rate**: the number of shillings for USD 1, with up to four decimal places. Each hosting business controls its own rate; it is never fetched or updated automatically.

Leave **Convert To For Processing** disabled. The gateway uses its own manual rate and leaves WHMCS currency rates unchanged. UGX invoices do not require a USD rate.

Checkout shows the original invoice amount, rate, converted UGX amount and fee. Conversion rounds to the nearest whole shilling. A started payment keeps its saved amounts and rate through retries and confirmation; if the rate changes before Pay, the customer must refresh the quote. WHMCS credits the original USD or UGX balance after confirmed success, while NuePay receives UGX. The Gateway Log records both amounts and the rate.

## Test, then go live

Start in Test Mode. Open an unpaid USD or 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.

> **Sandbox never pays real invoices**
> 
> Test success moves no real money, leaves invoices unpaid and does not provision hosting.

For real payments, enter the live secret and turn off Test Mode. The customer approves the UGX total, including the quoted fee, on their phone. WHMCS records the original invoice balance after 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 USD and UGX invoices. 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.