Skip to contentSkip to content
Developers

WHMCS visitor tracking through your gateway

Configure the supplied read-only WHMCS adapter, verified client identity, exact object references and safe status results.

Last updated

The supplied integrations/customer-gateway/whmcs-adapter.cjs connects the customer-owned gateway to WHMCS read APIs. It supports order, invoice, service and ticket status. It is available for controlled pilot verification; local protocol tests do not certify your WHMCS installation, permissions, identity mapping or deployment.

Configure the customer-operated gateway

  1. Create a dedicated WHMCS API credential with only GetClientsDetails, GetOrders, GetInvoice, GetClientsProducts and GetTicket, removing unused scope permissions. Allow the gateway server's IP in WHMCS. Keep the credential on your gateway host, separate from Frosvo's gateway signing secret and from the agent plugin's action credential.
  2. Configure FROSVO_GATEWAY_ADAPTER=whmcs, FROSVO_WHMCS_URL with your HTTPS WHMCS installation base address, FROSVO_WHMCS_IDENTIFIER and FROSVO_WHMCS_SECRET. Include an installation subdirectory when applicable; do not supply the API filename. Requests use includes/api.php, refuse redirects, have a source timeout and cap response bodies.
  3. Complete the gateway's signing-secret, TLS, replay-storage and traffic configuration from its runtime README. Grant only the read scopes you intend to support in both the gateway and Frosvo's owner settings.
  4. Enable the website's visitor tracking card. This does not install a WHMCS gateway or change the agent plugin.

Verify the WHMCS client identity

Your server-side website identity integration must attest the WHMCS client account ID, not an administrator, login-user, contact or another panel's ID. Use the namespaced external identity whmcs:<client-id>, for example whmcs:123. Frosvo passes the verified identity to the adapter; never expose the site's identity signing secret to browser code.

A verified email-only session can resolve the exact WHMCS client email. If both email and external identity are present, both must match that client. Plain numeric or other-system external IDs are refused instead of falling back to email. Typing an email into the widget is not verification. Validate your existing WHMCS addon identity integration before using it; enabling its agent plugin does not establish this mapping automatically.

Supported references

| Card type | Accepted reference | WHMCS object | |---|---|---| | Order | ORD-123 or canonical numeric ID | Internal order ID, not a different displayed order number | | Invoice | INV-123 or canonical numeric ID | Internal invoice ID, not a sequential invoice label | | Service | SVC-123 or canonical numeric ID | Client product/service ID | | Ticket | Exact public ticket number | GetTicket's ticketnum / returned tid |

The widget requires at least two reference characters; use the prefix form for single-digit IDs. The adapter checks returned identifiers and userid/clientid ownership even when the API already received a client filter. Guest tickets and cross-client records must not be exposed.

Results and troubleshooting

Only reference, a generic object title and a recognized status leave this adapter. It does not return account details, service passwords/IPs, ticket access tokens, replies, private notes, transactions or payment links. Authorization and lookup share the same minimal snapshot; lookup cannot fetch a different object after authorization.

Mapping whmcs-read-v1 recognizes standard statuses; custom or unfamiliar statuses display Unknown. Review and version any mapping changes before deployment. Unknown source update times stay unknown: WHMCS dates without a timezone are not converted into invented UTC timestamps. Paid is invoice status, not proof of service provisioning or universal net proceeds after adjustments.

Recognized missing objects and foreign-owned objects produce no accessible match. Provider outages, malformed/oversized responses, missing ownership fields and unexpected API errors produce an unavailable lookup, with no raw provider error. Inspect the gateway/WHMCS configuration privately; do not add credential or response-body logging. Larger ticket histories can exceed the response cap and require a narrower source integration.

Before customer use, test owned and foreign records for every enabled scope, unverified sessions, mismatched IDs/emails, unknown references/statuses, WHMCS credential revocation, blocked IPs, outages, TLS and replay-store restart/rotation. Run node --test tests/whmcs-tracking.test.cjs for the local synthetic HTTP suite; retain separate evidence from your controlled WHMCS installation. No production certification is implied by a successful ping.

WHMCS contracts: authentication, client details, orders, invoices, client services, tickets.

Frequently asked questions

Does enabling the agent WHMCS plugin automatically expose records to visitors?

No. Visitor tracking uses a separately deployed read-only gateway adapter and its own restricted WHMCS credential.

Can a visitor type an email to access a WHMCS invoice?

No. Frosvo requires a verified session; the adapter checks that identity against the WHMCS client and exact object's owner.