Ü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:
Schutz vor Screenshot- & Replay-Betrug
Wenn eine Kassierkraft den Coupon-Barcode scannt:
-
1
Der Scanner sendet eine Anfrage an
POST /api/v1/scansmitscannedBarcodeValueund dem geheimenx-scanner-keydes Scanners. -
2
Der Server prüft, ob der Pass-Status
ACTIVEist und der aktuelle Zeitpunkt vorexpirationDateliegt. -
3
Bei Gültigkeit setzt die Datenbank den Pass-Status atomar auf
VOIDED, weistvoidReason: "SCANNED_AT_CHECKOUT"zu und protokolliert die Scan-Transaktion. -
4
Wird derselbe Pass-Barcode erneut gescannt, lehnt die Validierungs-Engine die Transaktion sofort mit dem Entscheidungscode
ALREADY_VOIDEDund der FehlermeldungPASS_VOIDED_AFTER_SCANab. -
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
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-849201",
"operatorId": "emp_sarah_m"
}
HTTP-Antwort (200 OK)
{
"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 inrequest 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=oderX-Wallet-Experience-Pin), die per SMS oder auf dem Kaufbeleg übermittelt wird. -
CRM- & E-Commerce-Korrelation (
externalId): Übergeben Sie eineexternalId(z. B.order_88412_cpn) anPOST /api/v1/passesoder/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 modeentwertet den Pass unmittelbar nach einem gültigen Scan, währendINVALIDATE_AFTER_SCAN scan modeden Status aufINACTIVE/REDEEMEDsetzt. Prüfen Sie stets, welcherScanModezu Ihren Buchhaltungs- und Wallet-Darstellungsanforderungen passt.
Erfahren Sie mehr in unserer Übersicht zu Coupons & Gutscheinen.
