How to Integrate hCaptcha with WPForms

How do you integrate hCaptcha with WPForms?#

Configure WPForms' native hCaptcha integration, enter the sitekey and secret from your hCaptcha account, and enable hCaptcha on each form that needs protection. Test a valid entry and a failed evaluation before launch. WPForms performs verification as part of form processing and either blocks a flagged entry or stores it as spam, depending on the form's spam-entry setting.

This guide covers the native WPForms integration. It does not require the separate hCaptcha for WP plugin.

Keep WPForms enquiries and subscriptions moving#

• Keep attention on the submission. hCaptcha Pro's 99.9% Passive mode challenges fewer than 0.1% of legitimate users, reducing interruptions for people completing contact, subscription, and other enabled WPForms forms.
• Give suspicious activity more scrutiny. Pro adapts challenge difficulty to risk, helping you balance an easier form experience for legitimate visitors with stronger checks against automated abuse.

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.

Before you start#

You need:

• A WordPress site with WPForms installed and activated. WPForms documents hCaptcha support for WPForms Lite and paid versions.
• Administrator access to WPForms settings and permission to edit each protected form.
• Access to an hCaptcha account that can create a sitekey and securely manage its matching secret.

The sitekey identifies the site and can appear in browser-delivered configuration. The secret authorizes verification and must remain private. Do not put the secret in form markup, client-side scripts, public repositories, screenshots, or support messages.

Create your hCaptcha credentials#

1. Start with hCaptcha Pro for fewer challenges and adaptive protection on protected WPForms submissions, or use existing compatible hCaptcha credentials.
2. In the hCaptcha dashboard, create a sitekey for the WordPress site.
3. Add the hostname where the WPForms forms will run and save the sitekey.
4. Use the matching secret saved during account setup. If it is unavailable, generate a replacement in dashboard Settings, save it securely, and update integrations using the old secret; generating a new secret rotates it.
5. Store the secret in an approved credential manager until you add it to WPForms.

Use separate sitekeys for staging and production when you need independent behavior or reporting. Confirm that the sitekey covers the hostname used for testing, including a staging subdomain when applicable.

Install or update WPForms#

Use the WPForms Lite plugin page to check the current release, requirements, and installation details. Its code is available in the official WordPress plugin source repository. We also list WPForms as a native integration in the hCaptcha integration catalog.

Install WPForms through Plugins > Add New Plugin or update an existing installation through the site's normal release process. Record the WPForms and WordPress versions used for testing. If WPForms is already active, review existing CAPTCHA and spam settings before changing them.

Connect hCaptcha to WPForms#

1. In WordPress, open WPForms > Settings > CAPTCHA.
2. Select hCaptcha.
3. Paste the sitekey into Site Key.
4. Paste the matching secret into Secret Key.
5. Set the failure message that a visitor should see after an unsuccessful verification.
6. Save the settings, then confirm that the preview loads without a configuration error.

WPForms also provides No-Conflict Mode. It removes CAPTCHA code that was not loaded by WPForms, so enabling it can affect another form, theme, or plugin. Use it only after identifying a script conflict and testing every other CAPTCHA-protected flow on the site.

Enable hCaptcha on each WPForms form#

Global credentials do not protect every form automatically. Open a form in the WPForms builder and enable hCaptcha for that form by either:

• Selecting the hCaptcha field under Standard Fields; or
• Opening Settings > Spam Protection and Security and turning on Enable hCaptcha.

The hCaptcha badge in the form builder confirms that the option is enabled for that form. Save the form and repeat the step for every form that needs protection.

Review Store spam entries in the database at the same time. With storage disabled, WPForms blocks entries flagged by the configured CAPTCHA. With storage enabled, WPForms accepts the submission into the Spam section, suppresses notification emails, and blocks email-marketing actions. Choose the behavior that matches the site's review and retention process.

Verify the WPForms integration#

Test each enabled form on the page where visitors use it. A builder badge or visible widget does not prove that the complete form workflow is enforced.

1. Open the form in a private browser window and confirm that hCaptcha loads in the configured mode.
2. Complete hCaptcha and submit valid form data. Confirm that the expected entry, notification, and connected action occur once.
3. Submit without a valid evaluation. Confirm that the configured failure behavior occurs.
4. If spam storage is disabled, verify that WPForms blocks the entry. If it is enabled, verify that the entry appears under WPForms > Entries > Spam and that notifications and marketing actions do not run.
5. Repeat the tests with the site's normal cache, consent manager, security controls, and JavaScript optimization enabled.

Test payment forms separately. WPForms documents provider-specific handling for payment entries, so do not infer their result from a contact or subscription form test.

Troubleshoot common WPForms problems#

hCaptcha does not appear on the form

Open the form builder and confirm that the hCaptcha badge appears. If it does not, enable hCaptcha through the field or Spam Protection and Security settings and save the form. Then clear page, plugin, CDN, and browser caches.

The preview reports a configuration error

Confirm that the sitekey and secret were copied into the correct fields and belong to the same hCaptcha account. Check that the sitekey covers the current hostname. Replace exposed credentials before continuing.

WPForms reports corrupted post data

WPForms identifies caching, JavaScript optimization, blocked CAPTCHA scripts, AMP pages, and custom submission scripts as common causes. Check the browser console while submitting the form. Temporarily disable script delay, combination, or minification on staging to isolate the conflict, then configure the narrowest required exclusion.

A failed evaluation still appears under Entries

Check Store spam entries in the database for that form. When enabled, CAPTCHA-flagged submissions are stored under Spam instead of being discarded. They should not send notifications or run email-marketing actions unless an administrator later marks the entry as not spam.

The site loads more than one CAPTCHA script

Identify which plugin, theme, or form owns each script before using No-Conflict Mode. Removing another integration's CAPTCHA code can leave its form unprotected or broken. Enable the setting only after testing all affected forms.

Choose Pro or discuss an Enterprise deployment#

hCaptcha Pro is the self-service path for WPForms. It includes 99.9% Passive mode, custom themes, more detailed analytics, and multi-user account access. Configure the sitekey behavior in the hCaptcha dashboard, then repeat the accepted- and rejected-entry tests in WPForms.

Organizations with higher-volume form traffic, multiple WordPress properties, risk-score workflows, custom threat models, centralized access requirements, or contractual service needs should plan the deployment with our team. Those requirements can affect account ownership, credential management, monitoring, and rollout design.

FAQ#

Does WPForms include hCaptcha support?

Yes. WPForms provides a native hCaptcha integration in WPForms Lite and paid versions. Configure the credentials under WPForms > Settings > CAPTCHA, then enable hCaptcha on each selected form.

Do I need the hCaptcha for WP plugin to protect WPForms?

No. This procedure uses WPForms' native hCaptcha integration. Avoid configuring two CAPTCHA integrations on the same form unless the plugin vendors explicitly document that setup.

Does enabling hCaptcha in WPForms settings protect every form?

No. The global settings store the credentials. You must enable hCaptcha separately in each form's builder or Spam Protection and Security settings.

What happens when hCaptcha flags a WPForms entry?

WPForms blocks it by default. If Store spam entries in the database is enabled, WPForms stores it under Spam while suppressing notifications and email-marketing actions.

How do I know hCaptcha is working in WPForms?

Submit one valid entry and one entry without a valid evaluation. Confirm the valid workflow completes and the rejected entry follows the form's configured blocking or spam-storage behavior.