Themology
Docs Bouncer

FAQ

Frequently Asked Questions#

General questions#

What does this plugin do?#

Bouncer adds bot protection and fraud prevention to your WooCommerce store’s checkout, login, registration, and other forms. It supports five CAPTCHA providers (Cloudflare Turnstile, Google reCAPTCHA v3, Google reCAPTCHA v2, hCaptcha, and a self-hosted honeypot) and includes a 9-rule fraud scoring engine with disposable email detection, proxy/VPN detection, and geo-based blocking. Add rate limiting, country-level access control, and IP management on top of that.

Do I need API keys?#

For Cloudflare Turnstile, Google reCAPTCHA (v2 or v3), and hCaptcha, yes. All providers offer free tiers. The self-hosted Honeypot requires no API keys and makes no external calls.

Which provider should I use?#

  • Cloudflare Turnstile for most stores. Free, invisible, privacy-friendly.
  • Google reCAPTCHA v3 if you want score-based invisible verification and are already in the Google ecosystem.
  • Google reCAPTCHA v2 if you want visible “I’m not a robot” confirmation.
  • hCaptcha for a privacy-focused alternative to Google.
  • Honeypot for GDPR-strict stores or if you want zero external service dependencies.

See CAPTCHA Providers for a detailed comparison.

Does it work with Block Checkout?#

Yes. The plugin integrates with Block Checkout through the official WooCommerce Store API, not DOM injection. It works reliably with the React-based checkout without breaking on re-renders.

Does it work with PayPal Payments?#

Yes. The plugin automatically detects when WooCommerce PayPal Payments has its own reCAPTCHA enabled and skips CAPTCHA for PayPal payment methods to prevent double verification conflicts. Other payment methods remain protected.

Does it work with Apple Pay / Google Pay?#

Yes. Express payment methods are automatically skipped because they use their own secure wallet authentication (Face ID, Touch ID, device PIN). The plugin detects these methods and lets them through without CAPTCHA.

How does fraud scoring work?#

Every checkout order is evaluated against 9 configurable rules (disposable emails, proxy/VPN, geo mismatch, velocity, and more). Each rule has a weight that contributes to a score from 0 to 100. Orders above your threshold are automatically held, cancelled, or flagged. See Fraud Scoring for the full breakdown.

Can I block orders from specific countries?#

Yes, two ways. Geo-blocking prevents visitors from selected countries from accessing your site entirely. Country-based CAPTCHA exclusion skips CAPTCHA for trusted countries (reducing friction) while keeping it for everyone else. See Geo Protection.

Does it detect disposable email addresses?#

Yes. The plugin ships with 780+ known disposable email domains. When someone uses a throwaway email at checkout, the order can be blocked, flagged, or a warning shown. You can also add your own patterns with wildcard matching.

Does it work with Elementor Pro?#

Yes. When Elementor Pro is active, you can enable CAPTCHA on Elementor’s Form widget from the settings.

Does it work with WooCommerce Bookings?#

Yes. The booking add-to-cart form can be protected. CAPTCHA only appears on bookable products.

Can I protect custom forms?#

Yes. Use the [cfwc_captcha] shortcode to drop a CAPTCHA widget into any page or template. The shortcode includes an AJAX verification endpoint for custom form handlers. Developers can also use the cfwc_supported_forms filter to register entirely custom form types.

What’s the difference between per-IP and global rate limiting?#

Per-IP rate limiting blocks individual IPs after too many failures. Global rate limiting watches total site-wide traffic and blocks everyone temporarily when the overall failure rate spikes. Use both together: per-IP catches repeat offenders, global catches distributed attacks spread across many IPs.

Setup questions#

How do I get Cloudflare Turnstile keys?#

  1. Go to dash.cloudflare.com/turnstile.
  2. Click Add widget.
  3. Enter your site name and domain.
  4. Select Managed mode.
  5. Copy the Site Key and Secret Key.

You do not need a Cloudflare-proxied domain. Turnstile works on any site.

How do I test that CAPTCHA is working?#

  1. Enable at least one form (start with checkout).
  2. Open your store in a private/incognito browser window.
  3. Navigate to the protected form.
  4. For visible providers (reCAPTCHA v2, hCaptcha), you should see the widget.
  5. For invisible providers (Turnstile, reCAPTCHA v3, Honeypot), submit the form normally. It should work for real users.
  6. Check the dashboard widget at Dashboard > CAPTCHA Protection for verification activity.

How do I know which forms to protect?#

Start with:

  • WooCommerce Checkout (both Classic and Block) — protects against carding attacks
  • WooCommerce My Account Login — protects against brute force
  • WooCommerce My Account Registration — protects against spam accounts

Add more forms based on your threat profile. See Protected Forms for the full list.

Can I use different providers for different forms?#

No. The plugin uses one active provider for all forms. This is intentional: consistent behavior is easier to test and debug. You can skip CAPTCHA for specific forms using the settings checkboxes or the cfwc_form_enabled filter.

Troubleshooting#

CAPTCHA verification fails for every user#

  1. Check API keys. Use the “Test Connection” button on the settings page.
  2. Check domain. Your CAPTCHA provider keys must be registered for the exact domain your site uses (including www vs non-www).
  3. Check caching. Page caching that serves stale CAPTCHA tokens will cause failures. Exclude checkout and account pages from caching.
  4. Enable debug logging. Go to Advanced settings, enable logging, reproduce the issue, then check WooCommerce > Status > Logs.

CAPTCHA blocks legitimate customers#

  1. Lower the score threshold if using reCAPTCHA v3. Default 0.5 works for most stores. Try 0.3 if customers on VPNs or shared networks are affected.
  2. Whitelist roles for logged-in customers who are being blocked. Go to Access Control and add their role.
  3. Check rate limiting settings. If the lockout window is too aggressive, legitimate users who mistype their password may get locked out.

CAPTCHA widget doesn’t appear#

  1. Check the provider. Invisible providers (reCAPTCHA v3, Honeypot) don’t show a visible widget. Only Turnstile (sometimes), reCAPTCHA v2, and hCaptcha show visible elements.
  2. Check the form setting. Verify the specific form is checked under Protected Forms.
  3. Check for JavaScript errors. Open browser developer tools (F12) and look for errors in the Console tab.
  4. Check asset loading. The plugin only loads scripts on pages with protected forms. If you’re using a custom checkout page, you may need the cfwc_should_load_assets filter.

Checkout breaks after installing#

  1. PayPal conflict. If you use WooCommerce PayPal Payments with its reCAPTCHA enabled, the plugin should auto-detect this. Verify auto-detection is working by checking for the info notice on the settings page.
  2. Express payments. Verify the plugin correctly skips CAPTCHA for Apple Pay, Google Pay, etc. Check that the express payment method IDs are in the skip list.
  3. Another CAPTCHA plugin. Two CAPTCHA plugins on the same form will conflict. Deactivate the other plugin.
  4. Failsafe mode. If the CAPTCHA provider is down, check your failsafe setting. “Use honeypot fallback” prevents blocking all customers.

Fraud scoring held an order incorrectly#

Check the fraud score meta box on the order edit screen. It shows exactly which rules fired and their weighted scores. If a specific rule is too aggressive, lower its weight or disable it at WooCommerce > Settings > Bouncer > Fraud. For returning customers who shouldn’t be scored, enable the “Skip returning customers” option.

Rate limiting locks out my office#

Add your office IP to the whitelist at WooCommerce > Settings > Bouncer > Security > IP Whitelist. Whitelisted IPs bypass both CAPTCHA and rate limiting.

Privacy and compliance#

Is this GDPR compliant?#

It depends on your provider choice:

  • Honeypot: Fully GDPR compliant. No external data transfer, no cookies.
  • Cloudflare Turnstile and hCaptcha: GDPR-friendly. Both have published GDPR compliance documentation.
  • Google reCAPTCHA: Transfers data to Google servers. Requires disclosure in your privacy policy and potentially cookie consent.

What data is sent to the CAPTCHA provider?#

For external providers (all except Honeypot), the following is typically sent:

  • The visitor’s IP address
  • Browser user agent
  • The CAPTCHA response token
  • Your site key

No personal information like names, emails, or order details is sent to the CAPTCHA provider.

For Google reCAPTCHA, potentially yes, depending on your jurisdiction. Cloudflare Turnstile and hCaptcha have more privacy-friendly cookie practices. The Honeypot does not set any cookies.

The settings page includes a dynamic privacy section showing the data handling details for your selected provider.

Technical questions#

Is it compatible with HPOS?#

Yes. The plugin declares HPOS compatibility and works with both the legacy and custom order tables storage backends.

Does it work with WordPress multisite?#

Yes. Each site in the network has its own CAPTCHA settings. The plugin can be activated per-site or network-wide.

Can developers extend it?#

Yes. The plugin provides action hooks, filter hooks, a public API for rendering and verifying CAPTCHA on custom forms, and the ability to register custom CAPTCHA providers. There are also fraud-specific hooks: cfwc_fraud_rules to register custom scoring rules and cfwc_fraud_score_result to modify scores before they’re saved. The [cfwc_captcha] shortcode lets you drop a CAPTCHA widget into any page or template. See the Developer Guide.

Where are settings stored?#

Settings are stored in the cfwc_settings option in the WordPress options table. Individual settings are also mirrored to WooCommerce options with the cfwc_ prefix.

Is data deleted when I deactivate?#

No. Deactivation preserves all settings. If you want a clean uninstall, enable “Delete data on uninstall” in Advanced settings before deleting the plugin.

Support#

Where can I get help?#

  • Themology Support: Bug reports, feature requests, and critical support.
  • Plugin documentation: You’re reading it!

How do I report a bug?#

Submit via Themology Support with:

  • WordPress version
  • WooCommerce version
  • Plugin version
  • CAPTCHA provider in use
  • Steps to reproduce
  • Browser developer console errors (if applicable)