Billing modules

Connect WHMCS, Blesta, Paymenter, HostBill, ClientExec, Upmind or BillingServ to VMStack, and what each integration supports.

VMStack has an integration for seven billing systems. Each one creates the customer's panel account and server when an order is paid, suspends, unsuspends and terminates it with the billing system, upgrades it when the package changes, and gives the customer a client area and single sign-on into the panel. All of them talk to the panel's public API with one API key. They share the same core, so settings and error messages are worded alike.

All modules are new. The WHMCS module is the most complete; the others have been built and unit-tested against each system's documented module interface but, as their READMEs say, have not yet run against every real installation. Report problems through contact.

What each module supports#

WHMCS Blesta Paymenter HostBill ClientExec Upmind BillingServ
Module version 0.1.3 0.1.0 0.1.0 0.1.0 0.1.0 0.1.0 0.1.0
Kind server module module server extension hosting module server plugin provision provider separate connector app
PHP 8.1+ 8.1+ 8.3+ 8.1+ 8.1+ 8.1 to 8.3 8.1+
Test connection yes yes, on save yes yes yes no test command
Create, suspend, unsuspend, terminate yes yes yes yes yes yes yes
Upgrade to a larger plan yes yes yes yes yes yes (resize) yes
Root password change yes client tab, admin tab client tab yes yes yes portal, CLI
Customer sets up the server yes yes yes yes yes yes yes
One-click application option yes yes yes yes yes no yes
Placement by location, node group or node yes yes yes yes yes yes yes
Extra IPv4 yes yes yes yes yes no yes
Extra IPv6, disks, snapshots, traffic, port forwards yes no no yes no no yes (config)
Client area: power, console, rescue, reinstall yes yes yes yes yes yes (no rDNS) portal
Client area: reverse DNS yes yes yes yes yes no portal
Client area: port forwards (NAT) yes no no yes no no portal
Single sign-on into the panel yes yes yes yes yes yes portal
Plan switches enforced on client-area actions yes no no yes no no yes
Admin view services tab admin tab with actions none account page, import admin actions, admin sign-in none CLI
Usage billing bandwidth, disk, Metric Billing no no metered billing no no meter events
Email change sent to the panel yes no yes no no no yes

"Plan switches enforced" means the module sends client-area actions with X-On-Behalf-Of: customer, so the panel applies the plan's customer permissions and reinstall limits. The other modules act with the key's own rights: what the plan switches off is still refused in the panel itself, but not in that module's client area.

Common to all modules:

  • Server sizes come from panel plans; there are no CPU, memory or disk sliders.
  • The panel only upgrades: a package change to a smaller plan is refused with the panel's sentence ("The panel only upgrades: …").
  • Lowering an add-on never deletes disks, snapshots or forwards; only extra addresses are removed (the newest first, never the main address).
  • No single sign-on for billing staff into the panel as an administrator.

API key for a billing system#

Every module needs a panel API key of an administrator or a reseller. A user's key is refused.

  1. Sign in to the panel as the account the billing system should act as. A reseller's key creates customers under that reseller and is held to its pool; an administrator's key can place customers under any reseller or none.
  2. Go to Settings › API keys and create a key.
  3. Choose the preset Billing system. It ticks every servers:, users:, backups:, snapshots:, disks: and webhooks: scope plus usage:read, catalog:read, tasks:read and firewall:read, as far as the account's level is offered them.
  4. For an administrator's key that should list node groups and nodes for placement, also tick infrastructure:read.
  5. Under allowed addresses, enter the billing server's public address (required for administrator keys while System › Settings › API asks for it, which is the default).
  6. Set the expiry to never, unless you will rotate the key yourself.
  7. Copy the key (vmk_…). It is shown once.

The scopes the modules check when testing the connection:

Scope Needed for
servers:read, servers:create, servers:delete, servers:power, servers:manage, servers:provision the server's life cycle and the client area
users:read, users:write finding and creating the customer's panel account
users:login single sign-on and console links
usage:read traffic and usage billing
catalog:read plans, locations and images in the product settings
tasks:read waiting for creates and deletes
servers:secrets (optional) "Send welcome password" and showing the rescue password
infrastructure:read (optional, administrators) node groups and nodes under Placement
disks:write (optional) the extra disk made at create (WHMCS, HostBill, BillingServ)

Warning: users:login lets the key open a full panel session of any account it manages. Give it only to a billing system you trust, and always set allowed addresses on the key.

See API keys for the key form itself.

How accounts and servers are matched#

All modules use the same rules:

  1. The billing client is looked up by external_id (the billing system's client ID) among the accounts under the parent (the reseller of the key, or the configured reseller, or none).
  2. Else by exact email under the same parent. An unlinked account found this way is linked. An account that belongs to another client, or is an administrator or reseller, is refused.
  3. Else a new user account is created. Its panel password is not kept; the customer reaches the panel by single sign-on.

A server carries the billing service's ID as its external_id. A create that is run again finds the existing server and finishes what was left; it never makes a second server. Before any action the module checks that the server's owner is this client's account.

Pages#

Problems: Troubleshooting billing and accounts.

  1. WHMCSInstall the VMStack provisioning module in WHMCS, connect it to the panel, set up products, configurable options, add-ons, usage billing and the client area.
  2. BlestaInstall the VMStack module in Blesta, add the panel, set up packages and configurable options, and what the client and admin Server tabs offer.
  3. PaymenterInstall the VMStack server extension in Paymenter, connect it to the panel, set up products and checkout fields, and what the client area offers.
  4. HostBillInstall the VMStack hosting module in HostBill, connect an App, set up products, form fields and add-ons, client functions and metered billing.
  5. ClientExecInstall the VMStack server plugin in ClientExec, connect it to the panel, set up products and add-ons, and what clients and staff can do.
  6. UpmindThe VMStack provider for Upmind's servers provision category: configuration, product values, supported functions and limitations.
  7. BillingServRun the VMStack connector for BillingServ: hosting, configuration, the webhook, the worker and usage cron, the customer portal and the command line.