# WHMCS visitor tracking through your gateway

Source: https://frosvo.com/docs/whmcs-visitor-tracking
Updated: 2026-11-08

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

The supplied `integrations/customer-gateway/whmcs-adapter.cjs` connects the [customer-owned gateway](/docs/customer-owned-integration-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](/docs/visitor-order-and-service-tracking). 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](https://developers.whmcs.com/api/authentication/), [client details](https://developers.whmcs.com/api-reference/getclientsdetails/), [orders](https://developers.whmcs.com/api-reference/getorders/), [invoices](https://developers.whmcs.com/api-reference/getinvoice/), [client services](https://developers.whmcs.com/api-reference/getclientsproducts/), [tickets](https://developers.whmcs.com/api-reference/getticket/).

## Common 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.
