Using Cloudflare Turnstile to protect your checkout

Nicolas Audet
Nicolas Audet
  • Updated

Overview

Cloudflare Turnstile is a bot protection service that replaces traditional CAPTCHAs with a challenge that is, in most cases, invisible to your customers. Once the integration is installed, gaiia displays a Turnstile widget on your checkout so automated traffic is filtered out before an order is submitted.

This article covers how to create a Turnstile widget in your Cloudflare account, how to install and configure the Cloudflare Turnstile integration in gaiia, and how to validate that bot protection is active on your checkout.

 

Before you begin

Installing and configuring integrations requires the Integrations > Edit permission enabled.

You will need a Cloudflare account. If you do not have one, create it from the Cloudflare dashboard. You will also need your tenant's slug, which is the identifier used in your gaiia URLs.

 

 

Setting up the integration

The setup is done in three parts: creating the widget in Cloudflare, installing the integration in gaiia, then validating the result on your checkout page.

 

A. Create a Turnstile widget in Cloudflare

  1. Log into the Cloudflare dashboard.
  2. Navigate to the Turnstile page.
  3. Click on the Add widget manually button. 

  4. In the Hostname section, add both of the following hostnames

    1. The hostname your checkout is configured on, usually order.your-website.com.
    2. your-tenant-slug.gaiia-checkout.systems, replacing your-tenant-slug with your tenant's slug.

    The your-tenant-slug.gaiia-checkout.systems hostname is required for the Turnstile widget to correctly create challenges on the embedded Sales checkout flow in gaiia. Omitting it will leave the widget unable to load in that context.

  5. Save the widget, then copy both the Site key and the Secret key 

    cloudflare widget.webp

 

The Secret key is only used server-side and should be treated like a password. Store it securely and do not share it outside of your gaiia integration configuration.

 

B. Install the integration in gaiia

  1. Log into your gaiia instance.
  2. Navigate to the app directory at https://app.gaiia.com/your-company-name/admin/integrations.
  3. Locate the Cloudflare Turnstile integration and install it.
  4. Provide the Site key and the Secret key copied in step A.

  5. Once installed, edit the integration's configuration and enable bot protection in checkout under the Usage configuration tab 

    Usage configuration.webp

     

  6. Save your configuration.

 

C. Validate the configuration

To confirm that the integration is working, navigate to your checkout page and verify that the Turnstile widget appears on the address capture page.

Due to backend caching, it can take a few minutes for the widget to appear after the integration has been configured. If the widget is not visible right away, wait a few minutes and reload the checkout page.

 

Troubleshooting

Symptom What to check
The widget does not appear on the checkout page. Confirm that bot protection is enabled under the Usage configuration tab, then allow a few minutes for the cache to refresh.
The widget appears but always fails the challenge. Confirm that both hostnames were added to the Cloudflare widget, including your-tenant-slug.gaiia-checkout.systems.
The widget does not load in the embedded Sales checkout flow. The your-tenant-slug.gaiia-checkout.systems hostname is missing from the Cloudflare widget configuration. Add it and save.
The integration cannot be saved. Confirm that the Site key and Secret key were copied in full, with no leading or trailing spaces.

Was this article helpful?

Have more questions? Submit a request