Developer Guide

reCaptcha for WooCommerce is extensible through hooks, filters, a public API, and the ability to register custom CAPTCHA providers.

Action hooks

cfwc_loaded

Fires after the plugin is fully initialized. Safe to extend.

add_action( 'cfwc_loaded', function() {
    // Plugin is ready
});

cfwc_register_providers

Register custom CAPTCHA providers.

add_action( 'cfwc_register_providers', function( $manager ) {
    $manager->register( 'my_provider', new My_Custom_Provider() );
});

See Custom providers below.

cfwc_before_render / cfwc_after_render

Fires before and after the CAPTCHA widget renders on a form.

add_action( 'cfwc_before_render', function( $form_type, $args ) {
    // Add custom markup before the CAPTCHA widget
}, 10, 2 );

add_action( 'cfwc_after_render', function( $form_type, $args ) {
    // Add custom markup after the CAPTCHA widget
}, 10, 2 );

cfwc_before_verify

Fires before CAPTCHA verification begins.

add_action( 'cfwc_before_verify', function( $form_type ) {
    // Log or modify state before verification
});

cfwc_verified

Fires on successful CAPTCHA verification.

add_action( 'cfwc_verified', function( $form_type, $result ) {
    // Log successful verification, update stats, etc.
}, 10, 2 );

cfwc_failed

Fires on failed CAPTCHA verification.

add_action( 'cfwc_failed', function( $form_type, $error ) {
    // Custom logging, notifications, etc.
    // $error is a WP_Error object
}, 10, 2 );

Filter hooks

cfwc_skip_verification

Skip CAPTCHA for specific conditions.

add_filter( 'cfwc_skip_verification', function( $skip, $form_type, $context ) {
    // Skip CAPTCHA on checkout for orders over $500 (trust high-value customers)
    if ( $form_type === 'wc_checkout_block' && WC()->cart->get_total( 'edit' ) > 500 ) {
        return true;
    }
    return $skip;
}, 10, 3 );

cfwc_form_enabled

Override whether a form type is protected.

add_filter( 'cfwc_form_enabled', function( $enabled, $form_type ) {
    // Disable CAPTCHA on login during business hours
    if ( $form_type === 'wc_login' ) {
        $hour = (int) current_time( 'G' );
        if ( $hour >= 9 && $hour < 17 ) {
            return false;
        }
    }
    return $enabled;
}, 10, 2 );

cfwc_supported_forms

Add custom form types to the supported forms list.

add_filter( 'cfwc_supported_forms', function( $forms ) {
    $forms['my_custom_form'] = [
        'label'    => 'My Custom Form',
        'category' => 'custom',
    ];
    return $forms;
});

cfwc_error_message

Customize error messages shown to users.

add_filter( 'cfwc_error_message', function( $message, $code, $provider ) {
    if ( $code === 'verification_failed' ) {
        return 'Security check failed. Please try again.';
    }
    return $message;
}, 10, 3 );

cfwc_widget_container_class

Customize the CSS class on the CAPTCHA widget container.

add_filter( 'cfwc_widget_container_class', function( $class, $form_type ) {
    return $class . ' my-custom-class';
}, 10, 2 );

cfwc_verification_request_body

Modify the API request body sent to the CAPTCHA provider.

add_filter( 'cfwc_verification_request_body', function( $body, $provider_id ) {
    // Add custom parameters
    $body['custom_param'] = 'value';
    return $body;
}, 10, 2 );

cfwc_verification_timeout

Adjust the API request timeout (default 30 seconds).

add_filter( 'cfwc_verification_timeout', function( $timeout, $provider_id ) {
    return 10; // 10 seconds
}, 10, 2 );

cfwc_should_load_assets

Force CAPTCHA assets to load on specific pages (assets normally only load on pages with protected forms).

add_filter( 'cfwc_should_load_assets', function( $should_load ) {
    if ( is_page( 'custom-checkout' ) ) {
        return true;
    }
    return $should_load;
});

cfwc_settings_fields

Modify the settings page fields.

add_filter( 'cfwc_settings_fields', function( $settings ) {
    // Add or modify settings
    return $settings;
});

cfwc_recaptcha_v3_threshold

Override the reCAPTCHA v3 score threshold programmatically.

add_filter( 'cfwc_recaptcha_v3_threshold', function( $threshold ) {
    return 0.7; // Stricter than default
});

cfwc_honeypot_min_time

Override the honeypot minimum submission time.

add_filter( 'cfwc_honeypot_min_time', function( $min_time ) {
    return 5; // 5 seconds instead of default 3
});

Public API

Access the plugin instance and its components:

$plugin = CFWC\Plugin::instance();

Render CAPTCHA on a custom form

// In your form template
$plugin->render( 'my_custom_form', [
    'container_class' => 'my-captcha-wrapper',
] );

Verify CAPTCHA on form submission

// In your form handler
$result = $plugin->verify( 'my_custom_form' );

if ( is_wp_error( $result ) ) {
    // Verification failed
    $error_message = $result->get_error_message();
} else {
    // Verification passed, process form
}

Access settings

$settings = $plugin->settings();

$provider    = $settings->get( 'provider' );
$site_key    = $settings->get( 'site_key' );
$is_debug    = $settings->get( 'enable_debug_logging' );

Access provider manager

$providers = $plugin->providers();

// Get active provider
$active = $plugin->provider();

// Get all registered providers
$all = $providers->get_all();

// Check if a provider is registered
$exists = $providers->has( 'turnstile' );

Custom providers

You can register your own CAPTCHA provider by implementing the Provider_Interface:

use CFWC\Providers\Provider_Interface;

class My_Custom_Provider implements Provider_Interface {

    public function get_id(): string {
        return 'my_provider';
    }

    public function get_name(): string {
        return 'My Custom Provider';
    }

    public function get_description(): string {
        return 'Description of my provider';
    }

    public function requires_api_keys(): bool {
        return true;
    }

    public function render( string $form_type, array $args = [] ): void {
        // Output the CAPTCHA widget HTML
    }

    public function verify(): bool|\WP_Error {
        // Verify the CAPTCHA response
        // Return true on success, WP_Error on failure
    }

    public function enqueue_assets(): void {
        // Enqueue JS/CSS for the widget
    }
}

Register it during cfwc_register_providers:

add_action( 'cfwc_register_providers', function( $manager ) {
    $manager->register( 'my_provider', new My_Custom_Provider() );
});

The custom provider will appear in the provider dropdown on the settings page.

Logging

When debug logging is enabled, the plugin logs to WooCommerce's logging system:

• Verification attempts (success and failure)
• Rate limit events (lockouts, releases)
• Provider errors (API timeouts, invalid responses)
• IP blocklist matches

View logs at WooCommerce > Status > Logs and filter by source captcha-for-woocommerce.

// Access the logger programmatically
$logger = CFWC\Plugin::instance()->logger();
$logger->info( 'Custom log message', [ 'context' => 'value' ] );

Form type identifiers

When working with hooks, use these form type string identifiers: