Revolutionary Captcha Documentation

A self-hosted, privacy-first captcha for WordPress. Stop bots on logins, comments and forms with math, slider or checkbox challenges, no Google reCAPTCHA, no third-party calls, no tracking, and a clean developer API for everything in between.

Revolutionary Captcha is a self-hosted spam shield for WordPress. It adds a quick human-verification challenge to your logins, registrations, comment forms and any custom form, then generates and validates that challenge entirely on your own server. There are no external scripts, no API keys, no cookies and no data sent to a third party.

You choose from three challenge styles, a friendly math sum, a slider you drag to confirm, or a one-tap checkbox, and apply them with simple toggles or the [revolutionary_captcha] shortcode. Because everything happens in your install, the plugin is fast, accessible and GDPR-safe out of the box.

Tip: Because no challenge ever leaves your server, Revolutionary Captcha works on staging sites, intranets and air-gapped installs where reCAPTCHA simply cannot load.

Revolutionary Captcha installs like any standard WordPress plugin, from the bundled .zip archive or directly from the Revolutionary Plugins hub.

Upload the plugin. In your WordPress admin, go to Plugins -- Add New -- Upload Plugin and choose revolutionary-captcha.zip. Click Install Now.
Activate. Once installed, click Activate. A new Captcha menu appears under the Revolutionary Plugins hub.
Pick a default challenge. Open Captcha -- Settings and choose your default challenge type. Checkbox is the lightest touch; math is the most bot-resistant.
Turn on protection. Flip the toggles for login, registration, lost-password and comments. Each takes effect immediately, no further setup required.

Good to know: There are no API keys to register. The moment you activate the plugin, the captcha is ready to use, so a fresh install can be fully protected in under a minute.

Let's add the captcha to a custom contact form and confirm it blocks an empty submission. The whole loop takes about two minutes.

Place the field. In your form markup, drop in the shortcode [revolutionary_captcha] just above the submit button. It renders the challenge with your default style.
Validate on submit. In your form handler, call revcaptcha_verify(). It returns true only when the visitor passed a valid, unexpired challenge.
Reject failures. If verification fails, stop processing and show an error. The visitor is handed a fresh challenge automatically.
Test it. Submit the form without solving the challenge. The handler should reject it. Solve it, submit again, and the entry goes through.

That is the complete pattern: render the challenge, verify it server-side, reject anything that fails. Every other integration in this guide is a variation on those three steps.

Revolutionary Captcha ships three challenge styles. Set one as your site-wide default under Captcha -- Settings, or override it per form with the revcaptcha_challenge_type filter.

Type	How it works	Best for
Checkbox	A single "I'm a human" box paired with a hidden timing and honeypot check graded on the server.	Lowest friction, high-traffic public pages
Slider	The visitor drags a handle to the end of a track to confirm. Tactile and obvious on touch devices.	Mobile-first forms, friendly tone
Math	A small arithmetic sum (for example 7 + 4) the visitor types in. Includes an audio fallback.	Maximum bot resistance, login screens

Each challenge is signed with a one-time token that ties it to the current request and expires after a configurable window. A solved token cannot be replayed on a second submission, which shuts down the most common scripted bypass.

From Captcha -- Settings -- Locations you can switch protection on for the built-in WordPress entry points without writing any code:

Login form -- adds the challenge to wp-login.php and any custom login form rendered with the WordPress functions.
Registration -- guards new-account signups against bulk bot registration.
Lost password -- stops automated password-reset floods.
Comment form -- screens the native comment form while staying compatible with full-page caching.

For everything else, the shortcode and validation helper let you protect WooCommerce checkout, membership signups, or any third-party form that exposes a submission hook.

Caching tip: On cached comment forms, the challenge token is fetched fresh over a tiny AJAX request on first interaction, so a stale cached page never serves an already-used token.

Tune how hard the challenge pushes back under Captcha -- Settings -- Behavior. Higher difficulty trades a little visitor effort for stronger bot resistance.

Difficulty: larger math operands, a longer slider track, or a stricter minimum solve time for the checkbox.
Token expiry: how long a generated challenge stays valid, from 60 seconds to 30 minutes.
Retry limit: how many failed attempts are allowed before a fresh challenge is forced.
Brute-force lockout (Pro): temporarily block an IP after a configurable run of failed login challenges.

Heads up: Setting token expiry very low (under 60 seconds) can lock out slower readers and assistive-technology users who take longer to fill a form. For public forms, leave a comfortable window.

Embed a challenge anywhere with the shortcode. With no attributes it uses your site-wide default; pass type to override the style for that one placement.

// Render the default challenge
[revolutionary_captcha]

// Force a math challenge with a custom theme class
[revolutionary_captcha type="math" theme="dark"]

In the block editor, search for "Revolutionary Captcha", insert the block, and pick the challenge style from the inspector sidebar, you'll see a live preview right in the canvas.

You can also render the field from PHP inside a template using the helper function:

if ( function_exists( 'revcaptcha_field' ) ) {
    echo revcaptcha_field( [ 'type' => 'checkbox' ] );
}

Rendering the challenge is only half the job. On the server, call revcaptcha_verify() in your submit handler before you trust the request. It reads the posted token, checks the signature, confirms the answer, and ensures the token has not expired or been used already.

if ( function_exists( 'revcaptcha_verify' ) && ! revcaptcha_verify() ) {
    wp_die(
        esc_html__( 'Please complete the human check and try again.', 'my-plugin' ),
        '',
        [ 'back_link' => true ]
    );
}

The helper returns a plain boolean, so it drops cleanly into any handler. For finer control, revcaptcha_verify( [ 'context' => 'checkout' ] ) scopes the check to a named context so each form gets its own token bucket.

Developers can shape the challenge and react to verification results through WordPress filters and actions. Use the revcaptcha_challenge_type filter to switch the style per context, here we force a stricter math challenge on the login form while leaving comments on the lightweight checkbox:

add_filter( 'revcaptcha_challenge_type', function( $type, $context ) {
    if ( 'login' === $context ) {
        return 'math';
    }
    return $type;
}, 10, 2 );

Use the revcaptcha_failed action to run custom logic, logging, alerting or rate-limiting, whenever a challenge is failed:

add_action( 'revcaptcha_failed', function( $context, $ip ) {
    error_log( sprintf( '[captcha] failed %s from %s', $context, $ip ) );
}, 10, 2 );

Other commonly used hooks include revcaptcha_passed, revcaptcha_token_lifetime (adjust expiry per context), revcaptcha_math_range (set the operand range), and revcaptcha_field_markup (wrap or restyle the rendered field).

Every challenge ships with assistive-technology support so no visitor gets locked out. The widget exposes proper aria-label and role attributes, is fully operable by keyboard, and the math challenge includes an audio fallback for visitors who cannot read the prompt.

Keyboard: the slider responds to arrow keys and the checkbox to space, so no pointer is required.
Screen readers: the prompt, current state and error messages are announced through an ARIA live region.
Audio fallback: the math challenge offers a "play audio" control that reads the sum aloud.
Reduced motion: the slider honors the visitor's prefers-reduced-motion setting.

On privacy, the plugin sets no cookies, stores no personal data and makes no outbound request. Tokens live in a short-lived server-side transient keyed only to the request, so there is nothing to disclose in a privacy policy and nothing for a cookie banner to cover.

GDPR note: Because no visitor data is collected or transmitted, Revolutionary Captcha needs no consent prompt and no data-processing agreement. It is privacy-safe by construction, not by configuration.

Most issues come down to caching or a missing validation call. Work through these first:

Challenge always fails: confirm your handler calls revcaptcha_verify() on the same context the field was rendered in, and that the form actually posts the captcha token field.
Token expired errors: raise the token-expiry window under Behavior, or exclude the form page from aggressive full-page caching so visitors do not load a stale token.
Field not showing: verify the shortcode is spelled [revolutionary_captcha] and sits inside the <form> tags, not after the closing tag.
Comment form double challenge: if another plugin already adds a captcha to comments, turn off the comment-form toggle here to avoid stacking two checks.
Slider stuck on mobile: ensure a touch-action conflict from a parent element is not capturing the drag; the field needs touch-action: none on its track.

Tip: Switch the challenge to the math type while debugging. Its pass/fail outcome is unambiguous, which makes it easy to confirm whether the issue is in rendering or in your validation call.

Yes. Challenges are generated and verified entirely on your server, so the captcha works on intranets, staging environments and air-gapped installs where an external service like reCAPTCHA could never load.

No. Challenge tokens are fetched fresh over a tiny request on first interaction, so a cached page never serves an already-used token. You can keep full-page caching on for protected forms.

Yes. Render the field with the shortcode or the revcaptcha_field() helper, then call revcaptcha_verify() on the relevant submission hook. Scope each form with a context so tokens never cross over.

For most public forms, yes. The checkbox is paired with a hidden honeypot and a minimum solve-time check, which stops the overwhelming majority of bots. On high-value targets like login, the math challenge adds an extra layer.

No. The core challenge types, location toggles, shortcode and validation API are fully functional for free. Pro unlocks brute-force lockout, fine-grained difficulty tuning and priority support across the whole suite.

DOCUMENTATION

Getting started

Challenge types

Protected locations

Difficulty & lockout

Shortcode & validation

Hooks & filters

Introduction

Installation

Protect your first form

Challenge types

Protected locations

Difficulty & lockout

Shortcode & block

Validating submissions

Hooks & filters

Accessibility & privacy

Troubleshooting

FAQ

Frequently asked questions

Was this helpful?