Skip to main content

Switch from reCAPTCHA to hCaptcha

Switching from reCAPTCHA to hCaptcha is easy. Below you can find a step-by-step guide to help with this upgrade.

note

You don't have to update your callbacks or tag attributes. hCaptcha is API-compatible with reCAPTCHA.

Get your hCaptcha sitekey and secret key

  1. Signup or login on the hCaptcha Dashboard
  2. Go to the Sites tab in the dashboard and create a new sitekey.
  3. Go to the Settings tab in the dashboard and copy your secret key.

Update client side integration

  1. Replace the script tag:

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

    becomes

    <script src="https://js.hcaptcha.com/1/api.js"
    async defer></script>
  2. Replace the parameter name:

    g-recaptcha becomes h-captcha

Update server side integration

  1. Update secret key:

    Use the secret key that you got in the first step.

  2. Replace field used from the form:

    g-recaptcha-response becomes h-captcha-response

  3. Update siteverify URL

    https://www.google.com/recaptcha/api/siteverify (or https://www.recaptcha.net/recaptcha/api/siteverify) becomes https://api.hcaptcha.com/siteverify

  4. Invert score consumption (reCAPTCHA v3 or Enterprise to hCaptcha Enterprise only)

    reCAPTCHA scores run from 0.0 (bot) to 1.0 (person). hCaptcha Enterprise scores are risk scores, and thus they run from 0.0 (no risk) to 1.0 (confirmed threat). See the hCaptcha Enterprise documentation on scores for more details. (Requires login to Enterprise account.) This means you should invert any score checks in your score consumption code.

    If (score < threshold) Then [mitigate]

    becomes

    If (score >= threshold) Then [mitigate]

Switch from plugins/libraries

pre-built hCaptcha integrations are available for virtually all platforms and frameworks. A few are linked below:

Platform/FrameworkLink
ReactJSreact-hcaptcha
Angularng-hcaptcha
AndroidAndroid SDK
iOSiOS SDK
Express.jsexpress-hcaptcha
Node.jsnode-hcaptcha
VueJSvue-hcaptcha
WordPress pluginhcaptcha-wordpress-plugin
PHPUse hCaptcha with PHP Apps