How to validate Google reCAPTCHA v3 on server side?
The transition from reCAPTCHA v2 to v3 represents a fundamental shift in how you handle bot protection. In the legacy v2 model, the user experience was binary: an invisible checkbox or a classic image puzzle that required explicit interaction. The validation logic was straightforward; the frontend sent a token representing human completion, and the backend verified it against Google's API.
However, reCAPTCHA v3 operates differently. It assigns every action a "score" between 0.0 and 1.0 based on how likely the user is to be human. This score is generated entirely on the client side via JavaScript. Consequently, you cannot simply rely on checking a checkbox or a hidden field in your HTML form. If you try to use the old PHP library methods shown in your example codeâspecifically recaptcha_check_answer looking for recaptcha_response_fieldâyou will face exactly the problem you are describing: the form submits even if the validation fails. This is because v2's is_valid flag logic does not exist in v3, and more importantly, the score itself cannot be trusted from the client.
To properly validate reCAPTCHA v3 on the server side using PHP, you must implement a direct API call to Google's scoring endpoint. The frontend JavaScript automatically attaches the score to the form data as _captcha_response, but this value is mutable by the user and can be spoofed. Therefore, your server-side script must ignore the client-provided score and fetch the authoritative one from Google.
Here is the standard approach using PHP cURL:
<?php
// Configuration
$secretKey = 'YOUR_V3_SECRET_KEY'; // Replace with your actual site key secret
$url = 'https://www.google.com/recaptcha/api/siteverify';
// Retrieve response data from form submission
$responseData = json_decode(file_get_contents('php://input'), true);
// Note: If using a POST form, use $_POST['g-recaptcha-response'] instead of php://input
$getResponse = isset($_POST['g-recaptcha-response']) ? $_POST['g-recaptcha-response'] : null;
if (!$getResponse) {
// Handle missing response gracefully
}
$options = [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'secret' => $secretKey,
'response' => $getResponse
])
];
$ch = curl_init();
curl_setopt_array($ch, $options);
$result = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$response = json_decode($result, true);
// Check HTTP status code first to catch network errors
if ($httpCode !== 200) {
return ['status' => 'error', 'message' => 'Failed to connect to Google API'];
}
// Verify the score
if ($response['success'] === false) {
return ['status' => 'failed', 'score' => $response['score'], 'action' => $response['action']];
}
// Define your threshold (e.g., 0.5 means 50% chance of being human)
$threshold = 0.5;
if ($response['score'] >= $threshold) {
// Proceed with form processing
echo "Form is valid. Score: " . $response['score'];
} else {
// Reject the request
echo "Form rejected. Low confidence score.";
}
?>
The critical distinction here is that you are not checking a boolean "valid" flag like in v2. Instead, you are retrieving the score property and comparing it against your defined threshold. A common pitfall is setting this threshold too low, which defeats the purpose of the protection, or too high, which creates excessive friction for legitimate users.
There is also a specific edge case regarding API rate limits. Google imposes quotas on how many requests you can make to their scoring endpoint per day. If your site has extremely high traffic without caching strategies or IP whitelisting in place, you could exhaust your quota and temporarily disable reCAPTCHA protection across your entire application. Monitor your usage via the Google Cloud Console and implement retry logic with exponential backoff if you encounter 429 errors.
For developers using the Laravel ecosystem, this logic integrates cleanly within middleware or form request validation classes. You can encapsulate this cURL verification into a dedicated service class to keep your controllers clean, ensuring that bot protection is enforced consistently without duplicating API call code throughout your application.
