# WHMCS configuration

Global and per-product settings for the HexaHost GameCloud WHMCS integration.

## Addon module (global)

**Setup → Addon Modules → HexaHost GameCloud → Configure**

| Setting | GameCloud env | Description |
|---------|---------------|-------------|
| GameCloud API URL | `API_URL` | Base URL, e.g. `https://api.example.net` — no trailing slash |
| Integration ID | `WHMCS_INTEGRATION_ID` | Unique installation identifier |
| API Secret | `WHMCS_API_SECRET` | HMAC shared secret (≥ 32 chars) |
| Use mTLS client certificate | `INTEGRATION_MTLS_ENABLED` | Enable client cert — see [mtls](../mtls.md) |
| Client certificate path | — | PEM path readable by PHP |
| Client private key path | — | PEM path, restricted permissions |
| CA bundle path | — | Trust anchor for GameCloud API |
| Auto-reconcile on daily cron | — | Dry-run reconciliation after event poll |
| Event poll batch size | — | Default 50 |

## GameCloud side

```env
BILLING_PROVIDER=whmcs
WHMCS_INTEGRATION_ID=prod-whmcs-main
WHMCS_API_SECRET=<generated-secret>
WHMCS_WEBHOOK_SECRET=<optional-for-future-webhooks>
INTEGRATION_MTLS_ENABLED=true
APP_URL=https://panel.example.net
API_URL=https://api.example.net
```

Restart `api` after credential changes.

## Server module (per product)

Each WHMCS product using module `hexagamecloud` needs:

1. **Module Name:** HexaHost GameCloud
2. **Server:** Server entry pointing to API hostname
3. **Config options** or addon mappings — see [products](products.md) and [product mappings](../product-mappings.md)

### Default config options

| Option | Purpose |
|--------|---------|
| GameCloud Plan Slug | Fallback plan if no mapping row |
| Minecraft Version | Default version at provision |
| Software Family | VANILLA, PAPER, etc. |

Prefer **addon mappings** over raw config option text for production.

## Cron

WHMCS daily cron invokes:

- Pending event poll from GameCloud
- Optional reconciliation dry-run

Ensure WHMCS cron runs at least every 5 minutes for timely suspensions; daily hook handles bulk sync.

## Reverse proxy

If WHMCS reaches GameCloud through nginx/Traefik, preserve headers for mTLS fingerprint forwarding. Example: `deploy/nginx/integration-mtls.conf.example`.

## Staging checklist

- [ ] Integration ID unique per environment
- [ ] Test order on hidden WHMCS product
- [ ] SSO login to panel works ([sso](../sso.md))
- [ ] Suspend / unsuspend updates server state within 60s

## Related

- [Installation](installation.md)
- [Security](security.md)
- [Troubleshooting](troubleshooting.md)