---
title: WHMCS
---

# WHMCS

Official CaptchaLa addon module for WHMCS. Adds CAPTCHA verification to the WHMCS client area — login, registration, password reset, contact form, ticket submission and cart checkout — without writing any code.

Unlike a plain site-key widget, every challenge is backed by a **server-issued, single-use token** (anti-replay), and no third-party trackers are loaded.

## What it covers

Each surface below is an individual toggle in the module's settings — enable only the ones you want to protect.

- Login
- Registration
- Password reset
- Contact form
- Ticket submission
- Cart checkout

## Requirements

- WHMCS 8.x and 9.x (tested against the 8.3 and 9.0 client area; works with both the `six` and `twenty-one` themes, with or without Friendly URLs)
- PHP 8.0+ (WHMCS 9.0 itself requires PHP 8.2+)
- A CaptchaLa account — get your **App Key** + **App Secret** at [`dash.captcha.la`](https://dash.captcha.la)

## Install

### 1. Install the module

1. Download the latest `whmcs-x.y.z.zip` from the [releases](https://github.com/Captcha-La/captchala-whmcs/releases).
2. Extract it into your **WHMCS root** directory. This adds `modules/addons/captchala/`.
3. In WHMCS admin, go to **Setup → Addon Modules**, find **CaptchaLa**, and click **Activate**.

### 2. Configure

Click **Configure**, then:

1. Paste your **App Key** and **App Secret**.
2. Choose a **Widget mode** and **Theme**.
3. Toggle the forms you want protected.
4. Click **Save Changes**.

Open the **CaptchaLa** page in the admin sidebar to run a live connection test against the dashboard.

::: tip
After activating, if the widget doesn't appear, re-save the module settings once — WHMCS only registers a module's `hooks.php` when the module is (re)activated/saved.
:::

## Configuration

All settings live under **Setup → Addon Modules → CaptchaLa → Configure**.

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| App Key | string | — | Public key from the CaptchaLa dashboard. Required. |
| App Secret | string | — | Server secret, used to issue and validate tokens. Required; never exposed to the browser. |
| Widget mode | enum | `popup` | `popup` (trigger bar → fullscreen challenge), `float` (inline panel), `embed` (inline checkbox), `bind` (invisible, intercepts submit). |
| Theme | enum | `default` | Colour preset: `default`, `dark`, `slate`, `emerald`, `amber`, `rose`. |
| Language | string | `auto` | BCP-47 code (e.g. `en`, `zh`, `de`) or `auto` to follow the browser. |
| Protect login | bool | on | Challenge the client-area login. |
| Protect registration | bool | on | Challenge new account registration. |
| Protect password reset | bool | on | Challenge the password-reset form. |
| Protect contact form | bool | off | Challenge the contact form. |
| Protect ticket submission | bool | off | Challenge the final ticket-submit step. |
| Protect cart checkout | bool | off | Challenge cart checkout. |
| Skip for logged-in users | bool | on | Don't challenge visitors who already have a client session. |
| Failure message | string | — | Message shown when verification fails. |

## How it works

On each protected form page the module issues a fresh **server token (`sct_`)** from the dashboard, scoped to that form's action, and renders the widget bound to it. After the visitor solves the challenge, the SDK writes a **single-use pass token (`pt_`)** into the form. On submit, the module validates that `pt_` server-side before WHMCS processes the form; replays and action mismatches are rejected.

If the dashboard is temporarily unreachable, the module **fails open** (lets the submission through) so your client area is never locked out by an upstream hiccup.

## FAQ

**Is the module free?**

Yes. The module is free. The CaptchaLa free plan covers 10,000 verifications a month — paid plans only apply if you need more volume.

**Does it work on both WHMCS 8 and 9?**

Yes — tested on the 8.3 and 9.0 client area, with the `six` and `twenty-one` themes, with or without Friendly URLs.

**The widget doesn't show up.**

Re-save the module settings once (Configure → Save Changes). WHMCS only registers `hooks.php` when the module is (re)activated/saved.

## Source

- Module repository: [`github.com/Captcha-La/captchala-whmcs`](https://github.com/Captcha-La/captchala-whmcs)
- Issues / feature requests: filed against the repository above
- Related: [Web SDK](/web-sdk) · [PHP Server SDK](/sdk/server-php) · [API Reference](/api-reference)