VulCode

WHMCS modules for Proxmox, Pterodactyl and custom panels

WHMCS handles clients, invoices and due dates. A provisioning module makes a VPS or game server appear on its own once the order is paid, and get suspended when payment is overdue. We write such modules and hooks, and when WHMCS stops being enough, we talk about our Flaem panel.

Hosting companies
The vcproxmox module in the integration panel: module functions with the moment WHMCS runs them, Proxmox VE calls, products with their configoption settings and safeguards

How a provisioning module works

A module is a PHP file in /modules/servers/ with functions WHMCS calls at set points in a service's life.

When WHMCS runs the function

  • A paid order

    Or staff creating the service.

  • An overdue invoice

    The WHMCS cron job when payment is overdue.

  • The overdue invoice paid

    The client pays the overdue invoice.

  • Long overdue

    The cron job, when removal is enabled.

Module function in /modules/servers/

  • CreateAccount

    Creates the service in the panel or hypervisor. A product passes settings configoption1 to configoption24 to the module, e.g. node and template.

    After: A paid order

  • SuspendAccount

    Suspends the service in the panel or hypervisor.

    After: An overdue invoice

  • UnsuspendAccount

    Brings the suspended service back.

    After: The overdue invoice paid

  • TerminateAccount

    Removes the service from the panel or hypervisor.

    After: Long overdue

What WHMCS sets after success

  • Active and a welcome email

    The client gets an email with the service details.

    After: CreateAccount

  • Suspended

    WHMCS sets the status, not the module.

    After: SuspendAccount

  • Active

    The service is running again.

    After: UnsuspendAccount

  • Terminated

    The service ends in WHMCS.

    After: TerminateAccount

CreateAccount for Proxmox

One CreateAccount call in the module log: the parameters from WHMCS, the request to Proxmox VE and what goes back to WHMCS. The token secret never reaches the log.

The vcproxmox module log: a CreateAccount entry with the parameters from WHMCS, the template clone in Proxmox VE, the UPID task id and the completion job

  1. Node and template from the product

    Node and template come from product settings. The VMID derives from the service id, so a retry cannot create a second VM.

  2. The secret stays out of the log

    An entry in the Module Log, with the token secret scrubbed out. The Proxmox API token: user and token id in the server username field, the secret in the password field.

  3. success, the rest in the background

    The task id waits for completion: configuration, password and VM start.

Proxmox and Pterodactyl from the module side

The two most common WHMCS module targets at hosting companies.

CreateAccount

The client paid the order and the service has to appear on its own.

Proxmox VE
VPS and LXC containers
  1. POST .../qemu/{vmid}/clone clones the VM template
  2. Proxmox returns a UPID task id and the clone runs in the background
  3. A completion job waits for it to end, then configuration and start
Pterodactyl
game servers
  1. POST /api/application/servers with the order's external_id
  2. The server is in the panel at once
  3. Wings does the install per the egg
Takeaway: a different call in each panel

With Proxmox the module needs a job that finishes the work after the clone. With Pterodactyl one call is enough.

A retry after a failure

The same function runs a second time, e.g. after a dropped connection.

Proxmox VE
VPS and LXC containers
  1. The VMID derives from the service id
  2. The retried clone gets the same VMID
  3. A second VM cannot appear
Pterodactyl
game servers
  1. The external_id field ties the server to the order
  2. The retry first looks the server up by external_id
  3. The existing server comes back instead of a second one
Takeaway: a different call in each panel

Duplicate protection comes from a fixed VMID in Proxmox and from the external_id field in Pterodactyl.

SuspendAccount and UnsuspendAccount

The invoice is overdue, then the client pays it.

Proxmox VE
VPS and LXC containers
  1. The WHMCS cron job calls SuspendAccount when overdue
  2. POST .../status/stop or suspend
  3. After payment POST .../status/start
Pterodactyl
game servers
  1. The WHMCS cron job calls SuspendAccount when overdue
  2. POST /servers/{id}/suspend
  3. After payment POST /servers/{id}/unsuspend
Takeaway: a different call in each panel

In Proxmox the module stops or suspends the VM, in Pterodactyl it calls the server suspension. In both cases WHMCS sets the Suspended status.

How the module authenticates

Proxmox VE: an API token with its own permissions and expiry. Pterodactyl: a Bearer application key.

"Per arrangement" marks a detail we have not confirmed in public documentation.

From payment to a running VPS

The run with a Proxmox module: the service history in the client area and what WHMCS, the module and Proxmox VE do meanwhile.

The vps-1342 service in the client area on a phone: the IP address, access details sent by email, power buttons and the history from the paid invoice to the access details

  1. Invoice paid

    • ClientWHMCSpays the order
    • WHMCSModuleCreateAccount with the product's parameters

  2. A VM from the template

    • ModuleProxmox VEclone the VM templateAPI token in the header
    • Proxmox VEModulea UPID task id
    • ModuleWHMCSsuccessstatus Active

  3. Start and access details

    • ModuleProxmox VEonce the task ends: configure and start
    • WHMCSClientwelcome email and access details

Long operations

Proxmox returns a task id and the clone runs in the background. The module stores it, and a job that checks the status finishes the work.

Buttons in the client area

VM start, stop and restart as custom module functions, shown with the service in the WHMCS client area.

Common questions about WHMCS

Answers about ready modules, several nodes, panel sign-on, failures and the quote.

Setting up WHMCS services by hand?

Tell us which panel or hypervisor you use and what should happen after payment. We will reply within an hour with questions and a quote.