Eine Zeile im Shop, ein Aufruf auf Ihrem Server

Der Einbau besteht aus zwei Hälften, und die Trennung ist der eigentliche Entwurf:

Im Browser läuft die Bedienung — ein Fenster mit QR-Code, das Ihre Kundschaft durch die Prüfung führt. Das ist Anzeige, und Anzeige lässt sich mit den Entwicklerwerkzeugen umgehen.

Auf Ihrem Server sitzt der Riegel. Vor dem Bestellabschluss lösen Sie den Nachweis ein. Erst dieser Aufruf ist bindend. Wer ihn weglässt, hat eine hübsche Schranke ohne Schloss.

Geprüft wird über die staatliche E-ID (swiyu) oder — sobald die App in den Stores ist — über den Chip im Ausweis. Für Ihre Einbindung macht das keinen Unterschied: Die Schnittstelle bleibt dieselbe, nur der Weg dahinter ändert sich.

Die produktive E-ID des Bundes startet voraussichtlich Ende 2026. Damit Sie Ihre Einbindung nicht bis dahin aufschieben müssen, gibt es Testschlüssel: Sie erkennen sie am Anfang pk_test_ und sk_test_.

Eine Prüfung mit Testschlüssel spricht den Prüfdienst des Bundes gar nicht erst an. Sie steht vier Sekunden auf PENDING — damit Ihre Abfrageschleife wirklich durchläuft — und nimmt dann den Ausgang, den Sie bestellt haben.

curl -X POST https://verify.edelbyte.ch/api/v1/verifications \
  -H "Authorization: Bearer sk_test_…" \
  -H "content-type: application/json" \
  -d '{"reference":"warenkorb-4711","min_age":16,"test_outcome":"under_18"}'

min_age ist optional und nimmt die Zahl 16 oder 18. Ohne Angabe gilt die Vorgabe Ihres Shops, ab Werk 18. Im Beispiel oben prüft der Testlauf gegen 16 und liefert jemanden, der auch das nicht erreicht.

Ein unbekannter Wert wird mit 400 invalid_test_outcome abgewiesen und nicht stillschweigend zu «success» geglättet. Wer sich bei under_18 vertippt, soll es merken.

Eine Zeile ins Layout, vor dem schliessenden Body-Tag:

<script src="https://verify.edelbyte.ch/v1/gate.js"
        data-key="pk_test_…"
        data-callback="/wp-json/edelverify/v1/confirm"
        defer></script>

Ausgelöst wird über ein Attribut am Knopf — kein eigener JavaScript-Code nötig. Verlangt die Ware nur 16, kommt die Grenze an den Knopf und sticht die Vorgabe am Skript-Tag:

<button data-edelverify
        data-edelverify-reference="warenkorb-4711"
        data-edelverify-min-age="16">
  Alter bestätigen
</button>

Wer den Ablauf selbst steuern will, ruft window.EdelVerify.open() auf. Zurück kommt ein Promise:

const { verified, id } = await window.EdelVerify.open({
  reference: 'warenkorb-4711',
  min_age: 16,
  test_outcome: 'under_18', // nur mit Testschlüssel
})

min_age und test_outcome gelten für diesen einen Aufruf und gehen den Attributen am Skript-Tag vor. Ohne test_outcome nimmt eine Testprüfung immer den glücklichen Ausgang — bauen Sie Ihre Einbindung deshalb nicht ohne: der Fall, den Sie sehen müssen, ist under_18.

Zusätzlich meldet das Skript jeden Schritt am document: edelverify:started, edelverify:verified, edelverify:stored, edelverify:failed, edelverify:error und edelverify:closed. Das ist der Weg für Systeme, in denen sich kein data-callback setzen lässt.

Das Fenster hängt in einem eigenen Shadow DOM. Ihr Shop-CSS kann es nicht verschieben, und es kann Ihres nicht durcheinanderbringen.

Der Browser meldet Ihnen nur die Kennung der Prüfung. Alles Weitere macht Ihr Server mit dem geheimen Schlüssel — er verlässt Ihren Server nie.

a) Nachweis abholen. Direkt nachdem der Browser die Kennung gemeldet hat:

GET https://verify.edelbyte.ch/api/v1/verifications/<id>
Authorization: Bearer sk_test_…

→ { "status": "SUCCESS", "min_age": 18, "age_ok": true, "over_18": true,
    "proof": "av_…", "proof_expires_at": "2026-09-13T…" }

b) Nachweis einlösen. Vor jedem Bestellabschluss. Das ist der Riegel:

POST https://verify.edelbyte.ch/api/v1/proofs/verify
Authorization: Bearer sk_test_…

{ "proof": "av_…", "min_age": 16 }

→ { "valid": true, "min_age": 18, "required_min_age": 16, "over_18": true,
    "expires_at": "2026-09-13T…", "reference": "warenkorb-4711" }

Beim Einlösen sagt min_age, was die Ware verlangt. Ohne Angabe gilt 18. Zurück kommen beide Zahlen: min_age ist die Grenze, gegen die der Nachweis ausgestellt wurde, required_min_age die, gegen die eingelöst wurde. Im Beispiel oben deckt ein Nachweis ab 18 eine Ware ab 16 ab.

Ein Nachweis ab 16 löst keine Ware ab 18 ein; ein Nachweis ab 18 löst Ware ab 16 ein. Der Vergleich läuft in eine Richtung, und zwar auf unserer Seite — Sie müssen nichts nachrechnen. Wer beim Einlösen gar kein min_age mitschickt, prüft gegen 18: Ein 16er-Nachweis kommt dann als valid: false zurück.

Sobald der Schlüssel angenommen ist, antwortet dieser Aufruf immer mit HTTP 200; ob der Nachweis taugt, steht in valid. Das ist Absicht: Ein 4xx an dieser Stelle verleitet Einbindungen dazu, den Fehlerfall als «Dienst kaputt, durchlassen» zu behandeln. Auch die zu niedrige Altersstufe ist deshalb kein Fehler, sondern valid: false.

Davor steht die Anmeldung. Die läuft vor der 200-Regel: Ein unbekannter, zurückgezogener oder falscher Schlüssel wird mit 401 unauthorized abgewiesen, und ein öffentlicher pk_-Schlüssel gilt hier als falsche Art — auch er bekommt 401. Die 200-Regel gilt also für die Antwort auf Ihren Nachweis, nicht für die Anfrage an sich. Ein 401 heisst blockieren, nicht durchlassen: Wenn der Schlüssel nicht stimmt, ist überhaupt nichts geprüft.

Vier Endpunkte. Der Schlüssel geht als Authorization: Bearer … oder x-api-key.

status ist einer von PENDING, SUCCESS, FAILED oder EXPIRED. Achtung: SUCCESS heisst «die Prüfung ist abgeschlossen», nicht «alt genug». Massgeblich sind age_ok und min_age.

Zwei Altersstufen. min_age nimmt die Zahl 16 oder 18 — nicht die Zeichenkette "18". Alles andere, auch 17 oder 21, wird mit 400 invalid_min_age abgewiesen; wir raten nicht, was gemeint war. Lassen Sie das Feld weg, gilt die für Ihren Shop hinterlegte Vorgabe, ab Werk 18.

over_18 bleibt für bestehende Einbindungen erhalten, beantwortet aber ausschliesslich die 18er-Frage: Bei einer Prüfung gegen 16 steht dort false, unabhängig vom tatsächlichen Alter. Neue Einbindungen lesen age_ok zusammen mit min_age.

Herkunftsprüfung. Für den öffentlichen Schlüssel lässt sich hinterlegen, von welchen Adressen er benutzt werden darf. Solange für Ihren Shop keine Adresse hinterlegt ist, wird jede Herkunft angenommen — auch eine fremde, und auch gar keine. Erst mit dem ersten Eintrag greift die Sperre, und dann antwortet die Schnittstelle jeder nicht gelisteten Herkunft mit 403 origin_not_allowed.

Das ist so gebaut, damit eine neue Einbindung nicht an einer Kleinigkeit scheitert, bevor sie je lief. Vor dem Kundenbetrieb gehört die Liste aber gefüllt — sonst kann jede beliebige Seite Prüfungen auf Ihren Schlüssel beginnen. Diese Einstellung nehmen wir für Sie vor — sagen Sie uns Adresse und gewünschte Grenze. Einen Selbstbedienungszugang gibt es heute noch nicht.

Ein Nachweis gilt standardmässig 30 Tage und ausschliesslich bei dem Shop, für den er ausgestellt wurde.

Ein Sonderfall, damit Sie ihn nicht suchen: Beim Einlösen über /api/v1/proofs/verify gibt es für eine zu niedrige Altersstufe kein 4xx. Sobald der Schlüssel angenommen ist, antwortet dieser Aufruf immer mit 200 — die Absage steht als valid: false im Rumpf, zusammen mit required_min_age.

error_code beim Einlösen. Auch eine unbrauchbare Altersgrenze führt hier zu keinem 4xx: Ein min_age: 17 kommt als 200 zurück, mit valid: false und error_code "invalid_min_age". min_age und required_min_age stehen dann beide auf null — es wurde gar nichts geprüft. invalid_min_age gibt es also an beiden Endpunkten, nur in verschiedener Gestalt.

Das Feld error_code steht in dieser Antwort nur im Fehlerfall. Ein regulärer Einlösevorgang — gültig wie ungültig — liefert es gar nicht mit. Lesen Sie es deshalb als «vorhanden heisst: Ihre Einbindung ist zu reparieren», nicht als Feld, das Sie immer erwarten dürfen. Und behandeln Sie diesen Fall wie jede andere Absage: blockieren.

Der Stand lässt sich abfragen — er kommt aber auch von selbst, wenn Sie das wollen. So sparen Sie sich die Abfrageschleife auf Ihrem Server und erfahren das Ergebnis, sobald es feststeht.

Eingerichtet wird der Webhook mit Adresse und Geheimnis. Die Adresse muss https sein. Zugestellt wird als POST mit JSON-Rumpf. Diese Einstellung nehmen wir für Sie vor — sagen Sie uns Adresse und gewünschte Grenze. Einen Selbstbedienungszugang gibt es heute noch nicht.

POST /ihr/endpunkt
X-EdelVerify-Event: evt_…
X-EdelVerify-Signature: t=1786742825,v1=9f86d081…

{ "id": "evt_…", "type": "verification.completed",
  "created_at": "2026-08-15T09:12:44.000Z",
  "verification_id": "ver_…", "mode": "test",
  "status": "SUCCESS", "min_age": 16, "age_ok": true, "over_18": false,
  "reference": "warenkorb-4711", "error_code": null }

X-EdelVerify-Event ist die Kennung der Zustellung — merken Sie sie sich und verarbeiten Sie dieselbe Kennung nur einmal. Wiederholungen sind normal, doppelte Buchungen nicht.

Signatur prüfen. X-EdelVerify-Signature trägt zwei Werte: t ist der Zeitpunkt in Unix-Sekunden, v1 ein HMAC-SHA256 in Hex über die Zeichenfolge "<t>.<roher Rumpf>", mit Ihrem Geheimnis als Schlüssel.

• Rechnen Sie gegen den rohen Rumpf, so wie er ankam. Wer erst nach JSON wandelt und wieder zurück, bekommt eine andere Zeichenfolge und damit nie eine gültige Signatur.
• Vergleichen Sie zeitkonstant (hash_equals, crypto.timingSafeEqual), nicht mit ==.
• Weisen Sie ab, was älter oder neuer als 300 Sekunden ist. Das schliesst die Wiedereinspielung mitgeschnittener Zustellungen aus.

Wiederholungen. Nach 30 Sekunden, 2 Minuten, 10 Minuten, 1 Stunde und 6 Stunden — höchstens sechs Versuche. Als angenommen zählt nur eine 2xx-Antwort; Weiterleitungen werden nicht verfolgt, und nach 10 Sekunden ohne Antwort brechen wir ab. Antworten Sie deshalb sofort mit 200 und arbeiten Sie danach.

Damit Sie es von uns erfahren und nicht nach der Installation:

• Genau zwei Altersstufen. 16 und 18 — die beiden, die das Schweizer Recht kennt. Ein anderer Wert in min_age wird abgewiesen, nicht gerundet. Brauchen Sie eine weitere Schwelle, sagen Sie es uns.
• Die 16er-Stufe ist gebaut, aber noch nicht gegen einen echten Nachweis gemessen. In der Schnittstelle und in allen Paketen ist sie fertig, und im Testbetrieb ist die ganze Kette durchgängig belegt — Prüfung ab 16, Nachweis ab 16, Einlösen ab 16, und die Absage, wenn ein 16er-Nachweis auf Ware ab 18 trifft. Gegen einen echten Nachweis gemessen ist bisher aber nur die 18er-Frage. Ob die Beta-ID des Bundes das Merkmal age_over_16 überhaupt führt, prüfen wir vor dem ersten 16er-Piloten nach. Bauen Sie ruhig schon dagegen; setzen Sie einen 16er-Livebetrieb erst an, wenn wir das bestätigt haben.
• Ein Nachweis gilt bei einem Shop. Wer mehrere Shops betreibt, braucht je Shop ein eigenes Schlüsselpaar; die Kundschaft weist sich in jedem einmal aus. Das ist datenschutzrechtlich sauber, aber es ist eine Entscheidung und kein Versehen — sagen Sie uns, wenn Sie es anders brauchen.
• Die Schweizer Identitätskarte hat keinen Chip. Für den Ausweis-Weg brauchen Sie einen Pass oder einen Ausländerausweis. Die biometrische ID wird für Ende 2026 erwartet.

Fehlt Ihnen etwas davon dringend? Schreiben Sie uns — die Reihenfolge richtet sich danach, was Shops wirklich blockiert.