Compatibility

reCaptcha for WooCommerce is built for WooCommerce's modern architecture. This page covers compatibility with Block Checkout, PayPal Payments, express payment methods, HPOS, and common plugin conflicts.

Block Checkout

The plugin fully supports WooCommerce's block-based checkout (the default since WooCommerce 8.3).

How it works

Unlike plugins that inject CAPTCHA via DOM manipulation (which breaks on React re-renders), this plugin integrates through the official Store API:

• Widget rendering: The CAPTCHA widget is injected using the render_block_woocommerce/checkout filter, placing it before the Place Order button.
• Token passing: The client-side JavaScript passes the CAPTCHA token through extensions['captcha-for-woocommerce']['token'] in the Store API checkout request.
• Server validation: The token is verified during woocommerce_store_api_checkout_update_order_from_request, before payment processing begins.

The plugin declares Block Checkout compatibility via FeaturesUtil::declare_compatibility('cart_checkout_blocks', ...).

Verification

After a successful Block Checkout order, the plugin stores verification metadata on the order:

• _cfwc_captcha_verified -- whether CAPTCHA passed
• _cfwc_captcha_provider -- which provider verified
• _cfwc_captcha_timestamp -- when verification occurred

---

WooCommerce PayPal Payments

WooCommerce PayPal Payments (the official PayPal plugin) has its own built-in reCAPTCHA system as of 2024. Running a separate CAPTCHA on checkout alongside PayPal's reCAPTCHA causes double verification, which frequently breaks the payment flow.

Auto-detection

The plugin automatically detects when PayPal Payments reCAPTCHA is active by checking the woocommerce_ppcp-recaptcha_settings option. When detected:

• CAPTCHA verification is skipped for PayPal payment methods: ppcp-gateway, ppcp-credit-card-gateway, ppcp-card-button-gateway
• Non-PayPal payment methods (Stripe, bank transfer, etc.) are still protected
• An info notice appears on the CAPTCHA settings page explaining the integration

What this means in practice

A customer paying with Stripe sees your CAPTCHA. A customer paying with PayPal is protected by PayPal's own reCAPTCHA. Both paths are protected without conflicts.

Customizing PayPal method detection

If you use a custom PayPal gateway ID or need to add/remove methods from the skip list:

add_filter( 'cfwc_paypal_protected_methods', function( $methods ) {
    $methods[] = 'my_custom_paypal_gateway';
    return $methods;
});

PayPal reCAPTCHA settings

PayPal's built-in reCAPTCHA is configured at WooCommerce > Settings > Integration > WooCommerce PayPal Payments CAPTCHA. It requires both v3 and v2 Google reCAPTCHA keys. The plugin checks whether this is fully configured before skipping verification.

---

Express payment methods

Express payments (Apple Pay, Google Pay, Amazon Pay, Link by Stripe) use native wallet interfaces that bypass the normal checkout form. CAPTCHA widgets injected into the form have no effect on these flows.

Automatic skip

The plugin automatically skips CAPTCHA verification for express payment methods because:

• Express payments open their own secure wallet UI outside the browser form
• Injecting CAPTCHA into the wallet flow is technically impossible
• These payment methods have their own fraud detection (Apple Pay requires Face ID/Touch ID, Google Pay requires device authentication)

Supported express methods

Customizing the skip list

add_filter( 'cfwc_express_payment_methods', function( $methods ) {
    $methods[] = 'my_custom_express_method';
    return $methods;
});

Per-method control

For fine-grained control over which payment methods skip CAPTCHA:

add_filter( 'cfwc_skip_for_payment_method', function( $skip, $payment_method ) {
    if ( $payment_method === 'stripe' ) {
        return false; // Always require CAPTCHA for regular Stripe
    }
    return $skip;
}, 10, 2 );

---

HPOS (High-Performance Order Storage)

The plugin declares HPOS compatibility via FeaturesUtil::declare_compatibility('custom_order_tables', ...). It works correctly with both the legacy wp_posts order storage and the newer custom order tables.

Order metadata (_cfwc_captcha_verified, _cfwc_captcha_provider, _cfwc_captcha_timestamp) is written using WooCommerce's order meta API, which handles the storage backend automatically.

---

Multisite

The plugin is multisite-aware:

• Activation: Can be activated per-site or network-wide
• Settings: Stored per-site (each site has its own CAPTCHA configuration)
• Uninstall: Respects the "delete data on uninstall" setting across all network sites

---

Failsafe mode

If the external CAPTCHA provider is temporarily unreachable (API downtime, network issues), the failsafe setting controls what happens:

Configure at WooCommerce > Settings > CAPTCHA > Advanced > Failsafe Mode.

The recommended setting is "Use honeypot fallback." This maintains bot protection even during provider outages without blocking legitimate customers.

---

Known plugin conflicts

Caching plugins

CAPTCHA tokens are time-sensitive. If your page caching serves a cached CAPTCHA token, verification will fail. Most caching plugins handle this correctly by excluding checkout and account pages. If you see consistent CAPTCHA failures:

• Ensure checkout and My Account pages are excluded from page caching.
• Ensure the cfwc_nonce and CAPTCHA provider cookies are excluded from cache key generation.

Other CAPTCHA plugins

Running two CAPTCHA plugins simultaneously on the same form will cause conflicts. If you're switching from another CAPTCHA plugin, deactivate the old one first.

Security plugins with built-in CAPTCHA

Wordfence, iThemes Security, and similar plugins may have their own CAPTCHA on login forms. Disable their CAPTCHA on forms where this plugin is active, or disable this plugin's protection on those forms.