Adding captcha to your checkout flow

StoreConnect supports Google reCAPTCHA v3 on the checkout flow to help prevent spam and bot activity. reCAPTCHA v3 works invisibly in the background, scoring user behavior and validating the result server-side, without presenting any challenge to your shoppers.

:::note reCAPTCHA v3 is built in to the checkout flow (customer information step), with no theme changes required. :::

Prerequisites

• A Google account to access the reCAPTCHA Admin Console
• Access to your StoreConnect admin (to set store variables)
• Your store’s domain (for example, shop.example.com.au)

Step 1: Create your reCAPTCHA keys

1. Go to the reCAPTCHA admin console and sign in with your Google account.
2. Enter a label to identify this key, such as your store name.
3. Select reCAPTCHA v3 as the type.
4. Add your store domain (for example, shop.example.com.au). Keys are domain-specific, so add any additional domains you want to protect.
5. Accept the terms and submit.
6. Retrieve your Site Key and Secret Key from the confirmation screen, or from Settings > Keys in the Google Admin Console.

:::note The Site Key is public and used in the browser. The Secret Key is private and used server-side to verify scores. Only the Site Key is visible on your storefront, so do not expose your Secret Key publicly. :::

Step 2: Add store variables in StoreConnect

In your StoreConnect Store record, go to Store Variables and create the following variables.

The first three store variables are required. If captcha_type or captcha_secret_key are missing, the reCAPTCHA script loads in the browser but the server does not verify token scores, and your Google Admin Console shows the key as Unprotected.

Name	Key	Description	Required?
Captcha key	captcha_site_key	Your reCAPTCHA v3 Site Key (public key from Google). Select Available in Liquid. Without it, the checkout form does not request a reCAPTCHA token, so checkouts are not scored.	Required
Captcha secret	captcha_secret_key	Your reCAPTCHA v3 Secret Key (private key from Google)	Required
Captcha type	captcha_type	Must be set to recaptcha	Required
Captcha passing score	captcha_passing_score	The lowest score that passes, from 0.0 to 1.0. Defaults to 0.5 when not set. Enter the value with a leading zero, such as 0.3. A value such as .3 is not read as a number, and the score check is skipped. See Manage your reCAPTCHA score.	Optional

Once these variables are set, StoreConnect automatically injects the reCAPTCHA script into the checkout page and handles token generation and server-side verification, so no theme changes are required.

Step 3: Verify the setup

Browser verification

After setting the store variables, attempt a checkout on your store. On the customer information step:

1. Open browser developer tools (F12) and go to the Console tab.
2. Confirm there are no reCAPTCHA-related errors (for example, grecaptcha is not defined or Invalid site key).
3. The reCAPTCHA badge icon should be visible in the bottom-right corner of the screen on the customer information step.

Google Admin Console verification

1. Log in to the reCAPTCHA Admin Console and select your registered key.
2. After a real checkout is completed, activity data should appear in the dashboard within 24 to 48 hours.
3. If the console shows “Unprotected - Your key is requesting tokens but isn’t requesting scores”, this means captcha_secret_key is missing.

:::note There is a delay before activity appears in the Google Admin Console, even after a successful checkout. If no data appears after 48 hours and your store variables are correctly set, confirm that the domain registered in Google matches your store’s domain exactly. :::

Troubleshooting

Symptom	Resolution
Google Admin Console shows ‘Unprotected’ warning	The captcha_secret_key store variable is missing.
grecaptcha is not defined in browser console	The reCAPTCHA script is not loading. Check that captcha_site_key is set. Do not add the reCAPTCHA script manually to your theme. StoreConnect adds it to the checkout page automatically, and adding it again makes it load twice.
Invalid site key error in browser console	The value in captcha_site_key is incorrect. Retrieve the Site Key (not the Secret Key) from the Google Admin Console under Settings > Keys.
Domain mismatch or key not authorized	Ensure the domain registered in Google matches your live store URL exactly (for example, shop.example.com.au).
Every shopper on an account subdomain gets the unusual activity message at checkout	Checkout currently accepts a reCAPTCHA solve only from your store domain, so a host such as ambassador.example.com fails the check. To take orders on an account subdomain, leave reCAPTCHA off. See Account subdomains.

reCAPTCHA failure message to shoppers

Any bots that are detected are shown an error message after trying to complete the customer information step at checkout:

We have detected unusual activity, please try again or contact us for support.

Manage your reCAPTCHA score

reCAPTCHA v3 assigns a score between 0.0 (likely a bot) and 1.0 (likely a human) to each interaction. StoreConnect blocks the checkout when the score is below the captcha_passing_score store variable, which defaults to 0.5. Monitor your score distribution in the reCAPTCHA v3 Admin Console.

If legitimate shoppers are being blocked, review your score data in the Admin Console, then add a captcha_passing_score store variable with a lower value (for example, 0.3). If the variable already exists, lower the value.

:::note If your Site Key changes (for example, you register a new key), update the captcha_site_key store variable immediately. An outdated or incorrect key will break bot protection. :::

Privacy compliance

Once you are using reCAPTCHA, your shoppers’ data is sent to Google for verification. If you are using StoreConnect’s Cookie management and privacy compliance feature, you should update this as well.