Überblick
Einmalig einlösbare Aktionscoupons und Gutscheine erfordern eine strikt atomare Validierung, damit ein Pass niemals doppelt über verschiedene Kassen hinweg eingelöst oder per statischem Screenshot weitergegeben werden kann. Indem Sie eine Coupon-Vorlage mit einer auf VOIDED_AFTER_SCAN scan mode eingestellten ScannerConfiguration kombinieren, validiert Passinstance den Barcode, setzt den Pass auf VOIDED, blockiert Wiederholungsversuche und löst unmittelbar ein stilles Wallet-Update aus, das den Pass auf dem Gerät des Kunden ausgraut.
Wichtig: Übermitteln Sie bei Einlösungen von POS-Terminals stets einen Idempotenzschlüssel (
x-idempotency-key-Header beiPOST /api/v1/scansbzw.idempotencyKeyinrequest payloadbeiPOST /v1/pos/redeem). Falls ein Terminal nach einem Netzwerk-Timeout einen erneuten Versuch sendet, gibt Passinstance den ursprünglichen Akzeptanzbeleg zurück, statt dem Kassenpersonal fälschlicherweise den FehlerALREADY_VOIDEDanzuzeigen.
Architektur der Einmal-Einlösung
Erster Scan: Atomare Einlösung (POST /api/v1/scans)
Wenn eine Kassenkraft einen aktiven Coupon beim Checkout scannt, sendet der Scanner das Barcode-Payload an POST /api/v1/scans, authentifiziert durch x-scanner-key:
HTTP-Anfrage
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-774109",
"scannerConfigurationId": "scfg_coupon_checkout",
"operatorId": "cashier_12",
"terminalId": "reg_berlin_01",
"validationData": {
"receiptNumber": "RCPT-2026-88412",
"basketTotal": 64.00
}
}
HTTP-Antwort (200 OK — Akzeptiert & Entwertet)
{
"decision": "SUCCESS",
"status": "ACCEPTED",
"reasonCode": "PASS_VOIDED_AFTER_SCAN",
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true },
{ "rule": "ExpirationRule", "passed": true },
{ "rule": "DefaultAcceptanceRule", "passed": true }
],
"passSnapshot": {
"id": "pass_cpn_774109",
"templateId": "tmpl_winter_promo_25",
"serialNumber": "PI-CPN-774109",
"externalId": "promo_order_774109",
"status": "VOIDED",
"expirationDate": "2026-12-31T23:59:59.000Z",
"attributes": {
"offerTitle": "25% Off Winter Collection",
"promoCode": "WINTER25"
}
},
"display": {
"title": "Coupon Redeemed",
"subtitle": "Apply 25% discount — Pass is now voided",
"color": "success"
}
}
Ablehnung doppelter Scans (ALREADY_VOIDED)
Versucht der Kunde denselben Pass an einer anderen Kasse erneut zu scannen — oder legt eine zweite Person einen weitergeleiteten Screenshot des Barcodes vor — erkennt PassStatusRule, dass der Pass bereits VOIDED ist, und bricht die Ausführung sofort ab:
{
"decision": "ALREADY_VOIDED",
"status": "REJECTED",
"reasonCode": "PASS_VOIDED_AFTER_SCAN",
"ruleTrace": [
{
"rule": "PassStatusRule",
"passed": false,
"reasonCode": "PASS_VOIDED_AFTER_SCAN"
}
],
"passSnapshot": {
"id": "pass_cpn_774109",
"templateId": "tmpl_winter_promo_25",
"serialNumber": "PI-CPN-774109",
"externalId": "promo_order_774109",
"status": "VOIDED"
},
"display": {
"title": "Already Redeemed",
"subtitle": "This voucher was already used and is void.",
"color": "error"
}
}
Stiller Wallet-Push & visuelle Ausgrauung
Unmittelbar nach dem Festschreiben des Statusübergangs auf VOIDED:
-
1
Apple Wallet (
.pkpass): Passinstance signiert ein aktualisiertes Pass-Paket mit"voided": trueinpass.jsonsowie dem Pass-Type-Zertifikat der Vorlage (bundleId= ApplepassTypeIdentifier) und versendet eine stille APNs-Push-Benachrichtigung. iOS entsättigt (graut aus) die Kartenoberfläche automatisch und macht den Barcode in Apple Wallet ungültig. -
2
Google Wallet: Passinstance ruft die Google Wallet REST API auf, um den
statedes Pass-Objekts aufCOMPLETED/EXPIREDzu setzen, entfernt die Karte aus aktiven Sperrbildschirm-Vorschlägen und blendet einen Hinweis über den eingelösten Status ein.
Administratoren und Backend-Worker können einzelne Coupons oder ganze Stapel auch außerhalb eines Scan-Ablaufs über POST /api/v1/passes/voiding/:id/void (request payload) oder POST /api/v1/passes/voiding/batch-void (request payload) mit einem typisierten VoidingReason manuell entwerten.
Einlösung am POS-Terminal im Einzelhandel (POST /v1/pos/redeem)
Integrierte Point-of-Sale-Systeme im Einzelhandel führen direkte Einmal-Gutschein-Einlösungen über POS Redemption API aus (POST /v1/pos/redeem und POST /v1/pos/scan — außerhalb des globalen Präfixes /api/v1):
Feld (request payload) | Typ | Beschreibung |
|---|---|---|
idempotencyKey | string (erforderlich, max. 255) | Eindeutiger Idempotenzschlüssel (empfohlen: tenantId:terminalId:clientTxRef). |
passRef | string (erforderlich, max. 500) | Gescannte Barcode-Zeichenfolge, Download-Token, serialNumber oder externalId / passPublicId. |
operation | PosOperation (erforderlich) | Passinstance database-Enum: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID oder CUSTOM. Verwenden Sie VOID oder DISCOUNT für Einmal-Coupons. |
terminalId | string (optionale UUID) | UUID des registrierten POS terminal (muss bei gebundenen Zugangsdaten übereinstimmen). |
externalTerminalRef | string (optional) | Externer Kassencode, sofern nicht die Passinstance-Terminal-UUID verwendet wird. |
amount / currency | number / string | Optionaler Rabatt- bzw. Transaktionsbetrag sowie ISO-4217-Währungscode (z. B. EUR). |
clientTxRef | string (optional) | POS-Beleg- oder Warenkorb-Transaktionsreferenz für den Buchhaltungsabgleich. |
metadata | object (optional) | Beliebiger Warenkorb-, Kassenpersonal- oder Filialkontext, gespeichert in PosTransaction. |
Nach dem erfolgreichen Commit von POST /v1/pos/redeem enthält die Antwort walletPropagation (PosWalletPropagationStatus: QUEUED oder SKIPPED), um die Weiterleitung per Push an Apple Wallet und Google Wallet zu bestätigen.
Bewährte Methoden für das Kampagnendesign finden Sie unter Coupons & Gutscheine sowie Scan-Modi & Validierungsregeln.
