How to Add hCaptcha to Magento 2 Forms

Last updated: April 24, 2026 · Tested on Magento 2.4.7 with Grasch_HCaptcha 1.3.0 and MageMe WebForms.

hCaptcha for Magento 2 is a privacy-friendly CAPTCHA that blocks bots without sending visitor data to Google — GDPR-compliant by design and free for up to 1M verifications/month. You can enable it globally on native Magento forms (admin login, customer login, contact, reviews, newsletter, checkout) using the free open-source Grasch_HCaptcha module, or switch the CAPTCHA provider on custom forms built with MageMe WebForms. This guide covers both paths.

Which path is right for you?

Why Choose hCaptcha Over reCAPTCHA

Google reCAPTCHA is the most common CAPTCHA solution, but it sends visitor browsing data to Google for risk analysis. For stores operating under GDPR, CCPA, or other privacy regulations, this creates compliance concerns. hCaptcha solves this by keeping data processing minimal and transparent.

For EU-based stores or merchants selling to EU customers, hCaptcha eliminates the need for complex consent mechanisms that reCAPTCHA requires under GDPR regulations.

Option A — Free Grasch_HCaptcha Module

The open-source Grasch_HCaptcha module extends Magento’s built-in Magento_ReCaptcha framework and swaps the provider from reCAPTCHA to hCaptcha. This means hCaptcha automatically protects every form that Magento’s stock reCAPTCHA integration already covers — no code changes needed, no per-form configuration.

Install via Composer

From your Magento 2 root directory:

composer require grasch/module-hcaptcha
bin/magento setup:upgrade
bin/magento setup:static-content:deploy
bin/magento cache:clean

If you run a production build, add bin/magento setup:di:compile between setup:upgrade and setup:static-content:deploy.

Configure in Admin

1. Sign up at hcaptcha.com, add your domain, and copy the Site Key and Secret Key.
2. In Magento Admin, open Stores → Configuration → Security → hCaptcha Storefront (the module adds a parallel hCaptcha Admin Panel section for backend forms).
3. Paste your keys, pick Theme (Light/Dark) and Size (Normal/Compact), set the mode to Always on or Invisible, save, and flush cache.

Heads up. Grasch_HCaptcha is built on top of the native Magento_ReCaptcha* modules. They ship enabled in Magento 2.4.x, but if you’ve disabled any of them (for example Magento_ReCaptchaAdminUi), re-enable before installing — otherwise the module won’t wire itself into the admin login form. Verify with bin/magento module:status | grep ReCaptcha.

Option B — Set up hCaptcha in WebForms

If your forms are built with MageMe WebForms (contact forms, surveys, multi-step wizards, file-upload forms, quote requests), CAPTCHA is configured at the WebForms level — independently of the global Magento reCAPTCHA settings. Use this path when you want per-form on/off control or when your forms are custom WebForms rather than native Magento forms.

Step 1: Get Your hCaptcha Keys

1. Go to hcaptcha.com and create a free account
2. Add your site domain in the dashboard
3. Copy your Site Key and Secret Key

Step 2: Configure WebForms

In Magento Admin, navigate to MageMe → WebForms → Settings.

1. Set CAPTCHA Mode to Always on or Auto (shows only to suspicious visitors)
2. Select CAPTCHA Type as hCaptcha
3. Paste your Site Key and Secret Key
4. Choose Theme: Light or Dark (matches your store design)
5. Select Size: Normal or Compact
6. Save and flush cache

Step 3: Enable Per Form

Each form in WebForms inherits the global CAPTCHA settings. To override per form:

1. Open the form in MageMe → WebForms → Manage Forms
2. Go to the CAPTCHA tab
3. Set Mode to override the global setting if needed
4. Save the form

hCaptcha will now appear on the form frontend. Test by submitting the form to verify the challenge works correctly.

When to Use Each

WebForms supports hCaptcha, reCAPTCHA, and Turnstile as switchable providers on the forms you build — see the full Magento 2 Spam Protection Guide for a side-by-side of all options.

Common Issues & Troubleshooting

• Grasch module throws “Magento_ReCaptcha* is disabled”. Re-enable the framework: bin/magento module:enable Magento_ReCaptchaUi Magento_ReCaptchaAdminUi Magento_ReCaptchaFrontendUi, then setup:upgrade.
• hCaptcha widget not rendering on admin login. Clear pub/static and var/view_preprocessed, then bin/magento setup:static-content:deploy -f --area adminhtml.
• WebForms form still shows reCAPTCHA after switching to hCaptcha. Flush full_page and block_html caches and hard-reload; the rendered widget script is cached per form.
• Hyva or Breeze theme: widget missing. Both themes load scripts via custom loaders; if a minifier or JS bundler defers the hCaptcha script, initialisation can fail. Disable JS merging under Stores → Configuration → Advanced → Developer and re-test — if the widget appears, exclude the hCaptcha script from your minifier’s bundle list.
• Approaching the 1M/month limit. Unlikely for most stores, but monitor in the hCaptcha dashboard; if you hit it, switch the mode to Auto so only suspicious visitors see a challenge.

Key Takeaways

• Privacy-first protection — hCaptcha doesn’t track visitors or share data with ad networks, making it ideal for GDPR/CCPA compliance.
• Free for most stores — the free tier covers 1 million verifications per month, enough for virtually any Magento store.
• 3-minute setup — get your keys from hcaptcha.com, paste them into the module config or WebForms settings, done.
• Two paths, pick the right one — use Grasch_HCaptcha for Magento’s native forms (admin, customer, contact, reviews, newsletter, checkout), and WebForms for custom forms you build yourself. They complement each other.
• No vendor lock-in — both paths let you switch to reCAPTCHA, Turnstile, or back to hCaptcha without touching form structure.

Frequently Asked Questions