Checkout Bouncer

FAQ

Which checkout types are supported?

All of them.

• The classic [woocommerce_checkout] shortcode checkout.
• The WooCommerce Checkout block, verified through the Store API — a surface several widely-installed captcha plugins still miss.
• The pay for order page, used by emailed payment links.
• The add payment method page, where signed-in customers save a card (optional, off by default).

A checkout page built with Elementor, Divi, WPBakery, Beaver Builder, Bricks or Oxygen is recognised too — the scanner looks inside the builder’s own saved layout to find the checkout element and reports which builder it found.

Does it work with the block checkout?

Yes, and this is the reason Checkout Bouncer exists. The block checkout does not submit an HTML form; it posts JSON to the WooCommerce Store API. Checkout Bouncer registers proper Store API extension data so the reCAPTCHA token travels with the order, then verifies it on the checkout request. A failed check is turned into a clean error in the block UI, and no charge is attempted.

If your WooCommerce is too old to register Store API extension data, Checkout Bouncer cannot attach a token — so it tells you plainly and offers to block the route instead, which is the honest answer rather than a checkbox that does nothing.

Can it block the Store API?

Yes. If your customers check out through the classic form, the Store API checkout route is an open door you are not using, and Checkout Bouncer can return a 404 or a 403 for every request to it. Store staff and allowlisted IP addresses are always let through.

Be careful with this one: blocking the route disables the block checkout, the WooCommerce mobile app and any headless front end. The scanner spells that out before you switch it on, and if you block the route while your own checkout page uses the block, Checkout Bouncer raises a critical warning with a one-click undo.

What happens if Google is down or unreachable?

You decide, with the fail open setting.

• Fail open (default). If Google cannot be reached, times out, or answers with something unreadable, the order is allowed through and the event is logged as a soft failure. Your store keeps taking money during a Google outage.
• Fail closed. The order is rejected instead. Safer, but a Google outage becomes your outage.

Genuine “our end” problems — a malformed request, a bad secret key — are always treated as soft failures rather than punishing the shopper for your configuration.

Why do I have to keep the reCAPTCHA badge, or show the attribution text?

Google’s terms require that visitors are told reCAPTCHA is in use. You can satisfy that in one of two ways, and Checkout Bouncer supports both:

• Leave the floating reCAPTCHA badge visible (the default). Nothing else needed.
• Switch on Hide badge, and Checkout Bouncer automatically prints the required sentence near your place-order button: “This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.” — with both links, wired in five different places so a theme that drops the WooCommerce hooks cannot make it disappear.

Hiding the badge without that sentence breaks Google’s terms. Checkout Bouncer will not let that happen, and you do not need to add the sentence yourself — if you do, you will end up with two.

What score threshold should I use?

Start at 0.5, which is Google’s own recommendation and the Checkout Bouncer default, and leave it there for a week while you watch the Logs tab.

• Scores run from 0.00 (almost certainly a bot) to 1.00 (almost certainly a human).
• 0 verifies nothing — every visitor passes. Tokens are still checked and scores are still recorded, so it is a legitimate way to gather data before arming the plugin, but it rejects nobody. The scanner will warn you it is on.
• 0.9 and above will reject real customers. Genuine shoppers on phones, on VPNs, or behind a corporate network routinely score below that. The scanner warns about this too.

Raise it slowly, one notch at a time, and watch your low-score rows for orders that look human.

Will it block real customers?

That is the failure mode to watch, and Checkout Bouncer is built to make it visible rather than silent. Every decision is logged with its score and the threshold in force, every order gets a note explaining what happened, and the scanner actively warns you when your threshold is set high enough to cause trouble. If in doubt, set fail open, keep the threshold at 0.5, and read the logs for a week.

Does it work with caching, or behind Cloudflare?

Yes, with two things worth knowing.

Caching. reCAPTCHA v3 tokens are minted in the browser and expire after 120 seconds, so a cached checkout page is not a correctness problem — the token is generated fresh on page load and refreshed on a timer (100 seconds by default). The one real failure case is a page cache so aggressive that it serves a checkout page whose scripts were never enqueued, and the default Script loading scope of every page already covers it: Google’s API script loads on every front-end page, which survives any cache configuration. If you narrow the scope to checkout screens only and you run an aggressive cache or CDN, switch it back.

Cloudflare and other proxies. Out of the box Checkout Bouncer takes the client address from REMOTE_ADDR — the address your web server actually saw on the socket — and from nothing else. It does not trust X-Forwarded-For, X-Real-IP or CF-Connecting-IP, and it does not ask WooCommerce’s geolocation helper either, because those headers are set by whoever sends the request: trusting one would let any visitor walk onto your IP allowlist, hand themselves a fresh throttle bucket on every request, and spend a real customer’s quota by sending that customer’s address.

If your site sits behind Cloudflare, a CDN, a load balancer or any reverse proxy, you have to opt in — and until you do, REMOTE_ADDR is the proxy, not the shopper. In that state your IP allowlist entries can never match, every shopper shares one throttle bucket behind the proxy’s address (so the rate limits become far more aggressive than you intended), and the address on the Logs tab is your proxy’s. Opt in with one filter, naming the single header your proxy is guaranteed to overwrite on every request:

add_filter( 'checkout_bouncer_trusted_proxy_header', function () { return 'HTTP_CF_CONNECTING_IP'; } );

Set it only when visitors cannot reach your origin server directly — if they can, that header is spoofable again and you are back to the hole above. Checkout Bouncer reads that one header, validates the address it finds, and falls back to REMOTE_ADDR when it holds nothing usable.

That filter is the only thing that changes how an address is resolved: Checkout Bouncer does not read your WooCommerce or Cloudflare proxy configuration, so on a proxied site without it the address Checkout Bouncer uses can differ from the one WooCommerce records on the order. The quickest check is the Settings tab, which prints “You are viewing this page from …” using the address Checkout Bouncer itself sees — if that is not your own address, you need the filter.

Will it slow my site down?

No, in any way a customer would notice.

Google’s script is loaded in the footer and only on the pages that need it, so it never blocks rendering. Server-side, exactly one HTTP request is made to Google per checkout attempt, and only for a surface you have switched on. A token is never verified twice in one request — v3 tokens are single-use at Google, so the result is memoised. The scanner is the only expensive piece of work in the plugin, and it runs at most once every twelve hours, only in the admin or on cron, never on a front-end page load. Duplicate-page blocking reads a single autoloaded option, not a database query.

Does it store personal data?

As little as it can, and nothing in plaintext that it does not need.

IP addresses are anonymised before they are stored — the last octet of an IPv4 address and the last 80 bits of an IPv6 address are zeroed. Throttle counters use a site-salted, non-reversible hash of the IP, so a raw address never appears even in a transient name. Billing email addresses are stored only as salted digests. Log lines never contain the reCAPTCHA token, the secret key or a full email address. Your retention window is configurable and enforced by a daily job, and uninstalling the plugin drops the events table outright.

Please still disclose Google reCAPTCHA in your own privacy policy — see the Third-Party Services section above.

How do I stop Checkout Bouncer checking my own office?

Two ways, and you can use both:

1. Roles. Staff bypass is on by default for administrators and shop managers, and you can choose which roles count as staff.
2. IP allowlist. Paste your office or warehouse addresses, one per line, into the allowlist. IPv4, IPv6 and CIDR ranges are all accepted — 203.0.113.7, 203.0.113.0/24 and 2001:db8::/32 are all valid. Invalid lines are dropped when you save, so a typo can never widen your allowlist by accident.

Allowlisted addresses and staff are also exempt from the throttle and from route blocking, so you can always reach a blocked page to inspect it.

One caveat if you are behind a proxy: the allowlist is matched against the address Checkout Bouncer sees, which is REMOTE_ADDR until you set the checkout_bouncer_trusted_proxy_header filter described above. On a proxied site without that filter your office address never appears, so an allowlist entry for it will simply never match. Check the address printed on the Settings tab before you rely on the allowlist.

How do I test that it is actually working?

1. Place a real test order in a normal browser window. A pass row appears on the Logs tab within seconds, with the score Google gave you, and the order gets a note recording the same thing.
2. Open the same order and check the note reads as expected — surface, score, threshold and reason are all there.
3. To see a rejection without needing a bot, temporarily raise the score threshold to 0.9, place another test order, and watch it fail with low-score. Put the threshold back to 0.5 afterwards.
4. Press Test keys on the Settings tab at any time. Checkout Bouncer validates your secret against Google without needing a browser token and reports exactly what Google said.

My logs are full of “missing-token” — what does that mean?

It means the browser never produced a token. In practice that is one of four things:

• A bot that does not run JavaScript. This is Checkout Bouncer working exactly as intended, and it is by far the most common cause.
• An ad-blocker or privacy extension stopping Google’s script from loading. Checkout Bouncer gives up quietly after about ten seconds rather than throwing errors in the console, so the customer sees a checkout error rather than a broken page. If you serve a lot of privacy-conscious traffic, turn strict browser error off so a blocked script is treated as a soft failure instead.
• An aggressive page cache serving a checkout page whose scripts were never enqueued — the default sitewide loading scope already covers this, so check it has not been narrowed to checkout-only.
• A JavaScript error from another plugin or theme halting the page before Checkout Bouncer’s script runs. Check your browser console on the checkout page.

What is the difference between reCAPTCHA and the order rate limits?

They catch different attacks, which is why the plugin ships both.

reCAPTCHA scores a single request: is there a real browser and a plausible human behind this submission? The rate limits look at a pattern over time — how many orders, how many failed payments and how many different billing email addresses have come from one address inside a window you choose (the defaults are 8 orders an hour, 4 failed payments in fifteen minutes and 6 distinct billing emails an hour). A patient attacker driving a real browser can pass reCAPTCHA every single time and still be obviously card-testing the moment you look at the shape of the traffic.

The limits are applied on the classic checkout, the block checkout and pay-for-order, and they are keyed on the address Checkout Bouncer resolves — so read the proxy answer above first if your site is behind Cloudflare or a load balancer, because otherwise every shopper counts against a single bucket.

Run the throttle in monitor mode first. It records every trip without blocking anything, so you can see what your real traffic looks like before you arm it.

Does it work with my payment gateway?

Yes — any of them. Checkout Bouncer contains no gateway-specific code at all. It hooks WooCommerce’s own checkout, validation and order hooks, so Stripe, PayPal, Square, Authorize.Net, NMI, a bank plugin or an offline method all behave the same way.

You can also target verification per gateway: verify all payment methods, only a chosen list, or everything except a chosen list. That is useful when one gateway runs its own risk engine and you would rather not double up, or when a manual “bank transfer” method genuinely does not need scoring.

Does it support HPOS and modern WooCommerce?

Yes. Checkout Bouncer formally declares compatibility with High-Performance Order Storage (custom order tables) and with Cart & Checkout Blocks, so WooCommerce never lists it as incompatible. It works identically on legacy post-based order storage and on HPOS.

What about reCAPTCHA v2, hCaptcha or Turnstile?

Not supported, on purpose. Checkout Bouncer is a reCAPTCHA v3 plugin. v3 is invisible and scores every request, which is what a checkout needs; a v2 checkbox on a checkout costs you real conversions to catch bots that a score would have caught anyway. Supporting four captcha providers badly is not a feature.

Does it protect my login or registration form?

No, also on purpose. Checkout Bouncer protects the WooCommerce checkout and nothing else. Its whole design — the scanner, the surface model, the order-rate rules, the order notes — is built around orders. If you need login protection, use a plugin built for that job.

Does it work on multisite?

Yes. Activation, the events table, the scheduled purge and uninstall are all network-aware, and a site created while the plugin is network-active is set up automatically. Each site keeps its own settings, its own keys and its own event log.