composer require aheadworks/module-captcha<version>

Introducing to Magento 2 Google Invisible Recaptcha

Extension Overview

Protect your store from automated spam, fake registrations, and brute-force attacks with the Google Invisible reCAPTCHA extension for Magento 2. This module seamlessly integrates advanced bot-protection engines into your store's frontend and backend endpoints without disrupting the legitimate user experience. By deploying intelligent risk analysis, invisible tokens, and alternative verification protocols, you block malicious scripts while keeping conversion rates high. Manage your entire security layout straight from your Magento admin area without modifying theme code.

Key Features

• Choose between Google reCAPTCHA (v2/v3), Cloudflare Turnstile, and hCaptcha;

• Protect checkout conversion rates using invisible, background risk scoring;

• Secure headless architectures with native REST and GraphQL API protection;

• Instantly eliminate automated spam registrations, fake reviews, and newsletter signups;

• Restrict verification challenges to high-risk regions with targeted Geo-Fencing;

• Prevent checkout downtime during provider outages with automated Fail-Safe routing.

Using Magento 2 Google Invisible ReCAPTCHA

Extension Configuration

To configure the global settings for the module, navigate to Stores > Settings > Configuration > AHEADWORKS EXTENSIONS > Captcha.

CAPTCHA Configuration

Service Provider Settings

To configure the bot protection engine for your store, choose the provider that matches your security and user experience preferences from the dropdown list:

• Google reCAPTCHA v2 (Checkbox) — Requires users to check an "I'm not a robot" box.

• Google reCAPTCHA v2 (Invisible) — Validates requests in the background, only displaying a challenge if suspicious activity is detected.

• Google reCAPTCHA v3 — Verifies traffic behind the scenes using a background risk-scoring system.

• Cloudflare Turnstile — Cloudflare's alternative tool for non-intrusive user verification.

• hCaptcha — An independent third-party bot-protection service.

Based on your selection, click the blue dynamic shortcut link ("Please click here to redirect...") to open Magento's native storefront configurations (Security ➔ Google reCAPTCHA Storefront).

Expand the corresponding section matching your chosen engine to configure credentials:

Option 1: Google reCAPTCHA v2 (Checkbox)

• Google API Website Key — Enter the public site key generated in your Google Admin Console.

• Google API Secret Key — Enter the private secret key generated in your Google Admin Console.

• Size — Defines the visual size of the widget (uncheck Use system value to customize).

• Theme — Adjusts the color palette appearance.

• Language Code — Optional field to force a specific locale; auto-detects browser settings if left empty.

Option 2: Google reCAPTCHA v2 (Invisible)

• Google API Website Key — Enter the public site key generated in your Google Admin Console.

• Google API Secret Key — Enter the private secret key generated in your Google Admin Console.

• Invisible Badge Position — Set the position of the reCAPTCHA badge on the storefront.

• Theme — Choose between Light Theme or Dark Theme appearance.

• Language Code — Optional field to force a specific interface language; automatically detects user browser language if left blank.

Option 3: Google reCAPTCHA v3

• Google API Website Key — Enter your public site key generated via the Google Admin Console.

• Google API Secret Key — Enter your private validation secret key generated via the Google Admin Console.

• Invisible Badge Position — Choose where the native reCAPTCHA v3 badge appears on your pages.

• Theme — Choose the visual appearance mode for the protective widget badge.

• Language Code — Optional configuration to force a specific localization string; defaults to automatic browser detection if left unconfigured.

Option 4: Cloudflare Turnstile

Select Cloudflare Turnstile from the Service Provider dropdown list to utilize Cloudflare's privacy-focused alternative to traditional CAPTCHAs:

• Site Key — Enter the public HTML frontend key generated in your Cloudflare dashboard.

• Secret Key — Enter the private server-side token used for backend validation requests.

• Widget Theme — Define the visual styling mode. Choosing Auto (default) automatically matches the widget canvas to your storefront theme's color scheme.

• Widget Size — Adjust the visual proportions of the challenge container.

• Language — Set a hardcoded localization language string or keep it on Auto-detect to automatically match the visitor's browser locale configuration.

• Custom Error Message — Enter a localized string to display on the storefront if validation fails. Basic HTML syntax formatting tags are supported.

• Whitelisted IPs — Input a comma-separated list of specific IP addresses or ranges that are allowed to bypass validation checkpoints without rendering a Turnstile challenge box.

Option 5: hCaptcha Integration Guide

Select hCaptcha from the Service Provider dropdown list to deploy an alternative user-privacy focused anti-bot framework across your forms:

• Site Key — Input your public HTML client-side token key fetched from the hCaptcha dashboard.

• Secret Key — Input your backend communication token used for validating token payloads via server API handshake requests.

• Size — Choose the layout density footprint for the display container asset.

• Theme — Choose the base background layout palette tone styling parameter.

Protected Native Forms

Toggle individual frontend forms to Yes or No to control where the verification challenge is enforced:

• Account Creation — Secures the new customer registration form.

• Login — Adds verification checks to the customer login screen.

• Forgot Password — Protects the password recovery request form.

• Payment / Place Order — Secures the final step of the checkout process.

• Product Reviews — Blocks automated spam submissions on product detail pages.

• Send to a Friend — Controls validation for the product sharing form.

• Newsletter Form — Protects the newsletter subscription field. Note: When enabled, the asset loads globally across every page where the field resides.

• Contact Us Form — Protects the main customer feedback submission route.

• Enable for Edit Customer Account — Enforces verification when users update account profile information.

• Enable for Wishlist Sharing — Validates users trying to distribute wishlist links.

If you selected reCAPTCHA v3 in the first step, an additional Security Threshold (Score: 0.1 - 1.0) input field will appear next to each form toggle switch.

• Enter the minimum acceptable target score for each form field (e.g., 0.7).

• Google tracks and scores traffic behind the scenes: 1.0 indicates a clean, human interaction, whereas 0.1 represents an obvious bot payload. If the assessment value for a user submission falls below your configured threshold, the backend logic blocks the request.

Custom Forms 

To extend protection to non-native forms or third-party extension modules, use the dynamic selector matrix:

• Form Selector — Input the specific front-end element target.

• Status — Use the toggle switch to instantly enable or disable validation for that specific selector rule.

• Add Custom Form — Click this button to add another row for configuration parameters.

General Settings

This section covers core performance, fallback behaviors, and advanced script loading criteria for your chosen captcha engine.

• Enable Geo-Fencing — Select Yes to restrict CAPTCHA validation only to targeted countries. Selecting Yes dynamically reveals the following dependency fields:

• Target Countries — Select one or multiple countries from the list to restrict validation exclusively to visitors originating from these regions.

• IPInfo Token — Input your API access token for the IPInfo Lite service to ensure accurate IP-based country detection.
  
  

• Fail-Safe Mode — Choose whether to allow submissions if the service drops. Selecting Yes ensures that if the provider's API becomes unresponsive, form submissions remain open to users while falling back to a background Honeypot Layer for protection.

• Conditional Loading — Select Yes or No to control asset delivery. Setting this to Yes delays loading external provider scripts until a customer directly interacts with a protected form via focus, click, or hover, optimization that improves core performance metrics like LCP and TBT.

• CSP Auto-Configure — Select Yes to let the extension automatically whitelist the necessary CAPTCHA domains (including script, frame, connect, and image sources) within your Content Security Policy layout based on your active API choices.

API Protection (REST & GraphQL)

This section allows merchants to enforce backend captcha validation for headless storefront configurations or API integrations.

• Enable API Protection — Select Yes or No to control endpoint security rules. Setting this to Yes enforces server-side verification checks for specified incoming REST and GraphQL requests.

• Protected REST Endpoints — Enter specific REST route URLs that require verification token payloads, with one entry per line.

• Protected GraphQL Operations — Specify the exact GraphQL operation names to monitor and protect, with one name per line.

reCAPTCHA Failure Messages

To customize the frontend notifications users see when a security check fails or runs into issues, navigate to Stores ➔ Configuration ➔ Security ➔ Google reCAPTCHA Storefront and expand the reCAPTCHA Failure Messages accordion group.

These settings allow you to define clear user-facing communication for different failure states:

• reCAPTCHA Validation Failure Message — Input the error message that displays on the storefront when a user or automated bot fails the verification check. To input custom text, uncheck the Use system value box.

• reCAPTCHA Technical Failure Message — Input the error text that triggers if the storefront cannot establish a proper background connection with the provider's API servers or if network connectivity completely drops. To input custom text, uncheck the Use system value box.