Mikrotik VPN WHMCS module

Description

Changelog

Installation and Configuration Guide

Step-by-step instructions for installing, configuring, and setting up the Mikrotik VPN WHMCS module, including Mikrotik router preparation (RouterOS certificates, HTTPS and API-SSL, VPN server), WHMCS integration, email templates, server registration, and product configuration.

WHMCS setup (install/update)

Mikrotik VPN module WHMCS
Order now | Download | FAQ
System requirements

Requirement
Minimum version

PHP
8.2 or higher

WHMCS
9.x or higher

Mikrotik RouterOS
7.x or higher

ionCube Loader
v13 or newer (v14, v15)

Note: The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server.

Download
The module can be ordered and downloaded from PUQ Cloud:

Order / Download: https://panel.puqcloud.com/index.php?rp=/store/whmcs-module-mikrotik-vpn

FAQ: https://faq.puqcloud.com/

Direct download link for the latest version:

wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php82/PUQ_WHMCS-Mikrotik-VPN-latest.zip

Older module versions for WHMCS 8 are available in PHP-specific directories:

PHP 7.4: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php74/

PHP 8.1: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php81/

After downloading, extract the archive:
unzip PUQ_WHMCS-Mikrotik-VPN-latest.zip

Installation
Step 1: Upload files
Extract the module archive and copy the puqMikrotikVPN directory to the WHMCS servers module directory:
WHMCS_WEB_DIR/modules/servers/puqMikrotikVPN

Step 2: Add server
Navigate to System Settings → Servers → Add New Server:

Enter the correct Name and Hostname

In Assigned IP Addresses, enter the list of IPs to distribute to users
In Server Details, select the PUQ Mikrotik VPN module
Enter valid Mikrotik router credentials (username and password)
Click Test connection to verify

Step 3: Create product
Navigate to System Settings → Products/Services → Create a New Product:

Select the PUQ Mikrotik VPN module in the Module settings section
Configure the product parameters

Update
Step 1: Backup
Before updating, it is recommended to back up:

WHMCS database
Module files in modules/servers/puqMikrotikVPN/

Step 2: Upload new files
Download and extract the new version, then overwrite all files in:
WHMCS_WEB_DIR/modules/servers/puqMikrotikVPN/

Step 3: Verification

Log in to the WHMCS admin panel
Check the module is functioning correctly
Verify product settings

Important (v3.0): Product reconfiguration is required after updating to version 3.0. The traffic package model has been replaced with post-paid billing via WHMCS metrics.

Setup guide: Mikrotik preparation and configuration

Mikrotik VPN module WHMCS
Order now | Download | FAQ
This guide covers the preparation of a Mikrotik router for use with the PUQ Mikrotik VPN WHMCS module: root CA certificate, Webfig certificate, HTTPS, API-SSL and VPN server activation.

Note: Enter the following commands one by one and wait for each command to complete before running the next.

1. Check RouterOS version
Ensure RouterOS version is 7.x or higher:
system/package/print

2. Create a root CA on the router
Enable HTTPS by creating your own local root Certificate Authority:
/certificate
add name=LocalCA common-name=LocalCA key-usage=key-cert-sign,crl-sign

3. Sign the root CA certificate
/certificate
sign LocalCA

4. Create a non-root certificate for Webfig

Replace XXX.XXX.XXX.XXX with your router's public IP address (or the hostname you use to reach it).

/certificate
add name=Webfig common-name=XXX.XXX.XXX.XXX

5. Sign the Webfig certificate with the local CA
/certificate
sign Webfig ca=LocalCA

6. Enable HTTPS (www-ssl) with the Webfig certificate
/ip service
set www-ssl certificate=Webfig disabled=no

7. Enable API-SSL with the Webfig certificate
The PUQ Mikrotik VPN module communicates with the router through the API-SSL service:
/ip service
set api-ssl certificate=Webfig disabled=no

Important: The module uses the Mikrotik API only. Make sure the API-SSL port is reachable from the WHMCS server.

8. Enable VPN server
Enable the VPN protocol(s) you plan to offer to clients (PPTP, L2TP, etc.) and configure the corresponding PPP profile, service and IP pool. The PPP profile name configured here will later be selected in the product settings on the WHMCS side.

16-mikrotik-setup.png

9. Firewall, NAT and routing
Configure NAT, firewall and routing on the Mikrotik router so that VPN clients can reach the Internet and any internal resources you want to expose. The module itself only provisions the user account (PPP secret) — the surrounding network configuration is the responsibility of the router administrator.

Important: The module registers opposite values for upload and download speeds in the Mikrotik router compared to the WHMCS product settings, because Mikrotik measures incoming traffic while VPN clients experience outgoing traffic.

Setup guide: WHMCS setup

Mikrotik VPN module WHMCS
Order now | Download | FAQ
System requirements

Requirement
Minimum version

PHP
8.2 or higher

WHMCS
9.x or higher

Mikrotik RouterOS
7.x or higher

ionCube Loader
v13 or newer (v14, v15)

Note: The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server.

Older module versions for WHMCS 8 are available in PHP-specific directories:

PHP 7.4: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php74/

PHP 8.1: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php81/

Step 1: Download the module
wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Mikrotik-VPN/php82/PUQ_WHMCS-Mikrotik-VPN-latest.zip

Step 2: Extract the archive
unzip PUQ_WHMCS-Mikrotik-VPN-latest.zip

Step 3: Copy module files
Copy the puqMikrotikVPN directory to:
WHMCS_WEB_DIR/modules/servers/

Step 4: Add server in WHMCS
Navigate to System Settings → Servers → Add New Server

Enter the correct Name and Hostname

In Assigned IP Addresses, enter the list of IPs that will be distributed to users
In the Server Details section, select the PUQ Mikrotik VPN module
Enter valid Mikrotik router credentials (username and password)
Click Test connection to verify the connection

04-add-server-1.png

05-add-server-2.png

Step 5: Create product in WHMCS
Navigate to System Settings → Products/Services → Create a New Product
Select the PUQ Mikrotik VPN module in the Module settings section.

06-whmcs-setup.png

Email Template (puqMikrotikVPN notification traffic limit)

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Creating the email template
Navigate to System Settings → Email Templates → Create New Email Template
This template is used to notify the customer when the remaining traffic falls below the threshold configured in the product settings ("Notification traffic remainder less than X GB").

Template configuration

Parameter
Value

Email Type
Product/service

Unique Name
puqMikrotikVPN notification traffic limit

Email subject
Traffic less than {$notification_traffic_remainder} GB - {$username}

Email body
Dear {$client_name},

This letter informs you that the traffic limit of the service is coming to an end.

Product/Service: {$service_product_name}
Due Date: {$service_next_due_date}

Username: {$username}
Left traffic: {$traffic_balance_gb} GB
After renewing the service, {$traffic_billingcycle_gb} GB will be automatically added.

{$signature}

Available template variables
The following custom variables are passed to the email template by the module:

Variable
Description
Example

{$username}
VPN account username
mikrotik-user-42

{$notification_traffic_remainder}
Traffic threshold configured in product settings (GB)
5

{$traffic_balance_gb}
Remaining traffic balance for the customer (GB)
4.2

{$traffic_billingcycle_gb}
Traffic that will be added on the next billing cycle (GB)
100

In addition, all standard WHMCS product/service merge fields are available (e.g. {$client_name}, {$service_product_name}, {$service_next_due_date}, {$signature}).

Note: Notifications are sent automatically during the WHMCS cron execution when remaining traffic falls below the threshold configured in the product settings.

Screenshots

07-email-template-1.png

08-email-template-2.png

Email Template (puqMikrotikVPN Suspension Notification traffic limit)

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Creating the email template
Navigate to System Settings → Email Templates → Create New Email Template
This template is used to notify the customer that the VPN account has been suspended on the Mikrotik router because the traffic balance reached zero or below. The traffic limit will be restored on the next billing cycle.

Template configuration

Parameter
Value

Email Type
Product/service

Unique Name
puqMikrotikVPN Suspension Notification traffic limit

Email subject
Suspension Information - {$username}

Email body
Dear {$client_name},

This letter informs you that the VPN account has been suspended due to traffic exhaustion.
The traffic limit will be restored from the next service cycle.
It is also possible to switch to a package with a large amount of traffic.

Product/Service: {$service_product_name}
Due Date: {$service_next_due_date}

Username: {$username}
Left traffic: {$traffic_balance_gb} GB
After renewing the service, {$traffic_billingcycle_gb} GB will be automatically added.

{$signature}

Available template variables
The same custom variables as in the traffic-limit notification template are available:

Variable
Description

{$username}
VPN account username

{$traffic_balance_gb}
Remaining traffic balance (GB) — normally zero or below when this template is sent

{$traffic_billingcycle_gb}
Traffic that will be added on the next billing cycle (GB)

Plus all standard WHMCS product/service merge fields ({$client_name}, {$service_product_name}, {$service_next_due_date}, {$signature}).

Note: This email is sent automatically by the module when the VPN account is auto-suspended on the Mikrotik router because the customer's traffic balance has been exhausted.

Add server (Mikrotik router)

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Adding a Mikrotik router to WHMCS
Configure a Mikrotik router as a server within WHMCS using the PUQ Mikrotik VPN module.
Navigate to System Settings → Servers → Add New Server

Step 1: General settings
Enter the correct Name and Hostname for your Mikrotik router.

Name — an internal identification for the server (e.g. "My great Mikrotik router")

Hostname — a resolvable domain pointing to the router's IP address (e.g. vpn.mydomain.com)

If your Mikrotik API-SSL service listens on a non-standard port, enter it in the Port field. Check the Secure checkbox (the module talks to the router through API-SSL).

04-add-server-1.png

Step 2: Assigned IP addresses
In the Assigned IP Addresses field, enter the list of IP addresses that will be distributed to users. These IPs are consumed sequentially as new VPN accounts are provisioned. Both private and public IP addresses are supported.

Step 3: Module settings

In the Server Details section, select the PUQ Mikrotik VPN module from the dropdown
Enter valid Mikrotik router credentials:

Username — Mikrotik user with API access (typically with the full group or custom group that includes api, write, read, policy)

Password — the corresponding password

Click Test connection to verify the connection is working correctly

The test connection verifies that the module can reach the Mikrotik API-SSL service and authenticate with the provided credentials.

05-add-server-2.png

Important: The Mikrotik user must have sufficient privileges to create and manage PPP secrets, read traffic counters and reset them. The module uses the Mikrotik API only — SSH access is not used.

Product Configuration

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Add new product to WHMCS
Navigate to System Settings → Products/Services → Create a New Product
Select the PUQ Mikrotik VPN module in the Module settings section.

Configuration parameters

Parameter
Description

License key
A pre-purchased license key for the PUQ Mikrotik VPN module. The license must be active for correct operation. After saving, the verification status is displayed below the field.

Comment PREFIX
Prefix applied to the VPN user comments on the Mikrotik router. Helps identify which PPP secrets belong to WHMCS-managed accounts.

Profile
PPP secret profile on the Mikrotik router. The dropdown is populated with the profiles configured on the selected server.

Service
Available VPN service on the Mikrotik router (e.g. any, pptp, l2tp, pppoe, etc.).

Bandwidth Download
Download speed limit in M/s applied to the VPN account.

Bandwidth Upload
Upload speed limit in M/s applied to the VPN account.

Traffic (One Time / Monthly / Quarterly / Semi-Annual / Annual / Biennial / Triennial)
Packet of traffic added per billing cycle (in GB). Values match the WHMCS billing cycle of the product.

Save traffic history (days)
Number of days to retain daily traffic usage statistics. Older records are deleted automatically during cron execution.

User notification traffic limit email template
Email template sent when remaining traffic falls below the threshold configured in the next field. Select a Product/service email template (created manually in WHMCS).

Notification traffic remainder less than X GB
Traffic threshold (in GB) that triggers the notification email.

Suspend exceeding traffic limit email template
Email template sent when the traffic balance reaches zero or below and the VPN account is automatically suspended on the router.

Link to instruction
Optional URL to a client-facing setup manual. Displayed as a button in the client area. Leave empty to hide the button.

Support PPtP
Toggles the display of PPtP connection details (server address, credentials) in the client area.

Support L2TP
Toggles the display of L2TP connection details in the client area.

L2TP IPSec PSK key
The IPSec pre-shared key for L2TP; displayed in the client area when L2TP support is enabled.

Statistics collection frequency
The frequency at which traffic usage statistics are collected by the WHMCS cron. Also checks the traffic balance and disables the VPN account on the Mikrotik router when the balance is exhausted.

Important notes

Warning: This module works only as a server module (Products/Services). It cannot be used as an add-on product. Attempting to use it with add-on products will result in an error message.

Post-paid traffic billing (v3.0+): The module no longer exposes its own traffic package selector. Traffic consumption is reported back to WHMCS using standard metrics, so you can build any post-paid traffic pricing model directly in the WHMCS product configuration.

Opposite upload/download values on Mikrotik: the module intentionally registers opposite values on the router compared to the WHMCS settings, because Mikrotik measures incoming traffic while VPN clients experience outgoing traffic.

Screenshots

09-product-configuration.png

17-product-configuration-2.png

Client Area

Overview of the client-facing features available in the Mikrotik VPN WHMCS module, including the home screen (VPN server address, protocols, credentials, connection status, bandwidth limit), email notifications (traffic limit, suspension) and traffic usage statistics.

Home screen

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Client area home screen
After authenticating to the client panel, the end customer sees the VPN service management page with the following sections:
Service information

User manual — a button linking to the instruction URL (displayed only if configured by the administrator in product settings, "Link to instruction" field)

VPN server address — the hostname or IP address the customer should connect to

VPN protocols — information about which protocols (PPtP, L2TP) are available for this product, based on the "Support PPtP" / "Support L2TP" product settings

L2TP IPSec PSK key — displayed when L2TP support is enabled

Username — the VPN username with a copy-to-clipboard button

Password — the VPN password with a copy-to-clipboard button

Connection status — real-time indicator of whether the VPN account is currently connected on the router

Bandwidth limit — displays the configured download / upload speed limits

Traffic information

Remaining traffic balance — the current traffic balance for the customer

Traffic that will be added on the next billing cycle

Sidebar navigation
The client area sidebar contains two menu items:

Information — the main service details page (described above)

Traffic statistics — historical traffic usage charts (see Traffic statistics page)

Note: If the service status is not Active or if the VPN account cannot be found on the Mikrotik router, an error page is displayed instead.

Screenshot

10-home-screen.png

Email notification

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Email notification examples
The module sends two types of automatic email notifications based on the customer's traffic balance and the templates configured in the product settings.

1. Traffic limit about to be exhausted
Sent automatically when the remaining traffic balance falls below the threshold configured in the product settings ("Notification traffic remainder less than X GB"). Uses the template selected in "User notification traffic limit email template".

11-email-notification-1.png

2. Suspension notification (traffic exhausted)
Sent automatically when the traffic balance reaches zero or below and the module suspends the VPN account on the Mikrotik router. Uses the template selected in "Suspend exceeding traffic limit email template".

12-email-notification-2.png

Note: Both templates must be created manually in WHMCS before they can be selected in the product settings. See the Email Template pages in the Installation and Configuration chapter.

Traffic statistics

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Traffic usage statistics
The client can view traffic usage statistics in the sidebar menu item "Traffic statistics".
The statistics page shows the customer's traffic on a daily basis, broken down into incoming and outgoing traffic. Both charts are powered by Google Charts and automatically resize to fit the browser window. The raw data is collected by the WHMCS cron job and stored in the database for the number of days configured in the product settings ("Save traffic history (days)" parameter).

Note: Statistics data is only available after the WHMCS cron has run at least once with the UsageUpdate function. After each collection, traffic counters on the Mikrotik router are reset to zero to guarantee accurate accounting for the next interval.

Screenshots

13-traffic-statistics-1.png

14-traffic-statistics-2.png

Admin Area

Administrative features and tools available in the WHMCS admin panel for managing Mikrotik VPN services.

Product Information

Mikrotik VPN module WHMCS
Order now | Download | FAQ
Admin area product information
The administrator can view detailed service information in the WHMCS admin panel on the product/service page. The module adds a custom panel in the Module Data section with the following information:
License verification status
Displays the current license status with a colored indicator:

Green — license is valid and active

Red — license is invalid, expired, or missing

API connection status
Shows the result of a real-time connection test to the Mikrotik router API-SSL, confirming that the credentials entered for the server are working correctly.
VPN account information

Field
Description

Username
The VPN account username (PPP secret name) on the Mikrotik router

Enabled
Whether the VPN account is currently enabled or disabled on the router

Profile
The PPP profile assigned to the account

Service
The VPN service / protocol (e.g. any, pptp, l2tp, pppoe)

IP address
The IP address assigned to the account from the server's IP pool

Comment
Includes the configured Comment PREFIX and WHMCS service identifier

Traffic information

Bandwidth limits — configured download / upload speed limits

Traffic balance — current remaining traffic balance for the customer

Traffic that will be added on the next billing cycle

Connection status — shows whether the client is currently online

Available management actions
The standard WHMCS module command buttons are available:

Create — provision a new VPN account on the Mikrotik router

Suspend — disable the VPN account

Unsuspend — re-enable the VPN account

Terminate — permanently delete the VPN account from the router

Change Password — reset the account's password

Change Package — update profile, service, bandwidth limits and traffic configuration (used during upgrades/downgrades)

Reset Connection — force-disconnect the current VPN session (useful when the customer needs to re-establish the tunnel)

Screenshot

15-product-information.png