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 behaviour and validating the result server-side, without presenting any challenge to your shoppers.

Prerequisites

• A Google account to access the reCAPTCHA Admin Console
• Access to your StoreConnect admin (to set Store Variables)
• Your store's domain (e.g. shop.example.com.au)

Step 1: Create Your reCAPTCHA Keys

1. Go to https://www.google.com/recaptcha/admin/create and sign in with your Google account.
2. Enter a label to identify this key (e.g. your store name).
3. Select reCAPTCHA v3 as the type.
4. Add your store domain (e.g. 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 via Settings > Keys in the Google Admin Console.

Step 2: Add Store Variables in StoreConnect

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

All three Store Variables are required. If captcha_type or captcha_secret_key are missing, the reCAPTCHA script will load in the browser but the server will not verify token scores. Your Google Admin Console will show the key as Unprotected.

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 (e.g. 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 https://www.google.com/recaptcha/admin 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.

Enabling reCAPTCHA on Other Pages

The Store Variables set in Step 2 are all that is required. To enable reCAPTCHA on pages beyond the checkout flow, add the following snippet inside the form in the relevant theme file:

{%- if store_variables["captcha_site_key"] %}
  <script src="https://www.google.com/recaptcha/api.js?render={{ store_variables["captcha_site_key"] }}" async defer></script>
{%- endif %}
{% render "captcha", action: "YOUR_ACTION_LABEL" %}

Replace YOUR_ACTION_LABEL with a descriptive value for the page (e.g. register, login). This label appears in the Google Admin Console to identify where interactions are coming from - it does not affect how the token is generated or validated.

The following pages and their corresponding theme snippet files support this approach:

After adding the snippet to a page, visit that page and confirm the reCAPTCHA badge is visible in the bottom-right corner of the screen.

Troubleshooting

reCAPTCHA Failure Message to Shoppers

Any bots that are detected will be 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.

Managing Your reCAPTCHA Score

reCAPTCHA v3 assigns a score between 0.0 (likely a bot) and 1.0 (likely a human) to each interaction. You can monitor your score distribution and adjust thresholds from the reCAPTCHA v3 Admin Console.

If you find that legitimate shoppers are being blocked, review your score data in the Admin Console and consider whether your threshold needs adjustment.

Privacy compliance

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

Terms

Captcha: A CAPTCHA is a type of challenge-response test used in computing to determine whether or not the user is human.