Documentation

Requirements

Checkout Bouncer runs on any normal WooCommerce store. There is nothing to compile and no external service to sign up for beyond free Google reCAPTCHA keys.

What	Minimum	Notes
WordPress	6.2 or newer	Single site or multisite.
PHP	7.4 or newer	PHP 8.1 or 8.2 recommended for speed.
WooCommerce	7.0 or newer	HPOS (custom order tables) supported.
Checkout type	Classic shortcode or block checkout	Both are covered. Six page builders are detected.
Google reCAPTCHA	v3 site key and secret key	Free. v2 checkbox keys will not work.
Outbound HTTPS	To google.com	Your server verifies each token with Google.

Checkout Bouncer protects the checkout. It is not a firewall and not a malware scanner, and it does not touch login, registration, comments or contact forms.

Installing the plugin

Two ways in. Both end at the same place: WooCommerce → Checkout Bouncer in your admin menu.

From the WordPress.org directory

This is the easiest route and gives you one-click updates.

1. Go to Plugins → Add New.
2. Search for Checkout Bouncer.
3. Click Install Now, then Activate.

By uploading the zip

Use this if you have the zip file in hand.

1. Go to Plugins → Add New → Upload Plugin.
2. Choose the zip and click Install Now.
3. Click Activate Plugin.
4. If you prefer SFTP, unzip into wp-content/plugins/ and activate from the Plugins screen.

Activating the plugin does not block anything on its own. Nothing changes for your customers until you add keys and tick the enable box.

Settings reference

Every setting, group by group, and what it changes for a real shopper. This is the part of the Checkout Bouncer documentation worth bookmarking.

1. Keys

1. Keys

Setting	What it does
Site key	Your public reCAPTCHA v3 site key. Printed into the page so the browser can request a token.
Secret key	Your private key. Used server-side to verify each token with Google. Never sent to the browser.
Enable protection	The master switch. With this off, nothing is verified and nothing is blocked.

2. Scoring and behaviour

2. Scoring and behaviour

Setting	What it does	Suggested
Score threshold	reCAPTCHA v3 returns a score from 0.0 (almost certainly a bot) to 1.0 (almost certainly a person). Orders scoring below your threshold are blocked.	0.5
Fail open	Decides what happens when Google cannot be reached or the verification call times out. Fail open lets the order through so sales keep flowing. Fail closed blocks it.	On, unless you are under active attack
Strict browser errors	When on, a browser-side reCAPTCHA error is treated as a failure instead of being tolerated. Tightens things up at the cost of the occasional false block on odd browsers and privacy extensions.	Off to start
Token refresh	reCAPTCHA tokens expire after a couple of minutes. Refresh keeps a fresh token on the page so shoppers who take their time filling in the address form are not rejected for a stale token.	On
Script loading scope	Sitewide by default, because v3 scores a visitor on their whole-site behaviour and that is what Google recommends. You can narrow it to checkout screens only if you would rather the script did not load elsewhere; expect slightly less reliable scores.	Sitewide
Badge	Show or hide the floating reCAPTCHA badge. If you hide it, Google’s terms require you to credit reCAPTCHA in your privacy policy or near the checkout button.	Your call

3. Protected checkout screens

Tick the routes an order can enter your store through. Each one is a separate code path in WooCommerce, and a plugin that only covers the first of them leaves the rest wide open.

3. Protected checkout screens

Screen	Why it matters
Classic shortcode checkout	The traditional [woocommerce_checkout] page. What classic captcha plugins cover.
Block checkout (Store API)	The block checkout submits through the WooCommerce Store API and never fires the classic checkout hooks, so a captcha that only hooks the classic form never sees those orders. Checkout Bouncer registers Store API endpoint data so the token travels with the request.
Pay for order	The pay page behind an order-pay link. A favourite of card testers because it is a clean, repeatable form.
Add payment method	Optional. Covers the my-account screen where a saved card is added, which is a cheap way for a bot to test a card without placing an order.

4. Payment methods

Target verification by gateway, using your store’s real gateway list rather than a guessed one. Three modes:

• All gateways is the default, and the right answer for most shops.
• Include verifies only the gateways you tick, which is useful if card testing is hitting one card gateway and you do not want to touch anything else.
• Exclude verifies everything except the gateways you tick; it is handy for bank transfer, cash on delivery or an invoice gateway used by trade customers.

5. Blocking

Some routes cannot carry a token at all. You cannot protect those; you can only close them.

5. Blocking

Setting	What it does
Block the Store API checkout route	Hard-blocks the Store API checkout endpoint with a 404 or a 403, your choice. Use this when your store runs a classic checkout and has no legitimate need for the Store API checkout route. If you use the block checkout, or a headless or mobile front end, leave this alone and protect the route instead.
404 or 403	404 tells a scanner the route does not exist, which is the quieter answer. 403 is explicit about refusal. 404 is usually the better deterrent.
Block rogue checkout pages	Closes duplicate checkout pages the scanner found elsewhere on the site (old drafts, builder copies, a staging page someone published by accident). Your own active checkout is never offered for blocking.

6. Order-rate throttle

Scoring catches most bots. The throttle catches the rest by limiting what a single IP address can do in a short window.

6. Order-rate throttle

Limit	What it counts	Sensible start
Max orders per hour	Orders placed from one IP in a rolling hour.	Well above your busiest genuine customer
Max failed payments per 15 minutes	Declined payments from one IP. This is the card-testing signal: a real customer retries twice, a bot retries fifty times.	Low. This one does the work.
Max distinct billing emails per hour	How many different billing email addresses one IP uses. Catches a bot cycling through generated addresses.	Low, unless you sell from shared offices
Monitor mode	Logs what would have been blocked without blocking anything. Run this for a day or two first, look at the events table, then set your real limits with evidence instead of guesswork.	On for the first 48 hours

If your store sits behind a proxy or Cloudflare, read the proxy section before you turn the throttle on. Without the right configuration every visitor looks like the same IP and they all share one bucket.

7. Bypass

7. Bypass

Setting	What it does
Staff role bypass	Chosen roles skip verification and the throttle. Use it so a shop manager placing phone orders all afternoon is never throttled.
IP allowlist	Addresses that always skip checks. Accepts IPv4, IPv6 and CIDR ranges, one per line. Put your office and warehouse here. Keep it short, because every entry is a hole you have chosen to leave open.

8. Logging

Every decision lands in the events table: pass, fail or block, with the score and the reason. The dashboard rolls that up into pass, fail and block counts and a list of your top block reasons, so you can see at a glance whether you are being probed. Export the events to CSV when you need to hand evidence to your payment provider or work through a pattern in a spreadsheet.

The Checkout Scanner explained

Most stores are not protected the way their owner believes. The scan exists to tell you the truth. It answers four questions: which page is really your checkout, what actually renders it, what other checkout-shaped pages exist on this site, and is the Store API checkout route reachable.

Rendering detection covers the block checkout, the classic shortcode, and six page builders: Elementor, Divi, WPBakery, Beaver Builder, Bricks and Oxygen. It matters because a builder can wrap your checkout in a way that changes which hooks fire.

Finding: unprotected active checkout

Your real checkout is live but the matching screen is not ticked. Click Protect. This is the single most common finding and the one that actually costs money.

Finding: Store API checkout route exposed

The block checkout’s submission route is reachable. If you use the block checkout, or anything headless, choose Protect so the token travels with the request. If your store runs a classic checkout and nothing else needs that route, choose Block.

Finding: duplicate or rogue checkout page

A second page on your site renders a checkout. Usually an old draft, a builder copy, or a test page someone published years ago. Bots find these because they crawl your sitemap. Confirm it is not something you rely on, then choose Block.

Finding: configuration verifies nothing

The plugin looks switched on but no request would ever be checked: keys missing, no screens ticked, or a gateway rule that excludes everything you actually sell with. Fix the setting the finding names. This is the silent failure the scan exists to catch.

Re-run the scan after any theme change, builder change, or WooCommerce update. New pages appear and old ones come back from the dead.

Developer hooks

Seven filters cover the customisation people ask for, and this part of the Checkout Bouncer documentation lists each one. Put your code in a small site plugin so a theme update cannot wipe it.

8. Logging

Filter	What it controls
checkout_bouncer_trusted_proxy_header	Which server header holds the real visitor IP. Empty by default, so REMOTE_ADDR is used. Set it only if you sit behind a proxy you control.
checkout_bouncer_skip	Skip verification for a request entirely. Use for a specific integration, a known internal flow, or a scripted order.
checkout_bouncer_error_message	The message a blocked shopper sees. Change it to give people a phone number or a way to reach you.
checkout_bouncer_should_block	The final block decision. Your last word before an order is stopped or allowed.
checkout_bouncer_bypass_roles	The list of roles that bypass checks. Add custom staff roles the settings screen does not know about.
checkout_bouncer_soft_errors	Which error conditions are treated as soft, meaning logged and tolerated, instead of hard failures.
checkout_bouncer_throttle_exempt	Exempt a request from the order-rate throttle while still verifying its score.

// Change the message a blocked shopper sees.
add_filter( 'checkout_bouncer_error_message', function ( $message ) {
 return 'We could not verify this order. Please call us on 01234 567890 and we will take it over the phone.';
} );

// Let a custom staff role bypass checks.
add_filter( 'checkout_bouncer_bypass_roles', function ( $roles ) {
 $roles[] = 'warehouse_manager';
 return $roles;
} );

Several of these filters pass extra context as later arguments. Because add_filter only hands you the arguments you ask for, the one-argument callbacks above are safe as written; raise the accepted-args count when you want the context. The exact signatures are documented in the plugin source next to each apply_filters call.

When the Checkout Bouncer documentation does not cover it

Export your events to CSV and send it with your question. The block reasons usually make the answer obvious in a minute or two. The plugin is free and fully functional on WordPress.org. There is no paid tier to buy today.