Schnellstart

simplecaptcha schützt Ihre Formulare unsichtbar: keine Bilderrätsel, keine Klicks, keine Cookies, kein Consent-Banner. Die Einbindung besteht aus zwei Schritten — Widget einbinden und Token serverseitig prüfen. Beide sind nötig; ohne Server-Prüfung besteht kein Schutz.

1. Widget einbinden

Fügen Sie das Script ein und markieren Sie Ihr Formular mit data-simplecaptcha:

<form method="post" action="/kontakt" data-simplecaptcha>…</form>
<script
  src="https://api.simplecaptcha.de/v1/widget.js"
  data-sitekey="sck_ihrsitekey"
  defer
></script>

Das Widget beginnt beim ersten Nutzerkontakt mit dem Formular unsichtbar im Hintergrund zu rechnen und legt das Ergebnis als verstecktes Feld simplecaptcha-response ab. Wird das Formular abgeschickt, bevor die Berechnung fertig ist, hält das Widget den Submit kurz an und schickt ihn automatisch ab, sobald das Token vorliegt. Formulare, die erst nach dem Laden in die Seite gerendert werden (React/SPA-Checkouts), werden automatisch erkannt.

Tokens sind einmalig gültig: nach jedem Submit rechnet das Widget im Hintergrund ein frisches Token, sodass auch ein wiederholter Versuch (Validierungsfehler, abgelehnte Zahlung) wieder verifiziert wird.

JavaScript-Events (optional, für SPAs)

Das Formular erhält Events mit Bubbling:

form.addEventListener('simplecaptcha:solved', () => { … })
form.addEventListener('simplecaptcha:error', (e) => console.warn(e.detail))
form.addEventListener('simplecaptcha:expired', () => { … })

Verschickt Ihr Code das Token programmatisch (fetch/XHR statt Formular-POST), lösen Sie nach dem Auslesen simplecaptcha:consume auf dem Formular aus — das Widget rechnet dann ein Ersatz-Token:

form.dispatchEvent(new CustomEvent('simplecaptcha:consume'))

2. Token serverseitig prüfen

Prüfen Sie das Feld simplecaptcha-response bei jedem Submit gegen /v1/siteverify — mit Ihrem geheimen Schlüssel (scs_…), niemals im Frontend:

curl -X POST https://api.simplecaptcha.de/v1/siteverify \
  -d "secret=scs_ihrgeheimnis" \
  -d "response=TOKEN_AUS_DEM_FORMULAR"

Antwort:

{ "success": true, "challenge_ts": "2026-07-06T13:00:00.000Z", "hostname": "ihreseite.de" }

Mit SDK:

// Node — npm install @simplecaptcha/node
import { SimpleCaptcha } from '@simplecaptcha/node'
const captcha = new SimpleCaptcha({ secret: process.env.SIMPLECAPTCHA_SECRET })
const result = await captcha.verify(req.body['simplecaptcha-response'])
if (!result.success) return res.status(400).send('Captcha fehlgeschlagen')

// PHP — composer require simplecaptcha/simplecaptcha
$captcha = new \SimpleCaptcha\SimpleCaptcha($_ENV['SIMPLECAPTCHA_SECRET']);
$result = $captcha->verify($_POST['simplecaptcha-response'] ?? null);
if (!$result->success) { http_response_code(400); exit('Captcha fehlgeschlagen'); }

3. Testen ohne echte Schlüssel

Legen Sie im Dashboard einen Test-Schlüssel an (Häkchen „Testmodus“): Er funktioniert auf localhost, akzeptiert jedes Token und wird niemals abgerechnet. Die Antwort enthält dann "is_test": true.

Wichtige Hinweise

• Jedes Token ist einmalig. Ein zweiter /siteverify-Aufruf mit demselben Token liefert timeout-or-duplicate. Prüfen Sie genau einmal.
• Fehlercodes behandeln — siehe Fehlercodes, insbesondere quota-exceeded (Empfehlung).
• Kein JavaScript, kein Token — Empfehlung für diesen Fall: Umgang mit fehlendem Token.