Truform Captcha

WHMCS module

Install and configure the Truform Captcha addon for WHMCS 8.x.

The Truform WHMCS addon protects client and admin forms with Syndaq Truform puzzle captcha. Version 2.x includes a setup wizard, connection testing, per-form toggles, and module logging.

Requires: WHMCS 8.x+, PHP 8.0+, PHP cURL extension.

Download

Sign in to the Syndaq client area.
Open your Truform service and Manage the site key for your WHMCS domain.
Go to the Integrate tab and download WHMCS addon module (v2.0.0+).

Install

Extract the zip and copy truform_captcha/ into your WHMCS modules/addons/ directory.
In WHMCS admin, go to Setup > Addon Modules.
Activate Truform Captcha and grant Full Administrator access (or your preferred role).
Click Configure and enter your Site key (tf_pub_...) and Secret key (tf_sec_...).
Open Addons > Truform Captcha to run the setup wizard.

Setup wizard

The wizard walks through four steps:

Step	Action
1	Confirm keys are saved in addon configuration
2	Test connection to api.syndaq.com (plan, quota, key status)
3	Choose which WHMCS forms to protect
4	Complete setup

You can change protection toggles later under Setup > Addon Modules > Configure or in the wizard step 3 panel.

Protected forms

Enable any combination of these surfaces:

Toggle	WHMCS surface
Client login	Client area login page
Contact form	Public contact form
Client registration	New client signup
Password reset	Forgot password flow
Ticket submission	Open ticket form
Checkout	Shopping cart checkout
Admin login	WHMCS `/admin` login

Each form uses a distinct data-action value (login, contact, register, etc.) for analytics and siteverify.

Configuration options

Field	Purpose
Site key	Public `tf_pub_` key (browser widget)
Secret key	Secret `tf_sec_` key (server siteverify)
Protected domain	Optional. Root domain on your Truform site key for validation warnings
Widget theme	`light` or `dark`
Widget size	`normal` or `compact`
Verification mode	`interactive` (default) or `managed`. Managed also requires the same setting on the site key in the Syndaq client area
Fail open on API outage	Allow submissions when Syndaq API is unreachable (optional, less secure)

Dashboard

Open Addons > Truform Captcha for:

Connection test (keys, plan, quota remaining)
Last verification result and timestamp
Quota usage warning when above 80%
Server IP reminder (for Truform IP allowlists)
Embed snippet for custom templates
Update check against Syndaq published version

Theme compatibility

Hook variables differ by theme. The module injects standard Smarty variables such as {$loginCaptcha} and {$contactCaptcha}.

If the widget does not appear, add the variable to your theme template. See templates/overrides/README.md in the addon folder or the table below:

Form	Smarty variable
Login	`{$loginCaptcha}`
Contact	`{$contactCaptcha}`
Register	`{$registerCaptcha}`
Password reset	`{$passwordResetCaptcha}`
Tickets	`{$ticketCaptcha}`
Checkout	`{$checkoutCaptcha}`

Clear template cache after edits: Utilities > System > Clear Template Cache.

Module logging

Verification and API calls are written to Utilities > Logs > Module Log when WHMCS logging is enabled. Search for truform_captcha.

Error messages

The module maps Syndaq API errors to readable messages:

error_code	Meaning
domain_not_allowed	WHMCS hostname does not match the Truform site key domain
ip_not_allowed	Server IP not on the key allowlist
quota_exceeded	Monthly Truform quota exhausted
rate_limit_exceeded	Too many requests per minute

Troubleshooting

Widget does not show

Confirm the protection toggle is enabled for that form.
v2.0.1+ auto-mounts on Twenty-One and similar themes; add the Smarty variable for custom placement (see above).
Clear WHMCS template cache.

getSiteKey() or captcha template errors

Upgrade to Truform WHMCS module v2.0.1+. Older builds overwrote WHMCS $captcha with HTML.
Disable WHMCS built-in captcha for forms Truform protects (Setup > General Settings > Security), or enable Disable WHMCS built-in captcha in the module settings (v2.0.4+; syncs automatically when protection toggles change).

Connection test: Wrong key type

Site key must be the public key (tf_pub_...).
Secret key must be the secret key (tf_sec_...). These are separate fields in addon configuration.

Verification always fails

WHMCS System URL hostname must match the domain on your Truform site key (including subdomains).
If IP restrictions are enabled on the key, add your server's outbound IP in the Syndaq client area.

Lockout during API outage

Enable Fail open on API outage only if you accept the security tradeoff.

Updates

The dashboard Check for updates button compares your installed version against https://syndaq.com/truform/whmcs-module-version.json. Download newer releases from the Syndaq client area Integrate tab.

Official integrations - all starter packs
Web integration - widget options and callbacks
Site keys and security - domains and IP rules