WHMCS cPanel Integration: Complete Configuration Guide

WHMCS + cPanel is the most common hosting stack on earth, and most installs are configured 80% correctly. The remaining 20% is what causes provisioning failures, password sync issues, suspension races, and the "why doesn't the SSO button work?" tickets.

I've configured WHMCS-to-cPanel for hosting brands selling 10 accounts to 50,000+. Here's the working setup.

Prerequisites — what must already be true

• You have a cPanel/WHM server with admin (root) access.
• WHMCS is installed and licensed.
• Both servers can talk to each other over the network (WHMCS → WHM port 2087).
• WHM has at least one hosting package configured (the customer-facing plans you'll sell).

Step 1 — Create an API token in WHM

cPanel deprecated API-key authentication years ago. Use API tokens.

1. Log in to WHM as root.
2. Home → Development → Manage API Tokens.
3. Click Generate Token.
4. Name it descriptively: whmcs-integration.
5. Set ACL to Full Access (or scope it to the specific privileges WHMCS needs if you want least-privilege; the WHMCS cPanel module docs list the required ACLs).
6. Copy the token immediately — WHM only shows it once.

Don't use the root user's password as the credential. If you've been doing that, replace it with a token now.

Step 2 — Add the cPanel server to WHMCS

WHMCS Admin → Setup → Products/Services → Servers → Add New Server.

• Name: descriptive — web01-us-east, not server1.
• Hostname: the server's hostname (or IP).
• IP address: server's primary IP (used for some API calls and shown to clients).
• Nameservers: ns1/ns2 for accounts on this server (cosmetic — actual NS comes from the package or domain).
• Server Status Address: optional, for cPanel server status checks (use the server's status URL if you have one).
• Type: cPanel.
• Username: root (the cPanel user, even with API token auth).
• Password: leave blank — you're using a token.
• Access Hash: paste the API token here.
• Secure: Yes (uses HTTPS on port 2087). Always.
• Port: 2087 (WHM SSL). Use 2086 only if you really know what you're doing.

Click Test Connection. You should see "Connection successful." If not, see troubleshooting below.

Step 3 — Configure hosting products

You need a 1-to-1 mapping between WHMCS products and WHM packages.

In WHM:

WHM → Home → Packages → Add a Package

Create the package that defines disk quota, bandwidth, email accounts, MySQL databases, etc. Note the exact name.

In WHMCS:

1. Setup → Products/Services → Products → Create a New Product.
2. Choose Product Type: Shared Hosting (or Reseller, depending).
3. Fill in name, description, pricing.
4. Module Settings tab:
   • Module Name: cPanel.
   • Server Group: the group containing your server.
   • Package Name: the exact WHM package name from above.
   • Automatic Setup: Automatically setup the product as soon as the first payment is received. This is what makes provisioning hands-off.
5. Save.

Step 4 — Test provisioning end-to-end

This is the validation step everyone skips and regrets.

1. Create a test client in WHMCS (Clients → Add New Client).
2. Place an order for your new hosting product (use a coupon for 100% off so no payment is processed).
3. WHMCS Admin → Orders → Pending → find the order → click the order → click Module Create.
4. Watch the output. Success = "Module Command Success." Failure includes a specific error.
5. Log in to WHM and confirm the account exists with the right package.
6. From the WHMCS service detail page, click Login to cPanel (the SSO button). You should land in the customer's cPanel.
7. From the service detail page, click Suspend. Verify WHM shows the account as suspended.
8. Click Unsuspend. Verify in WHM.
9. Click Terminate. Verify the account is gone from WHM.

If any step fails, the WHMCS Module Log (Utilities → Logs → Module Log) shows the exact API call and response.

Step 5 — Server groups (when you have more than one)

For two or more cPanel servers, group them so WHMCS can pick the right one for each new account.

1. Setup → Products/Services → Servers → Create New Group.
2. Add servers to the group.
3. Pick a Fill Type:
   • Add to next server until full (default) — fills server1, then server2. Best for spreading manually.
   • Fill the server until full then move to next — same as above (same fill type, slightly different option label depending on WHMCS version).
   • Add to the least full server — load-balanced. Best for keeping servers evenly loaded.
4. Set the per-server account limit. WHMCS won't provision more than N accounts on a single server within the group.

Step 6 — The overlooked details

Username generation

Setup → General Settings → Other → Generate Username. WHMCS auto-generates usernames from the customer's name/domain. Defaults are fine; the only common tweak is enabling/disabling random suffixes to avoid collisions.

Password sync

By default, WHMCS stores the cPanel password (encrypted). When the customer or admin changes it via WHMCS, both systems sync. If you let customers manage their cPanel password directly inside cPanel, the WHMCS-stored copy becomes stale and SSO will break. Either:

• Train customers to change passwords via WHMCS only (and use a hook to enforce by intercepting cPanel logins), or
• Use the WHMCS Change Password function from the service detail page when the customer requests it.

Free domain on signup

Covered in my domain registrar guide. If you offer a free domain with hosting, the domain registration runs in parallel with the cPanel account creation. If either fails, you have a half-provisioned customer — set up monitoring (see below).

WHMCS sends welcome emails by default

WHMCS sends a "Hosting Account Welcome Email" with login details when provisioning succeeds. Customize the template at Setup → Email Templates → Hosting → Hosting Account Welcome Email. Include the cPanel login URL, server name, support links.

How to verify everything is wired

1. Place a test order from the customer-facing order form. Pay (or coupon to zero). Account provisions automatically.
2. Check email — welcome email arrives with login details.
3. Customer logs in to client area; clicks "Login to cPanel" — SSO works.
4. Customer logs in to cPanel from the link in the welcome email — direct login works.
5. From WHMCS admin, suspend → verify in WHM → unsuspend → verify.
6. Manually mark the service as cancelled and run the termination → account deleted from WHM.

Do this drill quarterly per server. It catches API token rotations, permission changes in WHM, and other drift.

Common pitfalls

"Test Connection fails with 'cURL error 7: Failed to connect'." The WHMCS server can't reach port 2087 on the WHM server. Firewall rule or CSF block. telnet WHM-IP 2087 from the WHMCS server to confirm. Open the firewall both sides.

"Test Connection fails with 'cURL error 60: SSL certificate problem'." The WHM server's SSL certificate is self-signed or expired. Install a real cert on WHM (Let's Encrypt works fine for hostnames). Don't disable SSL verification — it defeats the security of HTTPS.

"Provisioning works but SSO doesn't." WHM API token doesn't include the create-session privilege. Generate a new token with the right ACL.

"Suspending in WHMCS suspends in WHM but customer can still receive email." By default, cPanel suspension doesn't disable mail. Configure suspension behavior in WHM → Tweak Settings → Force suspend mail.

"Race condition: customer paid, provisioning failed, customer can't log in." A common operational gap. Set up monitoring: a daily check for services with status="Pending" or "Failed" — anything stale >1 hour gets flagged. Or use the AfterModuleCreate hook to push success/fail to Slack.

"Termination in WHMCS doesn't delete cPanel account." Check the WHMCS product config — there's a "termination behavior" option. Some shops choose "suspend instead of delete" to preserve data for X days; verify yours matches your business policy.

My take — the operational discipline

1. One product, one package, one name. The WHMCS product name, the WHM package name, the customer-facing plan name — all the same. Otherwise debugging is misery.
2. Monitor the Module Log daily for the first month after a new server goes live. Anything unexpected is easier to fix when fresh.
3. Document your server-to-package mapping in a shared spreadsheet. New servers, new packages, deprecated plans — keep it current.
4. Test the suspend/unsuspend flow before relying on auto-suspend. The day suspension fires automatically is not the day to discover the API permission is wrong.

Going further

• WHMCS cPanel integration docs
• WHM API documentation
• Build your own provisioning module when the cPanel module isn't enough.

I set up and maintain WHMCS + cPanel integrations for hosting businesses — server provisioning, package mapping, multi-server load balancing, and the operational monitoring that prevents incidents. Tell me about your setup and I'll send a quote in 24 hours.