# WHMCS and billing modules

> Automate hosting sales with the ZoPanel modules for WHMCS, Blesta, HostBill and Paymenter: install, connect with an API token, set up products and SSO.

Source: https://zopanel.net/docs/whmcs  
Updated: 2026-10-07

ZoPanel includes ready-made modules for WHMCS, Blesta, HostBill and Paymenter. When a customer pays, the billing system creates the hosting account and its first website. Suspension, termination, upgrades, password changes and single sign-on into the panel then happen automatically. All of the modules use the [provisioning API](/docs/provisioning-api).

## Before you start

Every integration needs:

- a ZoPanel **Pro** license, because API tokens are part of Pro,
- a valid certificate on the panel. Set a panel domain under **Settings → General → Panel domain & SSL**,
- at least one package in **Packages** (or one pushed through the API),
- an API token with the permission **Provisioning only**.

### Create the API token

1. In ZoPanel, open **My account → API tokens** and click **Create token**.
2. Give it a name, for example `whmcs`.
3. Set **Permissions** to **Provisioning only (WHMCS, CMS)**.
4. In **Allowed from IPs**, enter the billing server's IP address.
5. Choose an expiry, confirm with your password (and 2FA code), and copy the `zpat_…` token. It is shown only once.

A provisioning token can only call `/api/v1`: packages, accounts, single sign-on and usage. It cannot reach server settings, files or the terminal. If you also restrict panel access under **Settings → General → Restrict panel access**, add the billing server's IP there as well.

## WHMCS

The module supports WHMCS 8.x and 9.x on PHP 8.1 or newer.

| Event in WHMCS | What happens in ZoPanel |
| --- | --- |
| Order paid | The account and its first website are created |
| Overdue | The account is suspended, and later terminated |
| Upgrade or downgrade | The package is changed |
| Password reset | The password is changed |
| Client area | **Login to ZoPanel** (single sign-on) and usage |
| Daily cron | Disk and bandwidth usage are updated |
| Server sync | Existing accounts are imported |

### Install the module

Copy the `modules/servers/zopanel` folder into your WHMCS installation at `modules/servers/zopanel`. Use the release archive `zopanel-whmcs-module.zip`, or the `integrations/whmcs` folder of the source.

### Add the server

In WHMCS, go to **System Settings → Servers → Add New Server**:

| Field | Value |
| --- | --- |
| Module | ZoPanel |
| Hostname | The panel's host name, for example `panel.example.com` |
| Port | `8888`, with **Secure** checked |
| Access Hash | The `zpat_…` token |
| Username | Leave empty |

Click **Test Connection**. The username field accepts `skip-tls-verify` to turn off certificate checks, but use it only to test a panel that has no valid certificate yet.

### Configure the product

Create a product under **System Settings → Products/Services**. In the **Module Settings** tab, choose the server group and set:

- **Package:** a ZoPanel package. The list is loaded from the server.
- **PHP version:** for the first website (8.4, 8.3, 8.2, 8.1, 7.4 or the server default).
- **Create website:** create the order's domain as the account's first website.

Choose **Automatically setup the product as soon as the first payment is received**.

### Usernames

ZoPanel usernames are 3–16 characters, lowercase letters and digits, starting with a letter. Names starting with `zp` are reserved. The module adapts the name WHMCS proposes and saves the final name back on the service. For example, `shop-demo.vn` becomes `shopdemovn`.

### Single sign-on

The **Login to ZoPanel** button asks ZoPanel for a one-time sign-in link and redirects the customer to it. The link works once, for 60 seconds. Single sign-on is for customer accounts only. Resellers sign in with their own password and second factor.

### Safe retries (idempotency)

Billing systems retry calls that time out. To make retries safe, the module sends an `Idempotency-Key` header with each account creation, built from the WHMCS service ID and the username (`whmcs-create-<service id>-<username>`). If WHMCS repeats the call within 24 hours, ZoPanel returns the first answer instead of creating the account again or failing with "username already exists".

### Troubleshooting

Every API call is written to **System Logs → Module Log**, with passwords and tokens masked.

| Error | Cause |
| --- | --- |
| `this API token is not allowed from your address` | Add the WHMCS IP to the token |
| `this token can only use the provisioning API` | Expected for other paths: the module only uses `/api/v1` |
| `unknown package` | The product points to a package that was renamed or deleted |
| `API tokens require a Pro license` | The ZoPanel server needs a Pro license |

If the account was created but the website was not (for example, the domain is already hosted elsewhere), the order still succeeds. WHMCS logs the reason in its activity log, and the customer can add the website in the panel.

## Blesta

The module supports Blesta 5.x (PHP 7.2+) and lives in `integrations/blesta`.

1. Copy `components/modules/zopanel` into Blesta at `components/modules/zopanel`.
2. Install it under **Settings → Modules → Available → ZoPanel**.
3. Add a server with the **Panel URL** (`https://panel.example.com:8888`) and the **API token**. Blesta checks the connection when you save, and stores the token encrypted.
4. Create a package with the module **ZoPanel**, then choose the **ZoPanel package** and the PHP version.

The **Control Panel** tab shows usage and a **Login to ZoPanel** button. The welcome email can use `{service.zopanel_username}`, `{service.zopanel_password}` and `{service.zopanel_domain}`.

## HostBill

The module lives in `integrations/hostbill` (PHP 7.2+).

1. Copy `includes/modules/Hosting/zopanel` into HostBill at `includes/modules/Hosting/zopanel`.
2. Go to **Settings → Apps → Add new App → ZoPanel**. Enter the **Hostname**, the token as **Password**, and **Port** `8888`, then click **Test Connection**.
3. Create a product with that app and choose the **Package** and the PHP version.

For single sign-on, link to the module's `login` action (`user/class.zopanel_controller.php`) from your client area template.

## Paymenter

The extension supports Paymenter 1.x (PHP 8.3+) and lives in `integrations/paymenter`.

1. Copy `extensions/Servers/ZoPanel` into Paymenter at `extensions/Servers/ZoPanel`. If Paymenter does not list it, run `composer dump-autoload`.
2. Go to **Admin → Servers → New** and choose **ZoPanel**. Enter the **Panel URL** and the **API token**. Paymenter stores the token encrypted.
3. Create a product with that server and pick the **ZoPanel package** and the PHP version. Customers enter their domain at checkout.

Customers sign in through **Open ZoPanel**. The welcome email includes the username, password and panel URL.

## Resellers with their own billing

A reseller can connect its own WHMCS, Blesta, HostBill or Paymenter with a provisioning token created on the reseller account. The billing system then sees only the reseller's packages and sells only to the reseller's customers, within the reseller's plan limits.