Cloudflare Turnstile for WHMCS: Installation Guide

This guide explains, step by step, how to install Cloudflare Turnstile for WHMCS addon in your WHMCS instance and connect it to Cloudflare.

Before You Start

Make sure you have:

• WHMCS 8.x or 9.x
• PHP 7.2 or later
• Admin access to WHMCS
• Access to your server files
• A Cloudflare account

Compatibility

• WHMCS versions: 8.x and 9.x
• Supported templates: Twenty-One and Nexus
• Also compatible with child templates based on Twenty-One or Nexus

Part 1: Create Turnstile Keys in Cloudflare

1. Sign in to Cloudflare.
2. Open Turnstile from your Cloudflare dashboard.
3. Click Add Widget (or create a new Turnstile site).
4. Enter a name (for example: WHMCS Client Area).
5. Add your WHMCS domain under allowed hostnames.
   • Example: billing.example.com
6. Save.
7. Copy both values:
   • Site Key
   • Secret Key

Keep this page open. You will paste these keys in WHMCS next.

Part 2: Upload the Addon to WHMCS

1. On your server, open your WHMCS installation folder.
2. Go to:
   • modules/addons/
3. Upload the addon folder so the final path is:
   • modules/addons/turnstile/

Check that these files exist after upload:

• turnstile.php
• hooks.php
• lib/Turnstile.php
• js/
• lang/

Part 3: Activate the Addon in WHMCS

1. Log in to WHMCS Admin.
2. Go to:
   • System Settings -> Addon Modules
3. Find Cloudflare Turnstile.
4. Click Activate.
5. If prompted, assign admin role permissions for the addon.

Part 4: Configure the Addon

1. In WHMCS Admin, open addon configuration for Cloudflare Turnstile.
2. Set:
   • Enable Turnstile = On
   • Site Key = (paste from Cloudflare)
   • Secret Key = (paste from Cloudflare)
3. Choose your widget options:
   • Theme: auto (recommended)
   • Size: normal (recommended)
   • Appearance Mode: always (recommended to start)
   • Default Language: auto
4. Enable the forms you want to protect:
   • Protect Client Login
   • Protect Registration
   • Protect Password Reset
   • Protect Contact Form
   • Protect Ticket Submission
   • Protect Cart Checkout
5. Save changes.

Recommended First-Time Settings

For most setups, start with:

• Enable Turnstile: On
• Skip Logged-In Users: On
• Theme: Auto
• Size: Normal
• Appearance: Always
• Language: Auto
• All form protections: On

Part 5: Test Everything

Open your WHMCS client area in a private/incognito window and test:

1. Login page
2. Registration page
3. Password reset page
4. Contact page
5. Ticket submission page
6. Checkout page

Expected result:

• Turnstile appears near the submit button.
• Form submits normally when verification passes.
• If verification fails, user sees a friendly error message.