Skip to content
Hilfecenter-Anleitung
3 Min. LesezeitGeprüft 2026-11-16

Coupons & Gutscheine

Starten Sie einmalige oder zeitlich begrenzte Aktionsangebote mit Scan-Validierung und automatischem Ablauf nach Einlösung.

In dieser Anleitung

Überblick

Digitale Wallet-Coupons und Gutscheine liegen direkt neben Zahlungskarten auf dem Sperrbildschirm des Smartphones und erzielen deutlich höhere Einlöseraten als E-Mail-Rabattcodes oder Papiergutscheine. Passinstance bietet kryptografischen Schutz, Einmal-Validierung zur Betrugsprävention sowie eine Entwertung der Karte in Echtzeit direkt bei der Einlösung an der Kasse.

Backend-Architektur & Pass-Typ-Zuordnung

Im Passinstance-Backend werden Coupon-Kampagnen direkt auf die offiziellen Coupon-Primitive von Apple Wallet und Google Wallet abgebildet:

  • Pass-Typ (pass type): coupon (nutzt Apples natives Coupon-Layout mit markantem Rabatt-Badge).
  • Katalog-Demo-Vorlage: promotional-coupon (während des Onboardings verfügbar).
  • Standard-Validierungsmodus: VOIDED_AFTER_SCAN scan mode.
  • Zentrale Domänenregeln:

- limitToOneActivePerPass: true: Beschränkt Smart-Download-Links auf ein einzelnes Gerät und verhindert so das Weiterteilen von Rabatt-Links in Gruppen. - expirationDate: W3C-ISO-8601-Zeitstempel, der automatisch native Sperrbildschirm-Erinnerungen vor Ablauf auslöst. - addSecurityAnimation: true: Rendert einen dynamischen holografischen Rahmen rund um 2D-Barcodes, um statische Screenshot-Fälschungen zu unterbinden.

Einlösung & Anti-Betrugs-Ausführung

Der Einlöseprozess an der Kasse garantiert strikte Einmal-Integrität durch atomare Datenbanktransaktionen im Pass Mechanics Engine:

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
COUPON-EINLÖSUNG & ENTWERTUNG
BETEILIGTE SYSTEMKOMPONENTEN
P1 Kunden-Wallet-Pass
P2 Scanner / POS-Terminal
P3 Passinstance Core API
SCHRITT 1 ANFRAGE / AKTION Barcode-QR vorzeigen
›
(PI-CPN-849201)
SCHRITT 2 ANFRAGE / AKTION POST/api/v1/scans
›
Header: x-scanner-key
›
Body: {scannedBarcodeVal}
SCHRITT 3 ANFRAGE / AKTION Prüfe status === ACTIVE
SCHRITT 4 ANFRAGE / AKTION Prüfe expirationDate >= now()
SCHRITT 5 ANFRAGE / AKTION Atomares Update:
›
status = VOIDED,
›
oidedAt = now()
SCHRITT 6 ANTWORT 200 OK
SCHRITT 7 ANFRAGE / AKTION APNs Push & Google PATCH
›
{ decision: "SUCCESS",
›
(Stilles Update an Gerät)
SCHRITT 8 ANTWORT Karte ausgegraut & entwertet == status: "ACCEPTED" }

Schutz vor Screenshot- & Replay-Betrug

Wenn eine Kassierkraft den Coupon-Barcode scannt:

  1. 1
    Der Scanner sendet eine Anfrage an POST /api/v1/scans mit scannedBarcodeValue und dem geheimen x-scanner-key des Scanners.
  2. 2
    Der Server prüft, ob der Pass-Status ACTIVE ist und der aktuelle Zeitpunkt vor expirationDate liegt.
  3. 3
    Bei Gültigkeit setzt die Datenbank den Pass-Status atomar auf VOIDED, weist voidReason: "SCANNED_AT_CHECKOUT" zu und protokolliert die Scan-Transaktion.
  4. 4
    Wird derselbe Pass-Barcode erneut gescannt, lehnt die Validierungs-Engine die Transaktion sofort mit dem Entscheidungscode ALREADY_VOIDED und der Fehlermeldung PASS_VOIDED_AFTER_SCAN ab.
  5. 5
    Gleichzeitig reiht Passinstance eine Hintergrund-Push-Benachrichtigung an Apple APNs und Google Wallet ein. Die Karte auf dem Smartphone der Kundin oder des Kunden wird umgehend ausgegraut und mit einem sichtbaren Wasserzeichen „Redeemed“ versehen — eine erneute Nutzung an einer anderen Kasse ist ausgeschlossen.

Konkrete Scan-Request- & Response-DTOs

Kassensysteme (POS), Scanner-Terminals und E-Commerce-Checkouts kommunizieren über den Validierungsendpunkt:

HTTP-Anfrage

POST /api/v1/scans
Header
x-scanner-key sk_live_counter_register_04
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-CPN-849201",
  "operatorId": "emp_sarah_m"
}

HTTP-Antwort (200 OK)

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "passSnapshot": {
    "id": "pass_cpn_849201",
    "templateId": "tmpl_coupon_7712",
    "serialNumber": "PI-CPN-849201",
    "status": "VOIDED",
    "attributes": {
      "discount": "25% OFF",
      "terms": "Valid on purchases over €50"
    }
  }
}

Schutzmaßnahmen für Kampagnenverteilung

Beim Verteilen von Coupons über öffentliche PassFlow-Seiten, API-Erstellung oder SMS-Kampagnen stehen folgende Schutzmechanismen zur Verfügung:

  • Download-Ablauf (enableDownloadUntil): Legen Sie ein fixes Datum samt Uhrzeit fest ("YYYY-MM-DD HH:mm" oder ISO-Zeitstempel in request payload / der Vorlagenkonfiguration), nach dem nicht abgerufene Download-Links HTTP 410 Gone zurückgeben.
  • Zugangs-PIN-Schutz: Schützen Sie hochwertige Aktionslinks mit einer Zugangs-PIN (?pin= oder X-Wallet-Experience-Pin), die per SMS oder auf dem Kaufbeleg übermittelt wird.
  • CRM- & E-Commerce-Korrelation (externalId): Übergeben Sie eine externalId (z. B. order_88412_cpn) an POST /api/v1/passes oder /api/v1/passes/upsert-by-external-id, damit Einmal-Gutscheineinlösungen eindeutig in Ihrem Bestellsystem abgeglichen werden können.
  • Bindung an ein einzelnes Gerät: Aktivieren Sie limitToOneActivePerPass, sodass sich jeder personalisierte Download-Link fest an das zuerst registrierte Gerät bindet und nicht in öffentlichen Gruppen zirkulieren kann.

Wichtig: VOIDED_AFTER_SCAN scan mode entwertet den Pass unmittelbar nach einem gültigen Scan, während INVALIDATE_AFTER_SCAN scan mode den Status auf INACTIVE / REDEEMED setzt. Prüfen Sie stets, welcher ScanMode zu Ihren Buchhaltungs- und Wallet-Darstellungsanforderungen passt.

Erfahren Sie mehr in unserer Übersicht zu Coupons & Gutscheinen.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.