Skip to main content

Migration from hCaptcha

This guide helps you migrate from hCaptcha to MTCaptcha while keeping the same overall pattern: load a client script, render a widget, then verify a token on the server.

Why migrate from hCaptcha​

  • Privacy and GDPR alignment: Standardize on MTCaptcha’s privacy-conscious model and documented GDPR posture. See Privacy GDPR Compliance.
  • WCAG 2.1 AAA accessibility: Improve outcomes for users who need keyboard, screen-reader, or low-friction flows. See Accessibility Compliance.
  • Global reliability, including China: Ensure consistent delivery where third-party CAPTCHA networks can be throttled or blocked. See Works in China.

Migration at a glance​

hCaptchaMTCaptcha
Client scripthttps://js.hcaptcha.com/1/api.jshttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget class.h-captcha (container <div class="h-captcha" data-sitekey="…"></div>).mtcaptcha (use <div class="mtcaptcha"></div>)
Token nameh-captcha-response (form field or callback)mtcaptcha-verifiedtoken (hidden input name)
Backend APIPOST https://api.hcaptcha.com/siteverify (secret + response)GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Server-side verification only

Perform CheckToken on your server only. Never ship your MTCaptcha PrivateKey to the browser.

Step 1: Replace client-side script and widget​

<!-- Remove [hCaptcha] -->
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
<div class="h-captcha" data-sitekey="YOUR_HCAPTCHA_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

Declare mtcaptchaConfig with "sitekey" before the <script src="...mtcaptcha.min.js"> tag so initialization picks up your site key.

If you used hCaptcha callbacks (data-callback, data-expired-callback, etc.), remap that logic to MTCaptcha’s JS APIs or status callbacks. See JavaScript Callbacks.

Step 2: Update server-side verification​

Replace siteverify requests with MTCaptcha CheckToken:

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

Use the posted value of mtcaptcha-verifiedtoken as token.

Token lifetime and single use

Expect tokens to expire quickly and to be usable once for CheckToken under normal settings. See Validate Token (With Private Key).

For strict egress controls, use https://service2.mtcaptcha.com/mtcv1/api/checktoken and the IP list documented in Validate Token.

Troubleshooting​

SymptomWhat to check
Widget missingAdmin Portal domain/site settings; remove leftover hCaptcha-only markup.
CSP blocks scriptAllow https://service.mtcaptcha.com (and service2 if you use the secondary loader from Quick Start).
Stale h-captcha-response handlingUpdate all server parsers and integration tests to mtcaptcha-verifiedtoken.
token-expiredUser waited too long; refresh widget and resubmit.
token-duplicate-cal / reuseDo not call CheckToken twice on the same token unless your policy explicitly allows it.
Callback never runsRe-wire hCaptcha callbacks to MTCaptcha equivalents (JS Callbacks).

Further reading​

Post-Migration Checklist​

  • Removed hCaptcha script and h-captcha-response handling end-to-end.
  • mtcaptchaConfig uses "sitekey": "YOUR_SITEKEY" before loading mtcaptcha.min.js.
  • Backend verifies mtcaptcha-verifiedtoken via https://service.mtcaptcha.com/mtcv1/api/checktoken.
  • Callback/async flows updated and regression-tested.
  • Valid submission, invalid token, and duplicate-check paths tested.
  • CSP and firewall rules updated for MTCaptcha script and API.