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.

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

<!-- After (3.0) -->
<script type="module" src="https://cdn.trustcomponent.com/trustcaptcha/3.0.x/trustcaptcha.esm.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.0

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.0

Supports React 18 and 19.

Go to the React-Guide

npm i @trustcomponent/trustcaptcha-vue@^3.0.0

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).

Plugin updates for our CMS and platform integrations (WordPress, CraftCMS, Keycloak, Magento 2, TYPO3, Webflow, Shopware 6) are not yet released. Until they are, continue to use the existing 2.x plugins — they keep working with the v3 backend libraries. We will add per-platform migration notes here once the corresponding releases are published.