WHMCS Module Setup Guide

The official xyz.am WHMCS module is a server provisioning module (no physical server required). When a client orders a product mapped to it, WHMCS calls xyz.am's API to:

• Create a premium xyz.am account on order activation.
• Suspend the account on overdue invoice or manual suspension.
• Terminate the account on cancellation.
• Generate one-click SSO login links for the client area.
• Sync usage stats (profile pages, bookmarks, aliases, domains, websites, short URLs) to both the admin Service tab and the client area.

• WHMCS 8.0+ (uses module API v1.1).
• PHP 7.4+ with the curl and json extensions enabled.
• An xyz.am partner API key. Contact us if you don't have one — these aren't the same as user-facing API tokens.
• Outbound HTTPS access from your WHMCS server to https://xyz.am/api/.

1. Upload the module

Extract the module archive and upload the xyzam/ folder to:

/path/to/whmcs/modules/servers/xyzam/
├── xyzam.php
└── xyzamclientarea.tpl

2. Install the client-area template

Copy xyzamclientarea.tpl into each client area theme that your customers use. For the default theme:

cp modules/servers/xyzam/xyzamclientarea.tpl \
   templates/twenty-one/xyzamclientarea.tpl

If you only use one theme, this is the only copy you need. The template renders the SSO button, account details, and usage summary inside the service overview tab.

3. Verify file permissions

WHMCS must be able to read the module files. On most setups:

chmod 644 modules/servers/xyzam/*.php modules/servers/xyzam/*.tpl
chown -R www-data:www-data modules/servers/xyzam/

The module declares RequiresServer = false, so you don't need to add a server entry. Configuration lives on the product itself.

1. Create the product

1. Go to System Settings → Products/Services → Create a New Product.
2. Set Product Type to Other.
3. Choose a Product Group (e.g. "xyz.am Premium").
4. Give it a name like "xyz.am Premium — Monthly".
5. Click Continue.

2. Pick the module

On the Module Settings tab, select xyzam from the Module Name dropdown. The four config fields below appear automatically.

3. Fill in the config

4. Test the connection

Save the product, then click Test Connection in the Module Commands section. A green success badge means the API key is valid and reachable. A red error includes the HTTP code and a snippet of the upstream response — usually enough to diagnose.

5. Configure auto-provisioning

On the Module Settings tab, check the boxes you want WHMCS to call automatically:

• Automatically setup the product as soon as an order is placed — usually combined with "when first payment is received" for paid plans.
• Automatically suspend on overdue invoices.
• Automatically terminate after the cancellation grace period.

When you open a client's xyz.am service in WHMCS admin, the Custom Fields area shows live data pulled from xyz.am:

• Login to xyz.am — one-click SSO link (10-minute token).
• Membership Status — premium, free, etc.
• Membership Expiry — date or "Never".
• Credits — current credit balance.
• Profile Pages, Bookmarks, Email Aliases, Domains/Subdomains, Websites, Short URLs — current usage counts.

Data is fetched live on every page load — no cron sync required. If a stat shows — it means the upstream call failed; check the module logs.

In the WHMCS client area, the service detail page is replaced by xyzamclientarea.tpl. It shows:

• A big Access Your Premium xyz.am Account button (SSO).
• An Account Details panel — status, expiry, credits.
• A Usage Summary panel — counts of all premium features.
• Four Quick Actions shortcuts (Create Profile, Manage Bookmarks, Setup Domain, Shorten URLs) — all open xyz.am via SSO.

If you maintain a custom theme, the template uses standard WHMCS Smarty + Bootstrap classes, so it's safe to drop into any modern theme. To restyle, edit the <style> block at the bottom of the .tpl or override classes in your theme's CSS.

Module Logs

Every API call is logged via logModuleCall(). View them at Utilities → Logs → Module Log, then filter by Module = xyzam. Each entry shows the request URL, payload, and full response — including HTML snippets if a WAF intercepted the call.

Common errors

Test Connection failed

Click Test Connection on the product's Module Commands. The button calls /api/whmcs-api.php with action=test_connection. The response body (success or error) shows in the WHMCS admin banner. If it succeeds but provisioning still fails, the issue is endpoint-specific — check the per-call entries in the module log.

• The module sends the API key in both the Authorization: Bearer header and a ?key= query parameter for compatibility with WAFs that strip Authorization headers. If your hosting provider logs query strings, treat those logs as sensitive.
• SSO login URLs are valid for 10 minutes. WHMCS doesn't cache them — every page load mints a fresh token.
• Keep Verify SSL on. The "off" option exists only for development.
• The partner API key gives full account-level control over xyz.am users. Rotate it if a WHMCS staff account is compromised.