PUQ Mautic

PUQVPNCP WHMCS module

WHMCS module for automated provisioning and lifecycle management of VPN client accounts on the PUQVPNCP panel. Supports WireGuard, OpenVPN and IKEv2, per-client bandwidth limits, location-based server groups, traffic statistics and one-time self-service links.

Description

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

PUQVPNCP WHMCS module

The PUQVPNCP WHMCS module is a provisioning module that integrates WHMCS with PUQVPNCP panels, enabling service providers to offer multi-protocol VPN accounts (WireGuard, OpenVPN, IKEv2) to their customers. The module automates the full lifecycle of VPN client management through the PUQVPNCP REST API.

Main features

System requirements

Requirement Minimum
WHMCS 9.x or higher
PHP 8.2 or higher
PUQVPNCP panel current
ionCube Loader v13 or newer (v14, v15)

Screenshots

Client area — Home screen

Client area home screen 01-description-client-area.png

Client area — Traffic statistics

Traffic statistics 02-description-traffic-stats.png

Admin area — Product information

Admin area product information 03-description-admin-area.png

Changelog

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

v1.0 (2026)

Installation and Configuration Guide

Step-by-step instructions for installing, configuring and setting up the PUQVPNCP WHMCS module — panel preparation, WHMCS integration, server configuration, location routing and product configuration.

Installation and Configuration Guide

Setup guide — PUQVPNCP panel

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

Before you can connect WHMCS, you need a running PUQVPNCP panel, an API token that WHMCS will use for every operation, and at least one VPN network with the protocols you want to expose enabled. This page walks through both.

1. Panel reachability

2. Issue an API token

The module authenticates to the panel with a Bearer token issued from the admin's profile page.

Step 1 — Open Profile

Click your username in the top-right corner of the panel and select Profile.

Top-right user menu 26-puqvpncp-profile-menu.png

Step 2 — Open the API Tokens section

Scroll down to the API Tokens card. Click the green + button on the right to create a new token.

Profile — API Tokens section 27-puqvpncp-profile-tokens.png

Step 3 — Create the token

Fill in the modal:

Click Save.

Create API Token modal 28-puqvpncp-token-create.png

Step 4 — Copy the Bearer token

The next dialog shows the Bearer Token. Click Copy and store it somewhere safe — the token is shown only once and cannot be retrieved later. If you lose it, delete the token and generate a new one.

Bearer token shown once 29-puqvpncp-token-bearer.png

The token grants the user's effective permissions — the admin group used in the screenshot has full access. For tighter control, create a dedicated user/permission group on the panel and issue a token for that user instead.

You will paste this token into the Password field of the WHMCS server record — see Add server.

3. Create a VPN network

The module needs at least one VPN network on the panel. On the WHMCS product configuration page, every available network is listed as a tickable server → network pair.

Step 1 — Open the Networks list

In the top menu, open Networks → List of networks.

Networks menu 30-puqvpncp-networks-menu.png

The list shows every existing network with the status of WireGuard / OpenVPN / IKEv2, the IPv4 subnet, the upstream interface and the bandwidth caps.

Networks list 31-puqvpncp-networks-list.png

Step 2 — Add a network

Click the green + button in the top-right corner of the Networks page. Fill the Create form:

Click the green ✓ in the top-right to save. Protocols (WireGuard / OpenVPN / IKEv2) are configured after the network is created.

Create network 32-puqvpncp-network-create.png

Step 3 — Enable protocols on the network

After saving, you land on the network's Edit page with a row of tabs (Main / WireGuard / OpenVPN / IKEv2 / Port Forwarding / Routes / Firewall / Clients / Traffic Control / Traffic) and a Protocols card on the right.

Tick Enabled for every protocol you want to offer to customers via WHMCS. The WHMCS module reads this state from GET /api/v1/network/{name} — disabled protocols are hidden in the client area and shown greyed-out (with a tooltip) in the admin service tab.

Network — enable protocols 33-puqvpncp-network-edit-protocols.png

Open each protocol-specific tab (WireGuard, OpenVPN, IKEv2) to fine-tune ports, ciphers, MTU and other parameters as needed. Defaults are sensible for most deployments.

What's next

Installation and Configuration Guide

Add server (PUQVPNCP panel)

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

Add a PUQVPNCP panel to WHMCS

Navigate to System Settings → Servers → Add New Server.

Step 1 — General settings

Add server - general settings 04-add-server-1.png

Step 2 — Module settings

  1. Server Details section, Type dropdown: select puqVPNcp.
  2. Leave Username empty (not used).
  3. Paste the panel's API token into the Password field — this is what the module sends as Authorization: Bearer <token> for every API call.
  4. Click Test connection — it calls /api/v1/system/status, /api/v1/license and /api/v1/network and returns OK on success.

Add server - module settings 05-add-server-2.png

Important: The API token must have permissions to manage clients, query networks and read system status.

Step 3 — Assign to a server group

For multi-server deployments, add the server to a WHMCS server group. Products bound to that group will list networks from every reachable server in it on the VPN Networks tree of the product configuration page — pick which server → network pairs are allowed for that product.

Installation and Configuration Guide

Product configuration

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

Create the product

  1. Navigate to System Settings → Products/Services → Products/Services → Create a New Product.
  2. Product Type: Other. Give it a name (e.g. VPN — 100 Mbit/s).
  3. On the Module Settings tab, pick PUQ VPNcp as the module and assign a server (or a server group).

After saving, the module injects a PUQ VPNcp settings panel below the standard module fields. All settings are persisted as JSON in configoption24 of the product record.

Product configuration 06-product-configuration.png

License key

Paste your licence key into the License key field. The status row underneath shows the result of the most recent verification (success: <timestamp> or an error). The module re-checks the licence on every product page render and caches the result for the validity period encoded in the licence response.

Bandwidth

Bandwidth 07-product-config-bandwidth.png

The module applies these via PUT /api/v1/client/{name} right after creating the client. The POST /api/v1/client create call does not accept bandwidth fields — the limits are always pushed through the follow-up update.

If the bandwidth update fails, the freshly created client is rolled back with DELETE /api/v1/client/{name} so billing never starts charging for an uncapped VPN.

Client name

Client name 08-product-config-client-name.png

Available macros:

Base macros

Random macros

Date & time macros

If the generated name already exists in tblhosting.username, the module appends -1, -2, … until it finds a free one.

Client Area

Client Area — link to instruction 09-product-config-client-area.png

VPN Networks

VPN Networks 10-product-config-vpn-networks.png

On opening the product, the module contacts every enabled puqVPNcp server in the product's server group and calls GET /api/v1/network on each. The UI then shows a per-server tree — unreachable servers remain visible with their error so you can see exactly what went wrong. License-slot capacity (used / total) is displayed next to each reachable server.

Each checkbox is a server → network pair. Ticking the same network name on two different servers creates two independent pairs.

How a server and network are picked at deploy time

  1. The module reads all ticked pairs in the order they appear in the list (top to bottom).
  2. For each pair it checks (a) free licence slots on that server (count_accounts < count_accounts_available from GET /api/v1/system/status) and (b) at least one free IP on the network (GET /api/v1/network/{name}/available_ip).
  3. The first pair that passes both checks wins. The service is reassigned (tblhosting.server is updated) to the selected server, and the client is created on the selected network via POST /api/v1/client.
  4. If nothing is ticked, network_name is omitted from the create call and the panel of the server WHMCS already picked decides automatically.
  5. If ticks exist but none is deployable (every chosen server is out of slots or every chosen network is full), provisioning fails — nothing is silently created on a wrong network.

Because order matters, put your preferred pairs at the top.

If the whole group is unreachable a red banner appears at the top of the section; previously saved ticks are preserved through hidden inputs so your configuration is not lost when you re-save the product.

Metric Billing (optional)

Metric Billing toggles 11-product-config-metric-billing.png

The module ships a WHMCS Usage Billing provider with two metrics:

Enable the metrics on the product's Pricing tab to charge customers per GB of traffic. The provider pulls daily totals directly from the panel via GET /api/v1/client/{name}/traffic/{Y}/{m} and reports them in gigabytes for the current calendar month. No local accumulation table is used — values come live from the panel each time WHMCS runs the usage-billing cron.

Client area

What your customers see after ordering a PUQVPNCP-backed service in WHMCS: the home screen with VPN client details and protocol configs, the traffic statistics page, and email notifications.

Client area

Home screen

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

The product details page is the Information tab — the module's main client-facing view. Everything on it is loaded dynamically from the PUQVPNCP panel via AJAX the moment the page opens.

Client area — home screen 12-home-screen-connection.png

Sidebar

The module replaces the default Information sidebar entry with two of its own:

Sidebar entries 13-home-screen-sidebar.png

User manual

Connection status

A live block at the top of the page that polls /api/v1/client/online every 5 seconds (paused while the browser tab is hidden) and shows one card per protocol the client is currently connected on:

Each card shows: VPN IP, network, endpoint, last handshake (with relative time suffix) and downloaded/uploaded bytes (humanised B/KB/MB/GB). The header pill is Online (green) when at least one protocol reports a session, Offline (red) otherwise.

A manual Refresh button next to the badge forces an immediate fetch.

A button that calls POST /api/v1/client/{name}/otl and displays a single-use self-service URL the customer can open once to configure their device without re-entering credentials.

One-Time Link generated 14-home-screen-otl.png

VPN Client

Static card with the panel's authoritative client record:

VPN Client info 15-home-screen-vpn-client.png

A status pill in the top-right reads Enabled (green) when the panel reports status:enable, Disabled (red) otherwise.

WireGuard

Shown when WireGuard is enabled on the client's network:

WireGuard config + QR 16-home-screen-wireguard.png

OpenVPN

Shown when OpenVPN is enabled on the client's network:

OpenVPN profile 17-home-screen-openvpn.png

The full .ovpn profile text with Copy Config and Download buttons.

IKEv2

Shown when IKEv2 is enabled on the client's network:

IKEv2 profile 18-home-screen-ikev2.png

The IKEv2 profile (JSON) with a Download button.

Traffic statistics

The Traffic statistics entry in the sidebar opens a separate page — see Traffic statistics.

Client area

Email notification

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

The module relies on the standard WHMCS Product Welcome Email — it does not send any emails of its own. See Email template for a suggested body and the available variables.

Client area

Traffic statistics

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

A dedicated page in the client area showing monthly traffic for the VPN client. Entered from the service sidebar via Traffic statistics (action_m=traffic_statistics).

Traffic statistics — chart and totals 19-traffic-statistics.png

Controls

Chart

A line chart rendered with Chart.js showing per-day:

All values are formatted with a human-readable B / KB / MB / GB / TB scale on hover and on the Y axis.

Totals

Two cards below the chart show the aggregated total download (blue) and total upload (green) for the selected month.

Data source

The page calls GET /api/v1/client/{name}/traffic/{year}/{month} on the PUQVPNCP panel every time Load is pressed. The module does not cache samples — values come live from the panel each render.

Admin area

What the module exposes to WHMCS administrators: the service admin tab, the license alert on the homepage, and the product settings panel.

Admin area

Product information (admin service tab)

PUQVPNCP module WHMCS

Order now | Download | COMMUNITY | PUQVPNCP

Open Clients → View/Search Clients → (client) → Products/Services → (service). The module adds a set of fields to the standard admin service tab — all populated live from the PUQVPNCP panel via AJAX.

Admin area — product information 20-product-information.png

License Verification

Shown only when the product's licence check fails — a red errorbox with the verification error. Fix the licence on the product configuration page and re-open the service.

Connection status

Connection status + VPN Client 21-product-info-status-client.png

A live block at the top that polls GET /api/v1/client/online every 5 seconds and shows one row per protocol the client is currently connected on.

The header pill is Online (green) when at least one protocol reports a session, Offline (red) otherwise. Last checked timestamp updates after every poll.

Each protocol row exposes the raw fields the panel returns (network, IP, endpoint, last handshake, transferred bytes), formatted for readability — bytes are humanised, the latest handshake gets a relative-time chip.

VPN Client

A table populated from GET /api/v1/client/{name} with the panel's authoritative client record:

Function buttons

Three buttons that fetch and inline-display the protocol configuration for the client. Buttons for protocols disabled on the network are greyed-out, marked cursor:not-allowed, and carry a tooltip explaining why they cannot be opened.

View WireGuard

WireGuard view in admin 22-product-info-wireguard.png

Calls GET /api/v1/client/{name}/config/text and /config/qr. Shows the .conf text alongside the QR code (the layout collapses to full-width text when no QR is returned). Copy and Download buttons act on the visible config; × closes the panel.

View OpenVPN

OpenVPN view in admin 23-product-info-openvpn.png

Calls GET /api/v1/client/{name}/openvpn/profile and shows the full .ovpn file. The block uses 100 % width because no QR is rendered.

View IKEv2

IKEv2 view in admin 24-product-info-ikev2.png

Calls GET /api/v1/client/{name}/ikev2/profile and shows the IKEv2 profile (JSON). Long base64 certificate strings wrap inside the box and never expand it horizontally.

Bandwidth

Bandwidth + Metric Statistics 25-product-info-bandwidth.png

Read-only summary of the per-client caps configured on the product: Download and Upload in Mbit/s, or Unlimited when the value is 0. To change them, edit the product's Bandwidth fields on the Module Settings tab.

Metric Statistics

WHMCS-rendered block (not part of the module's tab fields, shown when the product has Usage Billing metrics enabled). Lists the metric, its enabled state, current usage and last update time. Values come from the module's metric provider, which fetches monthly traffic totals from the panel via GET /api/v1/client/{name}/traffic/{Y}/{m} and reports them in gigabytes.

Click Refresh Now to re-poll the panel immediately.