reCAPTCHA v3
and CapMonster Cloud

Working with CapMonster Cloud via API typically involves the following steps:

1. Go to the reCAPTCHA admin console page.

2. Register a new site and choose the captcha type — reCAPTCHA v3

3. Get the two keys:

• Site key — public key (used on the frontend);
• Secret key — private key (used on the server for verification)

You can open the settings where you can, for example, specify domains that are allowed to use reCAPTCHA or configure alerts for site issues or spikes in suspicious traffic.

4. Client-side code examples

The simplest way to use reCAPTCHA v3 is to include the JavaScript API and add attributes to a button.

Connecting the API:

<script src="https://www.google.com/recaptcha/api.js"></script>

Callback function for the form:

<script>
  function onSubmit(token) {
    document.getElementById("form").submit();
  }
</script>

Button with reCAPTCHA attributes:

<button class="g-recaptcha" 
        data-sitekey="reCAPTCHA_sitekey" 
        data-callback='onSubmit' 
        data-action='submit'>Submit</button>

For full control, use grecaptcha.execute with the render parameter:

Connecting the API with the key:

<script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script>

Programmatic call:

<script>
  function onClick(e) {
    e.preventDefault();
    grecaptcha.ready(function() {
      grecaptcha.execute('reCAPTCHA_sitekey', {action: 'submit'}).then(function(token) {
          // Send the token to the server for verification
      });
    });
  }
</script>

The token should be sent to the server for verification immediately.

Important notes:

• Token lifetime: the token received from reCAPTCHA v3 is valid for 2 minutes. Make sure you send it to the server within this time.
• Server-side verification: after receiving the token on the server, send a POST request to https://www.google.com/recaptcha/api/siteverify with the following parameters:
  – secret: your secret key
  – response: the token received from the client
  – remoteip (optional): the user’s IP address
• Google’s server will return a JSON response containing details about the verification result.

You can find more detailed information in the captcha’s own documentation.

5. Now verify the response on the server side

PHP example

<?php
// Your reCAPTCHA v3 secret key
$secret = 'YOUR_SECRET_KEY';

// Get the token from the form
$token = $_POST['recaptcha-token'] ?? '';

// Send a request to Google to verify the token
$response = file_get_contents(
    "https://www.google.com/recaptcha/api/siteverify?secret={$secret}&response={$token}"
);

$result = json_decode($response, true);

// Check success and the trust score
if ($result['success'] && $result['score'] >= 0.5 && $result['action'] === 'submit') {
    echo "Verification passed";
} else {
    http_response_code(403);
    echo "Verification failed";
}
?>

Notes:

• Make sure that on the client the token is sent in a hidden form field named recaptcha-token:

<input type="hidden" name="recaptcha-token" id="recaptcha-token">


• The score threshold can be adjusted depending on how strict you want to be (for example, 0.3–0.7).
• Checking action === 'submit' increases security by making sure the token is issued for the specific action on the page.