Widget

Stand: 18. August 2026

Das Widget zeigt in deiner Kasse eine kompakte Zeile und darin einen Knopf. Beim Klick öffnet sich ein Dialog mit QR-Code auf dem Desktop oder einem Wallet-Button auf dem Handy. Es hat keine Abhängigkeiten und keinen Build-Schritt – es muss in jeder Umgebung überleben, die ein Shop schon geladen hat.

Das Widget sieht deinen API-Schlüssel nie. Es bekommt ID und Einweg-Token.

<script src="https://api.valyda.ch/widget/v1/valyda.js"></script>

Einbinden

const handle = Valyda.mount({
  el: '#valyda',
  apiBase: 'https://api.valyda.ch',
  profile: 'age-over-18',
  createSession() {
    return fetch('/meine-route/verifikation', { method: 'POST' })
      .then(r => r.json())          // {id, token, deeplink}
  },
  onSuccess() { form.submit() },
  fallback: { label: 'Ausweis hochladen', onSelect() { /* … */ } },
})

createSession wird erst aufgerufen, wenn die Kundin den Dialog öffnet. Das ist der empfohlene Weg: Verifikationen laufen ab, und die meisten Kassenaufrufe kommen nie bis zur Prüfung. Wer die Sitzung im Voraus erstellt, hat sie bei einem langsam ausgefüllten Formular oft schon verloren.

Alternativ übergibst du verificationId und token direkt; die Sitzung wird dann so verwendet, wie sie ist.

Optionen

Option	Bedeutung
`el`	Zielelement oder CSS-Selektor
`apiBase`	Basis-URL der API
`createSession`	Rückruf, liefert `{id, token, deeplink}` – bevorzugt
`verificationId`, `token`, `deeplink`	Vorab erstellte Sitzung statt `createSession`
`profile`	Profilkennung, steuert die Wortwahl im Dialog
`title`, `intro`	Überschreiben Titel und Hinweistext der Zeile
`verified`	`true` zeigt sofort das Ergebnis – für bereits geprüfte Warenkörbe
`lang`	Sprache; ohne Angabe nach Dokumentsprache
`pollIntervalMs`	Abfrageabstand, Minimum 1500 ms, Standard 2500 ms
`fallback`	`{label, onSelect}` – alternatives Verfahren, siehe unten

Ereignisse

Jedes Ereignis wird doppelt gemeldet: als Rückruf in den Optionen und als gepufferter DOM-Event auf dem Zielelement.

Rückruf	Event	Wann
`onSuccess`	`valyda:success`	Prüfung bestanden
`onFailure`	`valyda:failure`	Prüfung abgelehnt oder nicht erfüllt
`onExpired`	`valyda:expired`	Sitzung abgelaufen
`onError`	`valyda:error`	Netzwerk- oder Erstellungsfehler
`onFallback`	`valyda:fallback`	Kundin wählt das alternative Verfahren
`onRestart`	–	Kundin startet nach einem Fehlschlag neu

document.querySelector('#valyda')
  .addEventListener('valyda:success', () => form.submit())

Rückgabewert

mount liefert einen Griff mit open(), close(), refresh() und destroy(). refresh() fragt den Status sofort ab, destroy() hält die Abfrage an und räumt das Element leer – nötig, wenn deine Kasse ihr Markup neu aufbaut.

Der Rückfallweg

Heute hat kaum jemand eine Wallet. Ohne Alternative verlierst du die Bestellung.

fallback: {
  label: 'Ausweis hochladen',
  onSelect() { meinBisherigesVerfahren() },
}

Der Eintrag erscheint als unauffälliger Link unter dem Dialog. Was danach passiert, ist deine Sache – das Widget schliesst sich und meldet valyda:fallback.