How to Integrate hCaptcha with Ninja Forms

How do you integrate hCaptcha with Ninja Forms?#

Configure Ninja Forms' native hCaptcha integration under Ninja Forms > Settings > hCaptcha, add the hCaptcha field to each form you want to protect, and publish the form. Test a successful submission and one without a valid evaluation. Ninja Forms verifies the response with hCaptcha on the server and returns a form error when verification fails.

This guide covers the native field included in Ninja Forms 3.12.0 and later. It does not require the separate hCaptcha for WP plugin.

Reduce CAPTCHA friction on Ninja Forms#

• 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 enquiries and other submissions through forms containing the native hCaptcha field.
• 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:

• Ninja Forms 3.12.0 or later installed and activated on WordPress. The hCaptcha field is part of the core plugin.
• Administrator access to Ninja Forms settings and permission to edit and publish the protected forms.
• An hCaptcha account that can create a sitekey and securely manage its matching secret.

These instructions were last validated on September 22, 2026 with Ninja Forms 3.15.4 on its documented WordPress and PHP requirements.

Check the current Ninja Forms plugin listing before installation or upgrade.

The sitekey is sent to the browser so hCaptcha can render. The secret authorizes server-side verification and must remain private. Do not add it to 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 Ninja Forms submissions, or use existing compatible hCaptcha credentials.
2. Create a sitekey for the WordPress site in the hCaptcha dashboard.
3. Add the hostname where the Ninja Forms forms will run.
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 WordPress.

Use separate sitekeys for staging and production when the environments need independent settings or reporting. Include the staging hostname on its assigned sitekey before testing.

Install or update Ninja Forms#

Check the official Ninja Forms plugin page for the current release and requirements. The plugin code is available through the WordPress source repository. Ninja Forms also appears in the hCaptcha integration catalog and the hCaptcha integrations-list repository.

Install Ninja Forms through Plugins > Add New Plugin or update it through the site's release process. Record the WordPress, PHP, and Ninja Forms versions used during testing. If the form builder does not show an hCaptcha field, confirm that the installed Ninja Forms version is 3.12.0 or later.

Connect hCaptcha to Ninja Forms#

1. In WordPress, open Ninja Forms > Settings > hCaptcha.
2. Paste the sitekey into hCaptcha Site Key.
3. Paste the matching secret into hCaptcha Secret Key.
4. Choose the default light or dark theme.
5. Choose the default normal or compact widget size.
6. Save the settings.

Choose the sitekey's widget mode and passing threshold in the hCaptcha dashboard. Ninja Forms documents support for all modes and thresholds that are available on the selected hCaptcha plan. Theme and size defaults apply across Ninja Forms but can be overridden on an individual form.

Add hCaptcha to each Ninja Form#

Global credentials do not protect a form until it contains the hCaptcha field.

1. Open the form in the Ninja Forms builder.
2. Select Add New Field.
3. Under Miscellaneous Fields, choose hCaptcha.
4. Drag the field to the required position, normally before the submit button.
5. Open the field settings if the form needs a different theme, size, or label visibility from the global defaults.
6. Publish the form, then preview it or refresh the page where it appears.

Do not put hCaptcha and another CAPTCHA service on the same form. Ninja Forms documents that hCaptcha can run alongside other anti-spam tools such as Akismet, but competing CAPTCHA fields can interfere with the form workflow.

How Ninja Forms verifies hCaptcha#

The native field performs server-side verification during form processing. Ninja Forms sends the secret, the submitted hCaptcha response, and the visitor IP address to https://api.hcaptcha.com/siteverify using a server-side POST request.

The form returns an error when the response is missing or unsuccessful. It also reports an expired evaluation, a reused response, or a missing or invalid secret without completing the normal protected submission. The secret remains in the WordPress settings and is not added to the page.

Verify the Ninja Forms integration#

Test each protected form at its public location. A widget that renders successfully confirms only the browser portion of the integration.

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 success message, email, record, redirect, or connected action occurs once.
3. Submit without a valid hCaptcha evaluation. Confirm that Ninja Forms shows a verification error and does not run the protected form actions.
4. Allow an evaluation to expire or reload the form after completing it, then confirm that the stale response is rejected.
5. Repeat the tests with the site's normal caching, consent, security, and JavaScript optimization settings enabled.

Test each form separately. Theme templates, popups, conditional fields, and embedded forms can load scripts differently even when they share the same global credentials.

Troubleshoot common Ninja Forms problems#

The hCaptcha field is missing from the builder

Confirm that Ninja Forms 3.12.0 or later is active. Then open Add New Field and look under Miscellaneous Fields. Clear the WordPress administration cache and reload the builder after an update.

The form says the secret is not configured

Open Ninja Forms > Settings > hCaptcha and enter the secret from the same hCaptcha account as the sitekey. Save the settings and replace the secret if it was exposed.

Visitors receive an expired-verification error

Ask the visitor to complete hCaptcha again and resubmit. Ninja Forms returns this result when the verification request fails or hCaptcha reports an expired or duplicate response. Check outbound connectivity and server logs if fresh evaluations fail repeatedly.

The widget does not load on the public form

Confirm that the form contains the hCaptcha field and that its latest version is published. Clear site, CDN, and browser caches. Check the browser console and Content Security Policy reports for a blocked hCaptcha script. Temporarily remove script delay or combination on staging to isolate an optimization conflict.

A form contains another CAPTCHA field

Remove one CAPTCHA integration and retest the form. Keep other non-CAPTCHA anti-spam controls only when their vendors document compatibility with the form workflow.

Choose Pro or discuss an Enterprise deployment#

hCaptcha Pro is the self-service path for Ninja Forms. It includes 99.9% Passive mode, custom themes, more detailed analytics, and multi-user account access. Set the sitekey behavior in the hCaptcha dashboard, then repeat the successful- and failed-submission tests.

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 Ninja Forms include native hCaptcha support?

Yes. Ninja Forms added its native hCaptcha field in version 3.12.0. Update older installations before following this procedure.

Do I need the hCaptcha for WP plugin with Ninja Forms?

No. This procedure uses the native field in Ninja Forms. Avoid adding two CAPTCHA integrations to the same form.

Does entering the sitekey and secret protect every Ninja Form?

No. The credentials apply globally, but you must add the hCaptcha field to each form that needs protection and publish the form.

Does Ninja Forms verify hCaptcha on the server?

Yes. The native field sends the submitted response to hCaptcha's verification endpoint using the stored secret and returns a form validation error when verification fails.

Can I change the hCaptcha appearance for one Ninja Form?

Yes. Set global theme and size defaults under Ninja Forms settings, then override the theme, size, or label visibility in the hCaptcha field settings for an individual form.