Skip to content

WordPress Plugin

The EU CAPTCHA WordPress plugin integrates the EU CAPTCHA widget and server-side verification into your WordPress site with no custom code required. It supports WordPress core forms and several popular form plugins out of the box.

  • Version: 1.0.0
  • Requires: WordPress 5.8+, PHP 7.4+
  • Tested up to: WordPress 6.9
  • License: GPL-2.0-or-later
  • Download: eu-captcha.zip

Supported forms

Form Plugin required
WordPress Login —
WordPress Registration —
WordPress Comments —
Contact Form 7 Contact Form 7
Ninja Forms Ninja Forms
WooCommerce Checkout WooCommerce
WPForms WPForms

We are happy to include support for more plugins. Please contact support if you need additional plugins supported.

Installation

  1. Download eu-captcha.zip and upload it via Plugins → Add New Plugin → Upload Plugin in the WordPress admin, or extract and upload the eu-captcha folder to /wp-content/plugins/ via FTP.
  2. Activate the plugin through Plugins in the WordPress admin.
  3. Go to the EU-Captcha settings page (appears in the left menu at position 31, below Settings).
  4. Configure your credentials — use Quick Setup or enter them manually (see below).
  5. Under Protected Destinations, tick every form you want to protect.
  6. Click Save Changes.

Configuration

Quick Setup

Click Quick Setup on the settings page. A modal opens loading the EU CAPTCHA dashboard in an embedded iframe. Complete the registration flow inside the modal — the plugin receives your sitekey and secret automatically via postMessage and saves them without you copying anything.

Manual credentials

If you already have a sitekey and secret from the dashboard, enter them directly in the API Settings section.

Field Description
Sitekey Your public sitekey (UUID format). Safe to display on the frontend.
Secret Your secret key (Base64 format). Stored in the WordPress options table — never sent to the browser.

Protected destinations

Check each form type you want to protect. The widget is injected and server-side verification is enforced only for the destinations you enable. Supported values:

  • WordPress Login
  • WordPress Register Account
  • WordPress Post/Comment Page
  • Contact Form 7
  • Ninja Forms
  • WooCommerce Checkout
  • WPForms

API options

Option Default Description
Check CDN / Proxy Headers On When enabled, the plugin reads the visitor's real IP from HTTP_CLIENT_IP, HTTP_X_FORWARDED_FOR, or HTTP_X_REAL_IP before falling back to REMOTE_ADDR. Enable this if your site sits behind a CDN or load balancer.
Failsafe Off When disabled (default), a network error reaching the verification API causes the form submission to be blocked. When enabled, transport-level errors (timeouts, DNS failures) are treated as a passed verification so submissions go through. Invalid tokens are still rejected regardless of this setting.

Widget Styling

Option Default Description
Theme Light Controls the widget colour scheme. Choose Light or Dark.
Height (px) — Optional fixed height in pixels (minimum 48). Leave empty to use the widget default.
Width (px) — Optional fixed width in pixels (minimum 1). Leave empty to use the widget default.

How it works

  1. The plugin enqueues https://cdn.eu-captcha.eu/verify.js (with async defer) on every frontend page and on the login/registration screens.
  2. It injects <div class="eu-captcha" data-sitekey="..."> inside each enabled form.
  3. On form submission, it reads $_POST['eu-captcha-response'] and sends a server-side request to https://api.eu-captcha.eu/v1/verify with the token, visitor IP, and User-Agent.
  4. Submissions are accepted or rejected based on the API response.

Custom integration

If you want to add EU CAPTCHA protection to a form that the plugin does not handle natively, use the global eu_captcha_verify() function.

1. Render the widget in your form template:

<div class="eu-captcha" data-sitekey="EUCAPTCHA_SITE_KEY"></div>

The verify.js script is already enqueued on all frontend and login pages when the plugin is active, so no additional script tag is needed.

2. Verify the token on submission:

if ( function_exists( 'eu_captcha_verify' ) ) {
    $token  = sanitize_text_field( $_POST['eu-captcha-response'] );
    $result = eu_captcha_verify( $token );
    if ( ! $result ) {
        wp_die( 'Captcha verification failed.' );
    }
}

eu_captcha_verify() uses the sitekey and secret already stored in the plugin settings. It returns true on success and false on failure (invalid token, missing credentials, or API error with failsafe disabled). Always guard the call with function_exists() so your code degrades gracefully if the plugin is deactivated.

Third-party services

The plugin communicates with the following external hosts:

Host Purpose
cdn.eu-captcha.eu Loads verify.js on pages with protected forms
api.eu-captcha.eu Server-side token verification on each form submission
app.eu-captcha.eu EU CAPTCHA dashboard loaded in the Quick Setup iframe

EU CAPTCHA sets no cookies and collects no personal data in the browser, making it GDPR-compliant without a cookie banner. Data sent to api.eu-captcha.eu on each verification: sitekey, secret, captcha response token, visitor IP address, visitor User-Agent string. Refer to the EU CAPTCHA Privacy Policy for details on how this data is processed.

Troubleshooting

The widget does not appear on a form

  • Confirm the destination is ticked in Protected Destinations and that you clicked Save Changes.
  • Check that the sitekey is saved correctly (UUID format). The settings page highlights the field in red if the format is invalid.
  • Open browser DevTools → Network and verify verify.js loaded without errors.
  • If a Content Security Policy is active, add cdn.eu-captcha.eu to script-src and connect-src.

Form submissions are blocked even for real users

  • Verify the sitekey and secret are correct. An incorrect secret causes the API to return train: true, which the plugin treats as a failure.
  • Check that the sitekey was created for this domain. Each sitekey is tied to the domain specified at creation — create a new sitekey if needed.

Submissions always pass even for empty tokens

  • Confirm the secret is correct. A wrong secret puts the API into bypass mode (train: true) where all submissions appear successful.

The plugin blocks all submissions when your CDN is active

  • Enable Check CDN / Proxy Headers in API Settings so the plugin forwards the real visitor IP rather than the CDN's address.

What happens during an EU CAPTCHA outage?

By default the plugin blocks submissions when the API is unreachable (fail closed). Enable Failsafe to accept submissions during outages (fail open). See the Failsafe option above.