Dokumentation
Für die Beta-Infrastruktur des Bundes. Stand: 26. Juli 2026
Grundprinzip
Zwei Regeln bestimmen jede Integration:
- Der API-Schlüssel bleibt auf Ihrem Server. Gelangt er in den Browser, kann jeder Besucher Prüfungen auf Ihre Kosten auslösen.
- Dem Browser wird nicht geglaubt. Bevor Sie eine Bestellung freigeben, holen Sie das Ergebnis serverseitig ab. Was die Seite anzeigt, ist Bedienkomfort, kein Nachweis.
Ablauf
- Ihr Backend erstellt eine Verifikation und erhält ID, Einweg-Token und Wallet-Deeplink.
- Ihre Seite zeigt QR-Code oder Button und fragt mit dem Einweg-Token den Status ab.
- Die Kundin bestätigt in der Wallet.
- Ihr Backend prüft das Ergebnis und gibt die Bestellung frei.
Verifikation erstellen
Serverseitig, mit Ihrem API-Schlüssel:
| Endpunkt | POST https://api.valyda.ch/v1/verifications |
|---|---|
| Kopfzeile | Authorization: Bearer <api-key> |
| Körper | {"profile": "age-over-18", "client_reference": "bestellung-4711"} |
Die Antwort enthält id, public_token, deeplink
und expires_at. Die Referenz ist frei wählbar, darf aber keine
Personendaten enthalten.
Prüfprofile
| Profil | Übermittelt |
|---|---|
age-over-18 | nur ja/nein |
age-over-16 | nur ja/nein |
identity-full | Vorname, Name, Geburtsdatum |
Status abfragen
Serverseitig mit dem API-Schlüssel über
GET /v1/verifications/<id>. Der Status ist
PENDING, SUCCESS, FAILED oder
EXPIRED; bei Erfolg steht satisfied auf true.
Widget einbinden
Das Widget zeigt auf dem Desktop einen QR-Code und auf dem Handy einen Button, der die Wallet öffnet. Es erhält nur ID und Einweg-Token, niemals Ihren Schlüssel.
| Skript | https://api.valyda.ch/widget/v1/valyda.js |
|---|---|
| Aufruf | Valyda.mount({ el, verificationId, token, apiBase, onSuccess }) |
Optional lässt sich ein alternatives Prüfverfahren hinterlegen, das angeboten wird, wenn jemand keine Wallet hat.
Webhooks
Statt abzufragen können Sie sich benachrichtigen lassen. Jede Zustellung trägt den
Kopfzeileneintrag valyda-signature im Format
t=<zeitstempel>,v1=<hmac>. Signiert wird
"<zeitstempel>.<body>" mit dem Secret aus Ihrem Dashboard.
Prüfen Sie die Signatur, bevor Sie den Inhalt verwenden – und prüfen Sie den
Zeitstempel, um alte Zustellungen abzuweisen.
Grenzen der Beta
Bis zum produktiven Start der E-ID am 1. Dezember 2026 arbeitet der Dienst gegen die Beta-Infrastruktur des Bundes. Prüfungen haben in dieser Zeit keine rechtliche Beweiskraft.