reCAPTCHA is a tool used to determine if a given action is performed by a real user or malicious automation. Therefore, it is particularly helpful in preventing ecommerce fraud.

This guide shows you how to implement this feature in checkout integrations. To learn more about this type of validation in VTEX stores, see this article on reCAPTCHA on our help center.

VTEX is integrated with reCAPTCHA enterprise, which offers two validation approaches: checkbox (equivalent to reCAPTCHA v2) and score-based (equivalent to reCATPCHA v3). See this article on reCAPTCHA at VTEX Checkout to learn what version you should use depending on your storefront characteristics. You can also learn more each method: reCAPTCHA v2 or reCAPTCHA v3 with the documentation provided by Google.

To configure reCAPTCHA verification, follow the steps below:

1. Make a GET request using the endpoint Get orderForm configuration.
2. Make a POST request using the endpoint Update orderForm configuration with the same data obtained in the GET request, just modifying the recaptchaValidation parameter to one of the following values:
   • "never": no purchases are validated with reCAPTCHA.
   • "always": all purchases are validated with reCAPTCHA. This is the recommended option if you are using score-based validation (equivalent to reCATPCHA v3).
   • "vtexCriteria": only some purchases are validated with reCAPTCHA in order to minimize friction and improve the shopping experience. VTEX’s algorithm determines which sessions are trustworthy and which should be validated with reCAPTCHA. This is the recommended option if you are using checkbox validation (equivalent to reCAPTCHA v2).
3. Make a new GET request using the endpoint Get orderForm configuration to confirm activation.

This configuration is valid for the entire account. It is not possible to activate reCAPTCHA for a limited number of bindings.

If you activate reCAPTCHA for your account, it is important to note that any integrations that deal with placing orders should be able to handle the validation. If reCAPTCHA is required for a given order, it can not be placed without validation. However, if your store uses VTEX’s native UI, it is already capable of handling reCAPTCHA. ⚠️ If you are implementing a headless checkout experience in your store or even carrying out order creation tests via API, reCAPTCHA in active mode can block order completion requesting the reCAPTCHA validation key that is not possible to generate only via API, its only possible to generate displaying the reCAPTCHA widget.

Learn more about the applicable cases and how to implement reCAPTCHA for Checkout integrations.

Score-based reCAPTCHA returns a score for the user interaction at your store. Possible values are 0.1, 0.3, 0.7 and 0.9, where 1.0 is is very likely a good interaction and 0.0 is very likely a bot. Learn more about how to interpret this score.

If you are implementing score-based reCAPTCHA, you have the option to set a minimum score for each key that you create and set a minimum score for your account.

The priority order of score application for any given purchase is:

This means that if you set minimum scores for both your key and account, the minimum score of the key will be applied. On the other hand, if you set neither, VTEX will apply the default value of 0.7.

Interactions that return a value lower than the minimum value applicable will not be able to place orders.

To set a minimum score for your account, follow the steps below:

1. Make a GET request using the endpoint Get orderForm configuration.
2. Make a POST request using the endpoint Update orderForm configuration with the same data obtained in the GET request, just adding or modifying the value of the field recaptchaMinScore, which is a decimal number.