How To Implement reCAPTCHA v3 Into Your Website


This article assumes you have already registered your website and obtained your SITE KEY and SECRET KEY from the Google reCAPTCHA website. It also assumes that the file which handles your form submission is written in PHP.



1: Add the following line in the <head> section of your HTML file which contains the form you wish to protect.

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

Replace SITE-KEY with your reCAPTCHA site key.


2: Add the following hidden input element to your form.

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

Your form's input elements may now look like the following example.

<input type="hidden" name="token" id="token">
<input type="submit" value="Submit" name="submit-button" id="submit-button">

Note: If the name and/or id of your submit button is submit, you may run into conflicts with this script.


3: Add the following line near the end of your HTML file immediately before the closing </body> tag.

<script src="grecaptcha.js"></script>


4: Create a file named "grecaptcha.js" and open it in your text editor.

Copy and paste the following code into "grecaptcha.js".

document.querySelector('form').addEventListener('submit', function(event) {
	event.preventDefault();
    grecaptcha.ready(function() {
		grecaptcha.execute('SITE-KEY', {action: 'submit'}).then(function(token) {
			document.querySelector('#token').value = token;
			document.querySelector('form').submit();
		});
	});
});

Replace SITE-KEY with your reCAPTCHA site key.

Save "grecaptcha.js" in the same directory as your HTML file. (You can save "grecaptcha.js" in any directory you like, but if you do save it in a directory other than the same directory as your HTML file you will need to change src="grecaptcha.js" in step 3 to src="/path/to/grecaptcha.js", where /path/to is the path to the directory you saved it in.)


5: Open the PHP file which handles your form submission in your text editor.

Copy and paste the following code near the beginning of your PHP file immediately after the opening <?php tag.

if (isset($_POST['token'])) {
	$url = 'https://www.google.com/recaptcha/api/siteverify';
	$data = array('secret' => 'SECRET-KEY','response' => $_POST['token'],'remoteip' => $_SERVER['REMOTE_ADDR']);
	$options = array('http' => array('header'  => 'Content-type: application/x-www-form-urlencoded','method'  => 'POST','content' => http_build_query($data)));
	$context  = stream_context_create($options);
	$response = file_get_contents($url, false, $context);
	$result = json_decode($response);
	if ($result->success && $result->score >= 0.5) {
		echo "reCAPTCHA verification passed.";
	} else {
		echo "reCAPTCHA verification failed.";
		exit();
	}
}

Replace SECRET-KEY with your reCAPTCHA secret key.


6: This final step is only necessary if you have a Content-Security-Policy on your site. If you don't have a Content-Security-Policy on your site you can skip this step.

Add the following values to the script-src directive in your Content-Security-Policy, if they are not already there.

'self' https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/

Add the following values to the frame-src directive in your Content-Security-Policy, if they are not already there.

'self' https://www.google.com

Your Content-Security-Policy may now look like the following example.

Header set Content-Security-Policy default-src 'self'; script-src 'self' https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/; frame-src 'self' https://www.google.com;


That's it. You now have Google reCAPTCHA v3 working on your website. Congratulations!

You can test if it's working correctly by changing the value of $result->score in the PHP code in step 5 from the default threshold of >= 0.5 to >= 1.0 (which is an almost impossible score to achieve). You should then get the error "reCAPTCHA verification failed" when you attempt to submit the form. Don't forget to change it back to 0.5 after you have finished testing.

You should also setup your own error handling methods in the PHP code, but that's beyond the scope of this article.


Back to Top