HexaHost-GameCloud/docs/integrations/whmcs/reconciliation.md

WHMCS reconciliation (Phase E)

HexaHost GameCloud compares WHMCS service links with server state and reports drift.

API endpoints

Method	Path	Purpose
GET	/integrations/whmcs/accounts	ListAccounts sync payload
POST	/integrations/whmcs/services/import	Link an existing GameCloud server
POST	/integrations/whmcs/reconcile	Full installation reconciliation
POST	/integrations/whmcs/services/:id/reconcile	Single-service reconciliation
GET	/integrations/whmcs/events	Cursor-based event poll
POST	/integrations/whmcs/events/ack	Acknowledge or dead-letter events

Reconciliation checks

• Suspended link without billing suspension
• Active link with billing suspension
• Terminated link with non-deleted server
• Running server while suspended
• Plan / RAM mismatch (when expected values provided)
• Orphan servers (WHMCS client without service link)
• Missing join slug (info)

Severity

INFO, WARNING, BLOCKING, DESTRUCTIVE, SECURITY

Automatic repair (autoRepair: true, dryRun: false) only applies safe fixes:

• Apply billing suspension when link is suspended
• Clear billing suspension when WHMCS reports Active
• Block running servers that should be suspended

Events

GameCloud emits:

• reconciliation_required — blocking/security issues found
• usage_period_ready — previous UTC month closed (worker)

WHMCS should poll GET /events, process payloads, then POST /events/ack. Failed events can be dead-lettered.

PHP module

• hexagamecloud_ListAccounts() — server sync
• ApiClient::reconcileService() / reconcileAll()
• ApiClient::importService() for controlled imports

Worker

Daily at 03:00 UTC the worker runs a lightweight reconciliation pass for all active installations.