Concept - ReCaptcha

Table of Contents

Product Version


Product To Version



New Labels

Google is shutting down the reCAPTCHA v1 API on March 31, 2018 ( Google urges developers who are still using this API to update their websites to the reCAPTCHA v2 API ( as soon as possible. Intershop provides implementations of the reCAPTCHA v2. Please have a look at:

1 Introduction

reCAPTCHA (cartridge ac_catpcha_recaptcha) is a service implementation (of cartridge bc_captcha) based on the reCAPTCHA library and service provided by Google.

Basically, it supports:

  • audio captcha including localization - an acoustic challenge;
  • image captcha including localization - a visual challenge;
  • captcha reload - if the user cannot understand or read the challenge clearly, he/she can request a new challenge;
  • captcha switch (between audio and image) - provides the option to the user to decide whether he/she wants to solve the acoustic or the visual challenge;
  • tooltip support - this allows the provision of basic instructions on how to use the reCAPTCHA widget;
  • theme support - this allows the change of the layout with basic themes;
  • modal box (overlay) support - reCAPTCHA can be used within overlay windows;

The following image shows a basic audio CAPTCHA challenge (sound is played automatically):

Next, a basic image challenge is shown:

Google's reCAPTCHA is basically a web service, meaning that the CAPTCHA images are served directly from the Google servers to the end users. The Intershop integration uses the Managed Services framework.

It is customizable in the context of the reCAPTCHA service configuration. For further details please refer to customization documentation.

In addition to the pure CAPTCHA functionality, reCAPTCHA also helps in digitizing old books and newspapers. Refer to WHAT IS reCAPTCHA to learn more.




audio captcha

an acoustic captcha representation

image captcha

a visual captcha representation


public and private key to access the external reCAPTCHA service


Project Homepage:
Project Documentation:
Related questions are discussed in the Cookbook - ReCaptcha (valid to 7.7)

2 Configuration

Activating Captcha Services

For activating CAPTCHA services for a channel or a feature at all please refer to Concepts - Captcha Framework - Activation and Configuration

Configuration of the reCAPTCHA Service

A configuration of the following service configuration parameters can be achieved via the generic managed service back office (as a service manager):

ES Backoffice > Channel > Services > ReCaptcha Check - Configuration

For testing purposes the settings listed below can be used. However, it is kindly recommended to register another test account. To use reCAPTCHA on a production system, it is required to create a new key set for the unique production domain. This can be done here. Creating an account is free.



Public Key


Private Key






These settings are just for testing purposes and are valid for all domains.

3 Generation

The following sections describe how CAPTCHAs are generated based on the reCAPTCHA implementation.


Before getting into the details, it is worth seeing a high-level overview of how reCAPTCHA works. Below, the basic lifecycle of a reCAPTCHA challenge is displayed:


  1. The client requests a web page with the reCAPTCHA functionality activated and configured for this page. The reCAPTCHA implementation generates the required JavaScript tags to include reCAPTCHA on that page.
  2. The client's browser requests a challenge (an image with distorted text) from external reCAPTCHA service via JavaScript. reCAPTCHA delivers a challenge and a token that identifies the challenge to the client.
  3. The client fills out the web page form and later submits the result to the application server along with the challenge token.
    1. The validator, defined in the specific webform, is called. This invokes the verifyCaptcha method of the reCAPTCHA implementation.
    2. Based on the managed service framework, the executor class (encapsulates the service functionality) is called, thus communicating to the web service APIs verify method.
  4. The external reCAPTCHA service checks the user's answer, and gives you back a response.
  5. The validator checks the answer and sets the validation result of the webform parameter accordingly.

Generating a reCAPTCHA Image and Audio Challenge

Basically, the captcha generation is done by the external JavaScript provided by Google. This JavaScript is included in the webpage via a script tag in the template. The correct URL-including parameters for the script tag are prepared in the adapter according to the service configuration.

<script type="text/javascript" src=""></script>

Once the script is included, this JavaScript renders all the visual elements on the page needed by reCAPTCHA, thus providing all input elements (including hidden CAPTCHA challenge token), the CAPTCHA (visual or audio) itself and other interaction elements (e.g. the tooltip button). The rendering process itself can only be influenced by the reCAPTCHA API options. These options are provided as JSON object in the template:

<script type="text/javascript">
var RecaptchaOptions = {
    custom_translations : {
        instructions_visual : "<istext key="captcha.instruction.visual" />",
        instructions_audio : "<istext key="" />",
        play_again : "<istext key="" />",
        cant_hear_this : "<istext key="captcha.cantHear" />",
        visual_challenge : "<istext key="captcha.challenge.visual" />",
        audio_challenge : "<istext key="" />",
        refresh_btn : "<istext key="captcha.btn.refresh" />",
        help_btn : "<istext key="" />",
        incorrect_try_again : "<istext key="captcha.incorrect" />",
    theme: "white"

In case you want to change these settings, you can overload the template mentioned above in the storefront cartridge. Due to this approach, a second mode was implemented to use reCAPTCHA within modal boxes/overlay windows (currently the PrimeTech JavaScript framework prevents calling JavaScript from within modal boxes/overlay windows). The following line from the ReCaptchaHeader.isml template registers captcha in the Enfinity JavaScript framework, thus calling the AJAX API of the reCAPTCHA service.

$.extend(KOR.Captcha, {reCaptchaKey: '6LfdkcASAAAAAM2riv4EctfxSSqlXKSC-SasCYIO'});$.extend(KOR.Captcha, {reCaptchaOptions: RecaptchaOptions});

Whenever a DIV with the ID "captcha" is used within a modal box/overlay window, the Enfinity JavaScript framework triggers the rendering and building of the CAPTCHA.
The following artifacts contain the technical details.

The corresponding templates are:

  • ac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha_recaptcha\Recaptcha.isml
  • ac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha_recaptcha\ReCaptchaHeader.isml

Both files are located in ac_captcha_recaptcha.

4 Validation

After submitting the form, the webform framework invokes the CAPTCHA validator. If no captcha service is available or the used CAPTCHA preference is set to "off", the validator will always succeed (that is, no error or failed validation is returned). Also, the validator always succeeds if the user is logged in.

Otherwise, the external reCAPTCHA API is called via the CaptchaExecutor class (containing the communication to the external reCAPTCHA service) to verify the answer provided by the client.

The validation result is delivered back to the validator and the validator checks the answer and sets the ValidationResult of the webform parameter accordingly.
For further details consider the following classes:

5 Cartridge ac_captcha_recaptcha

Defined Artifacts Diagram

The following image outlines the most important interfaces and classes. A description of each one follows below.

Defined Artifacts Description


In the Adapter class the service interface CaptchaService of the bc_captcha cartridge is implemented.
The association with the Executor class (which is CaptchaExecutor here) is set in the constructor of this class.



The executor class realizes the communication with the external reCAPTCHA service we want to talk with. The needed data is transferred with the CaptchaExecutorRequest and CaptchaExecutorResponse data containers.


CaptchaExecutorRequest and CaptchaExecutorResponse

Request and response data container. They are handled in the verifyCaptcha method (implemented in CaptchaAdapter).



Configuration data container as used in the capability pattern.



Template that is included into forms to use reCAPTCHA.



Template that is included into the header section of the HTML to use reCAPTCHA.



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