> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# RECAPTCHAV3- (Google reCAPTCHA)

> Integrate Google reCAPTCHA V3 into the template: load the script, pass the token, query the result of the check and evaluate Google's response in the event of an error.

Google reCAPTCHA V3 does not give the visitor a task, but observes their behavior and assigns a score between 0 and 1. The shop retrieves this score from Google and uses a configured threshold to decide whether it considers the visitor to be a human.

In the template, this happens in three steps: you load the script from Google, pass the token generated by Google to the shop, and then query the result. The six `RECAPTCHAV3-` tags cover exactly these three steps.

Guide: Captcha protection

> [!NOTE]
>
> All tags on this page are permitted in all templates.

> [!NOTE]
>
> Friendly Captcha is the second provider available in the shop system. The tags there have different names but work according to exactly the same pattern.

Reference: FRIENDLYCAPTCHAV1- (Friendly Captcha)

## Loading the script from Google

Two tags return the details that the script needs.

| Tag | Returns |
| - | - |
| `RECAPTCHAV3-APIUrl` | the configured address of the reCAPTCHA interface |
| `RECAPTCHAV3-SiteKey` | the configured site key |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<script src="~RECAPTCHAV3-APIUrl~?render=~RECAPTCHAV3-SiteKey~"></script>
```

> [!NOTE]
>
> Both values come from the shop configuration. Do not hard-code them in the template; otherwise, the integration breaks as soon as the key is changed or a subshop uses its own.

> [!NOTE]
>
> The previous documentation lists both tags only as single tags. In the shop system, they also apply as range tags, specifically when the respective value is configured. This lets you cleanly hide the entire integration if reCAPTCHA is not set up for this shop.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{RECAPTCHAV3-SiteKey}
   <script src="~RECAPTCHAV3-APIUrl~?render=~RECAPTCHAV3-SiteKey~"></script>
{/RECAPTCHAV3-SiteKey}
```

## Passing the token to the shop

Google generates a token in the browser. Your form must send this token to the shop under the name `ws_recaptchav3_token`; otherwise, the shop cannot check anything.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form method="post" action="~FORM-Inquiry~">
   <input type="hidden" name="ws_recaptchav3_token" value="">
   ...
</form>

<script>
   grecaptcha.ready(function() {
      grecaptcha.execute('~RECAPTCHAV3-SiteKey~', { action: 'homepage' })
         .then(function(token) {
            document.querySelector("[name='ws_recaptchav3_token']").value = token;
         });
   });
</script>
```

> [!WARNING]
>
> The field name `ws_recaptchav3_token` is fixed and has no tag of its own. Write it exactly like this. A missing or empty token results in response code 200; the check is then considered failed.

> [!NOTE]
>
> A token from Google is short-lived. Therefore, only get it immediately before submitting, not when the page is built, if a lot of time can pass between building and submitting.

## Querying the result

Two ranges query the result. The difference lies in how often the check is performed.

| Tag | Checks |
| - | - |
| `RECAPTCHAV3-PassedAlways` | again on every page call |
| `RECAPTCHAV3-PassedOnce` | once per session; after that, the stored result applies |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{RECAPTCHAV3-PassedOnce}
   <a href="~ERP-DownloadLink~">Preisliste herunterladen</a>
{/RECAPTCHAV3-PassedOnce}

{!RECAPTCHAV3-PassedOnce}
   <p>Bitte bestätigen Sie, dass Sie kein Roboter sind.</p>
{/!RECAPTCHAV3-PassedOnce}
```

> [!WARNING]
>
> Neither tag is a passive query. When evaluating them, the shop system sends a request to Google and waits for the response. Therefore, only place them where the result is needed, and not as a precaution on every page. Every check actually performed is counted in the shop system.

> [!WARNING]
>
> Once `RECAPTCHAV3-PassedOnce` has stored a negative result in the session, it continues to return "failed" for the rest of the session and does not ask Google again. The visitor cannot get out of this state on their own. At the point where they should try again, additionally use `RECAPTCHAV3-PassedAlways`. A successful check achieved with it cancels the stored negative result.

> [!NOTE]
>
> `RECAPTCHAV3-PassedAlways` checks exactly once per page call. Placing it several times on the same page therefore does not generate a second request but reuses the result of the first tag.

> [!NOTE]
>
> The check is passed if the score returned by Google is **greater** than the configured minimum value. A score that exactly equals the minimum value is considered failed.

> [!WARNING]
>
> If Google cannot be reached, both tags report "failed". A tolerance for technical faults stored in the configuration does not apply here. Therefore, for important functions, plan a path that continues even without a successful check.

> [!NOTE]
>
> In the cross-references of both pages, the previous documentation misspells the tag name as `RECHAPTAV3-PassedOnce` and `RECHAPTAV3-PassedAlways`, respectively. The correct prefix is `RECAPTCHAV3-`.

## Tracing errors

After a check, two tags are available for troubleshooting.

| Tag | Returns |
| - | - |
| `RECAPTCHAV3-LastResponseCode` | the technical status code of the last check |
| `RECAPTCHAV3-LastPlainResponse` | the unchanged response from Google |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{RECAPTCHAV3-PassedAlways}
   Prüfung bestanden.
{/RECAPTCHAV3-PassedAlways}

{!RECAPTCHAV3-PassedAlways}
   Prüfung nicht bestanden, Code ~RECAPTCHAV3-LastResponseCode~.
{/!RECAPTCHAV3-PassedAlways}
```

> [!WARNING]
>
> Both tags refer to the **last** check. They must therefore be placed in the template **after** `RECAPTCHAV3-PassedOnce` or `RECAPTCHAV3-PassedAlways`. Before that, no check has taken place yet, and the code is 0, which mistakenly looks like a passed test.

### The response codes

The previous documentation only states "0 means passed, everything else means failed". The shop system additionally distinguishes what caused the result.

| Code | Meaning |
| - | - |
| 0 | check passed |
| 1 | already checked and failed in this page call |
| 2 | already checked and failed in this session |
| 3 | Google responded, the score is not sufficient |
| 200 | no token passed, the `ws_recaptchav3_token` field is missing or empty |
| 201 | the verification address is missing in the configuration |
| 202 | the secret key is missing in the configuration |
| 300 | the request to Google failed |
| 301 | Google returned nothing |
| 302 | the response from Google could not be evaluated |
| 400 | the shop system could not prepare the request |

> [!NOTE]
>
> Codes 1 and 2 do not mean that a check was just performed. They indicate that an earlier negative result was reused. Code 2 only comes from `RECAPTCHAV3-PassedOnce`, code 1 only from `RECAPTCHAV3-PassedAlways` on a second occurrence on the same page.

> [!NOTE]
>
> Codes 201 and 202 indicate an incomplete shop configuration, not a behavior of the visitor.

> [!NOTE]
>
> `RECAPTCHAV3-LastPlainResponse` returns Google's response as JSON, unchanged. Among other things, it contains the score and the action name. For further processing in the template, pass the content to the JSON interface.

Reference: EJD- (JSON interface)

> [!WARNING]
>
> Do not output `RECAPTCHAV3-LastPlainResponse` on a publicly visible page. The response contains technical details about the shop that are nobody's business but yours. A separate, protected page is suitable for troubleshooting.

## The tags at a glance

| Tag | Single tag | Range tag | Negative range tag | Loop tag |
| - | - | - | - | - |
| `RECAPTCHAV3-APIUrl` | yes | yes | yes | – |
| `RECAPTCHAV3-SiteKey` | yes | yes | yes | – |
| `RECAPTCHAV3-PassedOnce` | – | yes | yes | – |
| `RECAPTCHAV3-PassedAlways` | – | yes | yes | – |
| `RECAPTCHAV3-LastPlainResponse` | yes | yes | yes | – |
| `RECAPTCHAV3-LastResponseCode` | yes | – | – | – |

All six tags are permitted in all templates. As a range tag, `RECAPTCHAV3-LastResponseCode` is treated as an invalid tag.

## Related topics

* Guide: Captcha protection
* Reference: FRIENDLYCAPTCHAV1- (Friendly Captcha)
* Reference: EJD- (JSON interface)
* Reference: Captcha section in the shop configuration


## Related topics

- [External services and interfaces](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/externe-dienste-und-schnittstellen.md)
- [Validation and checking services](https://dokumentation.websale.de/en/konfiguration/validierungs-und-prufservices.md)
- [security - Security rules](https://dokumentation.websale.de/en/konfiguration/security-sicherheitsregeln.md)
- [FRIENDLYCAPTCHAV1- (Friendly Captcha)](https://dokumentation.websale.de/en/v8s/referenz/tags/friendlycaptchav1.md)
- [Forms for customer inquiries](https://dokumentation.websale.de/en/v8s/formulare-fuer-kundenanfragen/formulare-fuer-kundenanfragen.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.