Skip to main content

Migration from ALTCHA SaaS

This guide helps you migrate from ALTCHA SaaS / hosted verification (cloud challenge + vendor verify API or widget you embed from ALTCHA) to MTCaptcha using mtcaptchaConfig, the standard client script, and the CheckToken API.

Why migrate from ALTCHA SaaS​

  • Privacy and GDPR alignment: Consolidate on MTCaptcha’s documented GDPR-conscious approach. See Privacy GDPR Compliance.
  • WCAG 2.1 AAA accessibility: Standardize UX and conformance claims on MTCaptcha. See Accessibility Compliance.
  • Global reliability, including China: Reduce dependence on vendor-specific regional behavior; use MTCaptcha’s documented China path. See Works in China.

Migration at a glance​

ALTCHA SaaSMTCaptcha
Client scriptALTCHA-hosted snippet or package referenced by your integration docshttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget classALTCHA-provided widget/container (per your current embed).mtcaptcha (<div class="mtcaptcha"></div>)
Token nameField name from ALTCHA response (per your integration)mtcaptcha-verifiedtoken
Backend APIALTCHA SaaS verify endpoint you call todayGET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Server-side verification only

Call CheckToken from your backend only. Never expose the MTCaptcha PrivateKey in client apps or mobile bundles.

Step 1: Replace client-side script and widget​

<!-- Remove [ALTCHA SaaS] — vendor widget script, init snippet, and container -->

<!-- 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 the script tag that loads mtcaptcha.min.js.

Step 2: Replace server-side verification call​

Use MTCaptcha CheckToken:

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

Map your former ALTCHA token field to mtcaptcha-verifiedtoken.

Token lifetime and single use

Validate immediately after solve when possible. See failure codes in Validate Token (With Private Key).

Use https://service2.mtcaptcha.com/mtcv1/api/checktoken if you need allowlisted outbound IPs.

Troubleshooting​

SymptomWhat to check
Old vendor keys in envRemove ALTCHA API keys and secrets from config stores.
privatekey-mismatch-tokenSiteKey and PrivateKey must be a matched pair in Admin Portal.
CSP / adblockAllow-list MTCaptcha script host; test incognito without extensions.
token-expiredSlow form path or reused POST; refresh challenge.

Further reading​

Post-Migration Checklist​

  • Removed ALTCHA SaaS embeds and verification HTTP calls.
  • mtcaptchaConfig uses "sitekey": "YOUR_SITEKEY" before mtcaptcha.min.js.
  • Backend uses mtcaptcha-verifiedtoken and https://service.mtcaptcha.com/mtcv1/api/checktoken.
  • Secrets rotation: old ALTCHA credentials revoked.
  • Staging + production domains configured in Admin Portal.
  • Alerts/dashboards updated for new error rates.