Document Properties
Last Modified22-Jun-2020
Added to KB21-Jul-2016
Public AccessEveryone
Doc TypeGuidelines, Concepts & Cookbooks
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - ReCaptcha v2

1 Introduction

reCAPTCHA v2 is a CAPTCHA service implementation from Google. It provides website protection against automated bots and spam by adding an additional widget to web forms which verifies that the user accessing the page is a real human being. In contrast to the first version, users are now no longer required to solve hard to identify text CAPTCHA challenges each time they submit a form. They now only need to solve an image challenge once and afterwards only have to tick a box to successfully verify that they're indeed human.

The ReCAPTCHA v2 feature is available by default with ICM 7.8 or later.

To be available with 7.6 and 7.7 one has to consume the latest associated patches:

  • or later
  • or later

A typical reCAPTCHA v2 challenge workflow looks as follows:

  • If a user is considered trustworthy by Google's backend (e.g., because he has already solved a CAPTCHA challenge successfully before), the service will recognize this and mark the CAPTCHA as successfully solved. No further input is required.
  • If the user has not solved a CAPTCHA before or the Google backend cannot confidently predict if the user is human, a visual CAPTCHA challenge will be presented and the user is required to solve it:

  • Alternatively, the user may decide to solve an audio CAPTCHA challenge instead:

  • Once the user has successfully solved the CAPTCHA (or was already automatically recognized as trustworthy), the protected form can be submitted.

Most of the time a user should not need to solve a CAPTCHA with reCAPTCHA v2. This makes it much more user friendly than the old implementation which required the user to identify sometimes hard-to-read text fragments. In addition to that, the new solution is much better suited for responsive storefronts.

In addition to protect websites against automated bots and spam, reCAPTCHA is also used to build machine learning data sets. For more information, visit the official website.

The reCAPTCHA service is integrated into Intershop Commerce Suite by using the Managed Service Framework. Please note that this document only contains information about the reCAPTCHA specific service implementation. Generic details on the CAPTCHA framework and about how to include CAPTCHA fields into web forms and ISML templates can be found in Concept - Captcha Framework.

1.1 References

2 Configuration

reCAPTCHA is implemented as a managed service. For activating the service for a given channel, please refer to Concept - Captcha Framework (section Activation and Configuration).

The following managed service configuration parameters are available.

ParameterDefault ValueDescription
Site Key-Site key that is used to display the widget.
Secret Key-Secret key used to authorize communication between the application and the reCAPTCHA server.
Script URL where the script for rendering the reCAPTCHA widget can be found.
Verification URL that is called to verify a users response to a reCAPTCHA challenge.

A (free) Google account is required to get the key pair for a given domain. Keys can be requested here:

For testing purposes, the following keys can be used, which will allow all verifications requests to pass successfully:

ParameterDemo Value

A warning will be displayed on the CAPTCHA widget when using these keys. Do not use them in a production environment.

3 Displaying the Widget

For information on how to include the CAPTCHA form field into a web form and a template, please refer to Concept - Captcha Framework.

If reCAPTCHA v2 is configured as service, the following code will be inserted to web forms which contain a CAPTCHA form field automatically:

<div class="g-recaptcha" data-sitekey="{SITE_KEY}"></div>
<script src="{SCRIPT_URL}" async defer></script>

The configured site key and script URL will be included automatically as well. Additionally, the language code of the current request will be appended to the script URL, so that the widget is always displayed in the same locale as the rest of the web page. The script will assure that the <div> container is replaced with the CAPTCHA widget.

If the CAPTCHA widget should not be included automatically, the following two templates need to be overridden to provide custom functionality:

  • ac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha\recaptcha\v2\ReCaptcha.isml
  • ac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha\recaptcha\v2\ReCaptchaHeader.isml

For information on how to render the widget explicitly and how to customize the design, please refer to the official documentation:

If a user tries to submit a web form without solving the CAPTCHA challenge, an error will be displayed:

The error is part of the ReCaptcha.isml template in the implementation cartridge (see above). To customize the error message, override localization property "recaptcha.v2.incorrect.error".

4 Verifying the Response

When the CAPTCHA has been solved and the form is submitted, a new parameter (g-recaptcha-response) will be added to the following request. This parameter includes a token containing information about the solved CAPTCHA challenge. The parameter together with the configured site-specific secret key and the remote IP address of the user will be transferred to the configured verification URL. Here the token will be validated and a JSON response is returned:

  "success": true|false,
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional

This response is internally transformed into a CaptchaResponse which is then handled by the CAPTCHA framework. A list of possible error codes can be found in the official documentation:

5 Implementation Artifacts

All artifacts for the service implementation can be found in cartridge ac_captcha_recaptcha (component set p_platform).

5.1 Java Classes


5.2 Templates

The service implementation includes the following ISML templates:

Template NamePathDescription
ReCaptcha.ismlac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha\recaptcha\v2Contains the JavaScript to display the widget and the <div> container where the widget is to be loaded into.
ReCaptchaHeader.ismlac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha\recaptcha\v2Empty by default. May be overridden to customize design or behavior (also see chapter Displaying the Widget).


The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets