Migrate from MTCaptcha

The following tutorial will guide you on how to migrate from MTCaptcha to TrustCaptcha on your website.

You should have already completed the following steps before you start to integrate TrustCaptcha into your website.

1. Read Get-Started: Get a quick overview of the concepts behind TrustCaptcha and the integration process in get started.

2. Existing CAPTCHA: If you don’t have a CAPTCHA yet, sign in or create a new user account. Then create a new CAPTCHA.

MTCaptcha and TrustCaptcha both follow the same basic idea: your frontend produces a token and your backend verifies it. The migration is mainly about replacing the frontend widget and updating the server-side validation.

In practice, you will:

• Remove the MTCaptcha JavaScript and the MTCaptcha widget container from your pages.
• Add the TrustCaptcha dependency and the <trustcaptcha-component> web component.
• Replace the token field you send to your backend with the TrustCaptcha token field (tc-verification-token by default).
• Replace your server-side verification call to MTCaptcha with TrustCaptcha result validation.

Follow these steps to migrate from MT-CAPTCHA to TrustCaptcha.

Most MTCaptcha setups contain these two parts:

1. A script tag provided by MTCaptcha (domain and exact snippet may differ depending on your setup).
2. A widget container (often a div) inside your form where MTCaptcha renders the widget.

Remove both from your page. If you also used custom callbacks or special “on success” submit logic, remove that too. We will replace it with TrustCaptcha’s widget behavior and events.

TrustCaptcha provides a web component called trustcaptcha-component. It must be placed inside a <form> element and needs a TrustCaptcha sitekey.

<script src="https://cdn.trustcomponent.com/trustcaptcha/2.1.x/trustcaptcha.umd.min.js"></script>

<form>
  <!-- your input fields -->

  <trustcaptcha-component
    sitekey="<your_trustcaptcha_site_key>"
  ></trustcaptcha-component>

  <!-- further input fields / submit button -->
</form>

When TrustCaptcha completes, it automatically writes a hidden form field named tc-verification-token. You can also listen to the captchaSolved event if you want to send the token using JavaScript.

For detailed frontend integrations, use the guides below.

With MTCaptcha, the token field name depends on your integration. In many setups, MTCaptcha submits a hidden field (or you read a token in your custom callback) and forward it to your backend.

With TrustCaptcha, the field is tc-verification-token by default.

This means: update the backend code that reads the token and switch it to the TrustCaptcha field name. If you submit via JavaScript, you can read the token from the event:

<script>
  const trustcaptchaComponent = document.getElementsByTagName('trustcaptcha-component')[0];

  trustcaptchaComponent.addEventListener('captchaSolved', (event) => {
    const verificationToken = event.detail;
    // Send verificationToken to your backend (e.g., JSON body).
  });
</script>

With MTCaptcha, you typically call an API endpoint provided by MTCaptcha to verify the token and check whether it is valid.

With TrustCaptcha, you retrieve the verification result from our API using:

• the verification token from your frontend (tc-verification-token)
• the TrustCaptcha secret-key (from your CAPTCHA settings)

// Retrieving the verification result
let verificationResult;
try {
    verificationResult = await CaptchaManager.getVerificationResult("<your_secret_key>", "<verification_token_from_your_client>");
} catch (error) {
    // Fetch verification result failed - handle error
}

Then you decide what to do based on the returned result (for example, verificationPassed and the score).

// Act on the verification result (sample)
const threshold = 0.5;
if (!verificationResult.verificationPassed || verificationResult.score > threshold) {
    console.log("Verification failed or bot score > 0.5 – possible automated request.");
} else {
    console.log("Everything looks good - probably a human.");
}

Please follow the result validation overview, and (optionally) use one of the ready-made backend integrations.

Once you have successfully installed and configured TrustCaptcha on your website, you can use TrustCaptcha to its full extent. However, we still recommend the following additional technical and organizational measures:

• Security rules: You can find many security settings for your CAPTCHA in the CAPTCHA settings. These include, for example, authorized websites, CAPTCHA bypass for specific IP addresses, bypass keys, IP based blocking, geoblocking, individual difficulty and duration of the CAPTCHA, and much more. Learn more about the security rules.

• Data protection: Include a passage in your privacy policy that refers to the use of TrustCaptcha. We also recommend that you enter into a data processing agreement with us to stay GDPR-compliant. Learn more about data protection.

• Accessibility: Customize TrustCaptcha to your website so that your website is as accessible as possible and offers the best possible user experience. More about accessibility.

• Testing: If you use automated testing, make sure that the CAPTCHA does not block it. Learn more about testing.