TrustedCaptcha

Before you start.

You'll need: an existing reCAPTCHA integration that's working, fifteen minutes of focused attention, and access to deploy a new environment variable. That's it. There's no schema migration, no data export, no DNS change, no traffic cutover plan. The migration is a config edit and a script tag swap.

One thing worth noting up front: TrustedCaptcha's free tier is 1,000 verifications per day, and reCAPTCHA's is 1,000,000 per month. If you're at the very high end of the reCAPTCHA free tier (more than ~33k/day), you'll want to plan for the €25/month Pro plan from day one. For typical SaaS volumes — login, signup, contact forms, comments — the free tier is sufficient.

Step 1 — Sign up and add a site.

Create a free account at trustedcaptcha.com/signup. Verify your email. From the dashboard, click "Add site" and enter:

Site name — any human-readable label.
Hostnames — your production hostnames, comma-separated. example.com, www.example.com. You can use *.example.com for subdomains. Add localhost if you want to test locally.
Default mode — leave on "auto" unless you have a specific need; the risk engine will pick the right mode per challenge.

You'll be shown the sitekey (safe to commit to source) and the secret (treat like a password — store in environment variables, never in client-side code). The secret is shown once; copy it now.

Step 2 — Update the script tag.

Find your current reCAPTCHA script tag — usually in your site's <head>:

<!-- OLD -->
<script src="https://www.google.com/recaptcha/api.js" async defer></script>

Replace it with:

<!-- NEW -->
<script src="https://cdn.trustedcaptcha.com/widget/v1/api.js" async defer></script>

That's the entire client-side change for the script. The widget loader is feature-compatible — ?onload=cb&render=explicit works the same way reCAPTCHA does.

Step 3 — Update the widget div.

Find your reCAPTCHA widget div:

<!-- OLD -->
<div class="g-recaptcha" data-sitekey="6Lc..."></div>

Replace with:

<!-- NEW -->
<div class="trustedcaptcha" data-sitekey="0x..."></div>

If you're using g-recaptcha with explicit options (data-callback, data-theme, data-size, data-action), all of those work as data-callback, data-theme, data-size, data-action on TrustedCaptcha too. The names are the same.

Important compatibility note: the TrustedCaptcha widget will fill any existing g-recaptcha-response hidden input on submit. If your server-side code reads the form field by name g-recaptcha-response, you don't have to change a thing on that side either. We support that field name explicitly to make the migration painless.

Step 4 — Change your server-side verify URL.

This is the only meaningful server-side change. Find the place where your code POSTs to https://www.google.com/recaptcha/api/siteverify:

// OLD
$endpoint = 'https://www.google.com/recaptcha/api/siteverify';

// NEW
$endpoint = 'https://challenges.trustedcaptcha.com/api/v1/siteverify';

The POST body shape is identical (secret, response, remoteip) and the response shape is API-compatible — same JSON structure, same success boolean, same error_codes array, same challenge_ts, hostname, and action fields. The score field is also present and behaves equivalently to reCAPTCHA v3's score (0.0 to 1.0, higher = more human).

Update your secret environment variable to the TrustedCaptcha secret from Step 1. Most setups use RECAPTCHA_SECRET as the var name; rename to TRUSTEDCAPTCHA_SECRET or TC_SECRET while you're in there, but it's not required.

Step 5 — Test, deploy, monitor.

In your local environment, fill in the form, submit it, and verify the response from /api/v1/siteverify shows "success": true. Open your TrustedCaptcha dashboard — the verification will show up under the site's stats within seconds.

Deploy to production. Monitor the success rate in the dashboard for the first hour. If anything looks off — high failure rate, low score, hostname mismatches — email support@trustedcaptcha.com with the site ID and we'll help triage.

Common gotchas.

Hostname mismatch. If you see hostname-mismatch error codes in your verify responses, your form is being submitted from a hostname not in your site's allowlist. Add it on the site detail page in the dashboard.

Lingering reCAPTCHA cookies. Google's _GRECAPTCHA cookie persists in users' browsers after migration. It's harmless — just stale data — and Google will eventually expire it. There's nothing you need to do about it.

Content Security Policy. If you have a strict CSP, add https://challenges.trustedcaptcha.com to frame-src and https://cdn.trustedcaptcha.com to script-src. You can keep https://www.google.com there during a parallel-run period if you want extra safety.

Score thresholds. If you were using reCAPTCHA v3 with a custom score threshold (e.g., reject below 0.5), the same threshold value works for TrustedCaptcha. The score semantics are equivalent.

Rolling back.

If something doesn't work, you can roll back by reversing Steps 2 and 4. Your old reCAPTCHA sitekey/secret remain valid in your Google Cloud account; nothing is destroyed. We'd appreciate an email about what went wrong, but you're not locked in — that's the whole point.

Start the migration → Read the API docs →