How to Integrate hCaptcha with Magento 2

How do you add hCaptcha to Magento 2?#

Purchase and deploy MageComp's Magento 2 hCaptcha extension through your Magento release process, then open Stores > Configuration > MageComp > hCaptcha. Enter the sitekey and secret, select the storefront and Admin forms that require hCaptcha, and test every enabled workflow before production.

This guide covers the commercial MageComp Magento 2 hCaptcha extension, also listed on Adobe Commerce Marketplace. MageComp lists support for Magento 2.3 through 2.4. Confirm that the purchased extension supports the store's exact Magento or Adobe Commerce release, PHP runtime, theme, and checkout before deployment.

These instructions were last validated on September 22, 2026 with MageComp hCaptcha extension 1.0.5.

Reduce CAPTCHA friction on your Magento storefront#

• Keep shoppers focused on their purchase. With hCaptcha Pro's 99.9% Passive mode, fewer than 0.1% of legitimate users receive a challenge. That means fewer verification interruptions on checkout and account forms covered by your tested Magento integration.
• Apply stronger checks when needed. Pro automatically increases challenge difficulty as risk rises, keeping routine shopping less disruptive while giving suspicious interactions more scrutiny.

New Pro sitekeys use 99.9% Passive by default. For an existing sitekey upgraded to Pro, select that mode under Behavior in the hCaptcha dashboard.

Prepare the store and credentials#

1. Confirm the Magento edition, version, PHP version, storefront theme, checkout, deployment model, and licensed production domains.
2. Review extension conflicts and deploy first through the store's development and staging process.
3. Start with hCaptcha Pro for fewer challenges and adaptive protection on protected Magento shopping flows, or use existing compatible hCaptcha credentials.
4. Create a sitekey for the storefront and add every hostname that serves a protected form.
5. Retrieve the matching hCaptcha account secret and restrict Magento configuration access.

The sitekey can appear in storefront markup. The secret must remain in server-managed configuration and must never enter a CMS block, theme JavaScript, browser-visible markup, logs, or a public repository.

Install the MageComp extension#

Obtain the extension from MageComp or Adobe Commerce Marketplace. Use the exact Composer package name, version, and Magento module name supplied with the purchased package; do not infer them from the product title.

Adobe recommends adding extensions in a development branch, committing both composer.json and composer.lock, and deploying through the project's normal build process. For a Composer package, the pattern is:

composer require <vendor/package>:<version> --no-update
composer update

For an on-premises deployment that requires manual module enablement, follow the package guide and Adobe's module workflow. Verify the supplied module name before using commands such as bin/magento module:status, module:enable, setup:upgrade, and cache:clean. Adobe Commerce Cloud projects should enable and deploy extensions through source control; do not change a remote environment directly.

Configure hCaptcha in Magento Admin#

1. Open Stores > Configuration > MageComp > hCaptcha.
2. Enter the hCaptcha website key and secret key under General.
3. Under Admin Panel, enable protection and select Admin Login or Admin Forgot Password where required.
4. Under Frontend, enable protection and select the applicable pages and forms.
5. Choose Light or Dark theme and Normal or Compact size.
6. Configure custom-form support only after reviewing the vendor's generated block code and the server-side handler for that form.
7. Leave the IP whitelist disabled unless the security owner approves narrowly scoped, trusted addresses and an operational review process.
8. Save the configuration and clear applicable Magento caches.

Version 1.0.5 advertises 13 storefront workflows: customer login, forgot password, contact, registration, product review, newsletter subscription, send to friend, customer-account editing, confirmation-email resend, wishlist sharing, coupon codes, checkout, and multishipping checkout. It also advertises Admin login and forgot password protection. Enable only the workflows the store can test completely.

Verify every enabled workflow#

1. Open each protected route in a private browser window and confirm the expected widget mode renders.
2. Complete hCaptcha and submit valid data. Confirm Magento performs the action once.
3. Submit without a valid response and confirm the action is rejected.
4. Repeat with expired and reused tokens.
5. Test customer login and recovery without locking out the only Admin account.
6. Test checkout, multishipping, coupon, REST, and GraphQL behavior with the exact storefront clients in use.
7. Retest each website and store view, Hyva or Luma theme, custom checkout, full-page cache, CDN, consent tooling, and Content Security Policy.

MageComp advertises protection for 13 storefront forms, Admin login and password recovery, custom CMS pages and static blocks, trusted-IP allowlisting, REST and GraphQL APIs, and Hyvä storefront options. Treat those as vendor-documented capabilities for the purchased release rather than independent certification of its internal request handling.

Because the extension source is distributed commercially, verify behavior from the outside: each selected controller must reject a missing, invalid, expired, or reused token; Siteverify or network failure must stop the protected action; and logs must not contain the secret or complete response token. A visible widget alone does not prove enforcement. Escalate any failed case to MageComp support before enabling that workflow in production.

Troubleshoot common Magento problems#

The module is installed but its settings are missing

Confirm the exact module is enabled and included in the deployed app/etc/config.php. Complete the vendor's setup and cache steps, then check Stores > Configuration > MageComp > hCaptcha again.

hCaptcha appears on one store view only

Check the configuration scope and hostname assigned to the sitekey. Review website, store, and store-view overrides before copying values between scopes.

Checkout stops after enabling hCaptcha

Confirm extension 1.0.5 and the exact checkout implementation. Standard, multishipping, Hyva, headless, REST, GraphQL, and customized checkouts can take different paths and require separate tests.

Admin access is blocked

Use the store's approved recovery procedure to disable or correct the module configuration from a trusted maintenance path. Do not rely on a broad permanent IP bypass as the recovery design.

Frequently asked questions#

Is the Magento 2 hCaptcha extension free?

No. MageComp sells it as a commercial extension. Purchase and support terms come from MageComp or Adobe Commerce Marketplace.

How should I confirm Magento compatibility?

Verify the purchased package's PHP, edition, theme, checkout, and extension compatibility before deployment.

Which Magento forms can it protect?

The vendor lists 13 storefront workflows plus Admin login and forgot password. Actual coverage depends on enabled settings, version, theme, checkout, APIs, and customizations.

Can I protect a custom CMS form?

The extension advertises custom CMS page and static-block support. Confirm that the custom form's submission handler enforces verification server-side before treating it as protected.

Should I enable the IP whitelist?

Only after a security review. An allowed address bypasses hCaptcha, so keep entries narrow, documented, monitored, and removable.