Migrate to TrustCaptcha Version 3.0

This guide lists only the changes that existing v2 integrations need to act on to upgrade to v3. Additive new features and internal improvements are documented in the release notes linked at the start of each section below.

We released version 3.0 of TrustCaptcha in May 2026. This release covers both the CAPTCHA widget (frontend) and the backend libraries.

Versions 2.x and 3.x can both be used for now. Version 1.x is deprecated. We recommend upgrading to v3 as soon as possible to benefit from the improved widget, error handling, and configurability.

For all changes — including the additive ones not listed here — see the Widget Release Notes.

• Several attributes were renamed — see the renamed attributes table below. This is the most impactful change and applies to all integrations.
• captchaFailed event detail is now an object ({ errorCode, message }) instead of a plain string. Update any handlers that read event.detail.
• Some error codes were removed: UNAUTHORIZED, MODES_NOT_MATCHING, SITE_KEY_NOT_VALID, OPTION_NOT_AVAILABLE. If your code branches on them, switch to the matching v3 codes — see the Widget Overview error code table.
• White Label is now its own license feature. If your integration uses whiteLabel (formerly hideBranding), re-copy the license key from your CAPTCHA settings once.

Bump the version segment of the script URL from 2.2.x to 3.0.x (or pin to a specific version like 3.0.1). The module format does not change — keep whichever you used before (esm, umd, or cjs):

<!-- Before (2.x) -->
<script src="https://cdn.trustcomponent.com/trustcaptcha/2.2.x/trustcaptcha.<esm|umd|cjs>.min.js"></script>

<!-- After (3.0) -->
<script src="https://cdn.trustcomponent.com/trustcaptcha/3.0.x/trustcaptcha.<esm|umd|cjs>.min.js"></script>

<!-- Before (2.x) -->
<trustcaptcha-component
  sitekey="<your_site_key>"
  mode="minimal"
  width="full"
  license="<license-key>"
  hide-branding
  custom-translations='[{"language":"en","boxCompleted":"I am a happy human"}]'
  custom-design='{"theme":{"light":{"boxDefaultBackground":"#eab308"}}}'
></trustcaptcha-component>

<!-- After (3.0) -->
<trustcaptcha-component
  sitekey="<your_site_key>"
  minimal-data-mode="true"
  full-width="true"
  license-key="<license-key>"
  white-label="true"
  translations='[{"language":"en","boxCompleted":"I am a happy human"}]'
  design='{"theme":{"light":{"boxDefaultBackground":"#eab308"}}}'
></trustcaptcha-component>

Go to the JavaScript-Guide

npm i @trustcomponent/trustcaptcha-angular@^3.0.1

Requires Angular 17 or newer. The library now ships standalone components only — if your app still uses NgModules, add TrustcaptchaComponent to the module’s imports array.

Go to the Angular-Guide

npm i @trustcomponent/trustcaptcha-react@^3.0.1

Supports React 18 and 19.

Go to the React-Guide

npm i @trustcomponent/trustcaptcha-vue@^3.0.1

Requires Vue 3.3 or newer.

Go to the Vue-Guide

For all changes — including the additive ones not listed here — see the Backend Release Notes.

• Class renamed: CaptchaManager → TrustCaptcha.
• Parameter renamed: secretKey → apiKey (values unchanged).
• Two new dedicated exceptions: VerificationResultExpiredException (HTTP 410) and VerificationResultRetrievalLimitReachedException (HTTP 429). Previously collapsed into a single error — split if your code branches on them.
• Result schema dropped reason, mode, creationTimestamp, releaseTimestamp, retrievalTimestamp and added decisionType, decisionAction, riskScoringEnabled, minimalDataModeEnabled, countryCode plus 5 timestamps. See the Result Validation overview for the complete schema.
• Verification token simplified — now contains only verificationId and expiresAt. Old tokens still parse, extra fields are silently ignored.
• Language-specific notes (module/file paths, dependencies) are listed in the per-language sections below.

The minimum migration per language is shown next — bump the dependency, rename the call site, you’re done. For configured usage (custom API host, timeouts, proxy), see the language-specific guide.

# Module path bumped to /v3
go get github.com/trustcomponent/trustcaptcha-go/v3@v3.0.0

// Before (v2)
result, err := trustcaptcha.GetVerificationResult(secretKey, token)

// After (v3)
result, err := trustcaptcha.GetVerificationResult(apiKey, token)

Go to the Go-Guide

dotnet add package TrustComponent.TrustCaptcha --version 3.0.0

// Before (v2)
var result = await CaptchaManager.GetVerificationResult(secretKey, token);

// After (v3)
var result = await TrustCaptcha.GetVerificationResultAsync(apiKey, token);

Go to the DotNet-Guide

<dependency>
  <groupId>com.trustcomponent</groupId>
  <artifactId>trustcaptcha</artifactId>
  <version>3.0.0</version>
</dependency>

// Before (v2)
VerificationResult result = CaptchaManager.getVerificationResult(secretKey, token);

// After (v3)
VerificationResult result = TrustCaptcha.getVerificationResult(apiKey, token);

Go to the JVM-Guide

npm i @trustcomponent/trustcaptcha-nodejs@^3.0.0

// Before (v2)
const result = await CaptchaManager.getVerificationResult(secretKey, token);

// After (v3)
const result = await TrustCaptcha.getVerificationResult(apiKey, token);

Go to the NodeJS-Guide

composer require trustcomponent/trustcaptcha-php:^3.0

composer/ca-bundle is no longer a required runtime dependency.

// Before (v2)
$result = CaptchaManager::getVerificationResult($secretKey, $token);

// After (v3)
$trustCaptcha = new TrustCaptcha($apiKey);
$result = $trustCaptcha->getVerificationResult($token);

Go to the PHP-Guide

pip install "trustcaptcha>=3.0.0,<4.0.0"

The module is now imported from trustcaptcha.trust_captcha (was trustcaptcha.captcha_manager).

# Before (v2)
result = CaptchaManager.get_verification_result(secret_key, token)

# After (v3)
trust_captcha = TrustCaptcha(api_key)
result = trust_captcha.get_verification_result(token)

Go to the Python-Guide

gem install trustcaptcha -v '~> 3.0'

The file is now required as 'trustcaptcha/trust_captcha' (was 'trustcaptcha/captcha_manager').

# Before (v2)
result = CaptchaManager.get_verification_result(secret_key, token)

# After (v3)
trust_captcha = TrustCaptcha.new(api_key)
result = trust_captcha.get_verification_result(token)

Go to the Ruby-Guide

cargo add trustcaptcha@^3.0

The module path is now trustcaptcha::trust_captcha (was trustcaptcha::captcha_manager).

// Before (v2)
let result = CaptchaManager::get_verification_result(secret_key, token).await?;

// After (v3)
let trust_captcha = TrustCaptcha::builder(api_key).build()?;
let result = trust_captcha.get_verification_result(token).await?;

Go to the Rust-Guide

If you call our REST API directly instead of using one of the libraries, the v3 changes are:

• Endpoint: /v2/verifications/{verificationId}/results.
• Authorization: standard Authorization: Bearer <apiKey> header (was a custom header in v2).
• Response schema: see the Result Validation overview for the full v3 schema. The same field changes documented above apply to the raw JSON response.
• New status codes you may now receive: 410 Gone (result expired), 429 Too Many Requests (max-fetch limit reached), and 412 Precondition Failed (rejected client-failover claim — see Failover Behavior for context).

These changes apply consistently to every TrustCaptcha CMS / platform plugin. Stored option values are preserved — old settings keep working and are translated to the new schema at render time.

• Backend libraries upgraded to v3 — the v3 API key replaces the v2 “Secret Key”. The stored value is unchanged.
• White Label is now its own license feature. If your integration uses White Label (formerly “Hide Branding”), re-copy the license key from your CAPTCHA settings once.
• Self-hosted widget JavaScript — plugins now ship the trustcaptcha.umd.min.js bundle locally instead of loading it from our CDN. The only exception is the Webflow Designer Extension, which continues to inject the script from cdn.trustcomponent.com because Webflow’s CSP does not allow customer-bundled scripts.
• New “Failover” toggle — when enabled, CAPTCHA submissions are accepted if our verification API is unreachable from your server, so forms keep working during a TrustCaptcha outage. Client-reported failover claims are always rejected. See the Failover Behavior overview for details.
• Threshold floor raised to 0.20 — values below are clamped server-side. Existing configurations with very low thresholds become a bit stricter on upgrade.
• Label refresh in the plugin UI:
  • “Secret Key” → “API Key”
  • “Hide Branding” → “White Label / Hide Branding”
  • “Mode” → “Minimal Data Mode” with options “Disabled” / “Enabled” (stored values standard / minimal are unchanged)

Update via Plugins → Updates, the official WordPress Plugin Directory, or by downloading and re-uploading the latest plugin file. Existing settings are kept.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the WordPress-Guide

Download and install the latest plugin file under Extensions → My extensions → Upload extension. Existing settings are kept.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the Shopware 6-Guide

Download the latest plugin file, uninstall the old 2.x plugin (settings will be preserved if you keep user data), upload the new ZIP under Plug-ins → Plug-in manager → Upload, and install it.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the JTL-Shop-Guide

composer require trustcomponent/trustcaptcha-typo3:^3.0

Or upload the latest extension ZIP via the TYPO3 Extension Manager. After upgrade, run typo3 cache:flush and reload the extension configuration once to pick up the new settings.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the TYPO3-Guide

Download the latest plugin file, replace the old JAR in your Keycloak providers directory, and restart your Keycloak server.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the Keycloak-Guide

composer require trustcomponent/trustcaptcha-magento2:^3.0
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The Composer requirement of trustcomponent/trustcaptcha-php:^3.0 is resolved automatically.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the Magento 2-Guide

composer update trustcaptcha/trustcaptcha-craftcms
./craft up

Or update from Settings → Plugins in the Craft control panel. Existing settings are kept.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the CraftCMS-Guide

The Webflow Designer Extension is currently in review with Webflow’s marketplace team. Once approved, it will roll out automatically to your installed app.

To migrate existing CAPTCHA components on your site to the v3 attribute schema, simply open and re-save each TrustCaptcha element — the extension auto-converts legacy v2 attributes to v3 on save.

If you use the White Label feature, re-copy the license key from your CAPTCHA settings once after the upgrade.

Go to the Webflow-Guide