# Integrate NuePay API v1 Build against https://api.nuepay.net/v1. Read the linked contract and relevant guides before writing code. If behavior is unspecified, flag the gap instead of inventing an endpoint or parameter. ## Implementation rules - Call NuePay from your server with `Authorization: Bearer `. Keep credentials in environment variables; never embed them in browser code, prompts, logs or source control. - A named key identifies its application and merchant. Do not send an application nickname or account number for authentication. Up to ten applications share the merchant wallet; there are no separate application wallets or spending scopes. - Start with `np_test_` credentials and simulated funds. The same API base accepts test and live keys. Verify `/application` and the expected `mode` before testing. Only switch to real payments when explicitly authorized by the merchant. - Send UGX amounts as decimal strings, never binary floating-point calculations. Collections credit the requested principal; the payer covers the quoted total, rounded up to whole UGX. Disbursements require whole UGX amounts and debit principal plus fee. Get `/quotes` before displaying charges; quotes do not move or reserve funds. - Persist a UUID and the exact payment payload before calling `/collections` or `/disbursements`. Send that UUID in `Idempotency-Key`. After a timeout or retry, reuse both; never issue a fresh UUID to retry an uncertain payment. A changed payload with the same UUID returns `409`. - `202` means accepted. The payment is complete only when `status` is `success`. `process` includes pending or under-review payments; a timeout is not proof of failure. Read `/transactions/{reference}` and reconcile before fulfilling or retrying. - Handle non-2xx responses using `code`, `message` and `errors`. Log the HTTP `X-Request-Id` for investigation; `data.request_id` identifies the original payment UUID, not the current HTTP attempt. Honor rate limits and use bounded backoff. - Configure each application's HTTPS notification URL in API Keys. Webhook and API signing secrets are separate. Verify `X-NuePay-Signature` using HMAC-SHA256 over `timestamp + "." + raw_body`, compare in constant time, and reject timestamps more than five minutes from your synchronized clock. - After signature verification, match body `id` to `X-NuePay-Event-Id`, check `livemode`, durably deduplicate event IDs, and apply only newer payment `version` values. Save events before returning 2xx. Deliveries may repeat or arrive out of order; fulfil a real order only on a live success. ## Acceptance checks - Test collection and disbursement success, failure and timeout with the sandbox simulation endpoint. Sandbox never moves real funds; sandbox webhook delivery is opt-in. - Test identical retries, changed-payload conflicts and a network timeout after dispatch. Verify that neither charges nor fulfilment repeat. - Test invalid signatures, stale timestamps, duplicate/out-of-order webhooks, test/live isolation and insufficient wallet funds. - Store payment reference, application ID, merchant reference, idempotency UUID, status and version. Reconcile any unresolved payment before showing a final outcome. ## Read next - [Quickstart](https://docs.nuepay.net/quickstart/index.md) - [All endpoints](https://docs.nuepay.net/api/index.md) - [Retries and statuses](https://docs.nuepay.net/reliability/index.md) - [Webhook verification](https://docs.nuepay.net/webhooks/index.md) - [Going live](https://docs.nuepay.net/going-live/index.md) ## Source API v1. Behavior reviewed against platform commit `4133868d96070eef6352f9fe2a1d0278bcab38f6` on 2026-10-22. Docs index: https://docs.nuepay.net/llms.txt. Contract: https://docs.nuepay.net/openapi.json. --- # 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.