Skip to main content

Migration from reCAPTCHA

This guide helps you migrate from Google reCAPTCHA (v2 checkbox/invisible or v3) to MTCaptcha with parallel changes in the browser and on your server.

Why migrate from reCAPTCHA​

  • Privacy and GDPR alignment: MTCaptcha is designed as a privacy-conscious service with clear handling of end-user data. See Privacy GDPR Compliance for how MTCaptcha approaches compliance.
  • WCAG 2.1 AAA accessibility: MTCaptcha targets strong accessibility for diverse users and assistive technologies. See Accessibility Compliance for conformance detail and VPAT references.
  • Global reliability, including China: Dedicated delivery in mainland China helps avoid reliance on providers that are often slow or blocked there. See Works in China.

Migration at a glance​

reCAPTCHAMTCaptcha
Client scripthttps://www.google.com/recaptcha/api.jshttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget class.g-recaptcha (v2 widget container; v3 loads script without a visible widget).mtcaptcha (use <div class="mtcaptcha"></div>)
Token nameg-recaptcha-response (form field or callback)mtcaptcha-verifiedtoken (hidden input name)
Backend APIPOST https://www.google.com/recaptcha/api/siteverify (secret + response)GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Server-side verification only

Call MTCaptcha CheckToken only from your backend. Never embed your PrivateKey in frontend code or expose it to the browser.

Step 1: Replace client-side script and widget​

<!-- Remove [reCAPTCHA] -->
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<div class="g-recaptcha" data-sitekey="YOUR_RECAPTCHA_SITE_KEY"></div>

<!-- Add [MTCaptcha] -->
<script>
  var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" };
</script>
<script src="https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js" async defer></script>
<div class="mtcaptcha"></div>
Load order

Set var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" }; before loading mtcaptcha.min.js so the client reads your site key when the script initializes.

If you used reCAPTCHA v3 (score-only, no visible widget), remove the v3 script and any execute calls; add the MTCaptcha anchor <div class="mtcaptcha"></div> (or use explicit render if you already customize rendering).

Step 2: Update server-side verification​

Replace calls to Google siteverify with MTCaptcha CheckToken:

GET https://service.mtcaptcha.com/mtcv1/api/checktoken?privatekey=YOUR_PRIVATEKEY&token=VERIFIED_TOKEN

Read VERIFIED_TOKEN from the submitted form field mtcaptcha-verifiedtoken (not g-recaptcha-response).

Token lifetime and single use

Verified tokens are short-lived. Validate promptly after form submit and expect one successful CheckToken per token; a second check may fail with a duplicate-token error. See Validate Token (With Private Key).

If your infrastructure requires fixed outbound IPs, use https://service2.mtcaptcha.com/mtcv1/api/checktoken and the documented allowlist in the same guide.

Troubleshooting​

SymptomWhat to check
Widget does not appearDomain allowlist and site configuration in MTCaptcha Admin Portal; browser console for script errors.
Script blocked (CSP)Allow https://service.mtcaptcha.com (and https://service2.mtcaptcha.com if you load the secondary client script per Quick Start).
invalid-token / token-expiredSubmit the latest mtcaptcha-verifiedtoken; avoid caching old POST bodies or double-submitting without refreshing the widget.
privatekey-mismatch-tokenSiteKey and PrivateKey must be from the same MTCaptcha site.
CheckToken fails from serverConfirm egress is allowed; try service2 host and IP allowlist from Validate Token.

Further reading​

Post-Migration Checklist​

  • Removed all reCAPTCHA script tags and server siteverify code paths.
  • mtcaptchaConfig with "sitekey": "YOUR_SITEKEY" is defined before mtcaptcha.min.js.
  • Form POST includes mtcaptcha-verifiedtoken and backend reads that field only.
  • Backend calls https://service.mtcaptcha.com/mtcv1/api/checktoken (or service2 per policy) and treats success: true as the only acceptance criterion.
  • Tested valid submit, expired-token path, and wrong/missing token rejection.
  • Production and dev hostnames match Admin Portal domain settings.
  • CSP/network allows MTCaptcha script and API hosts.