Skip to content
Hilfecenter-Anleitung · Einlösung & Transaktionen
3 Min. LesezeitGeprüft 2026-11-16

Coupon- & Gutscheineinlösung

Verarbeiten Sie Einmal-Gutscheine am Point of Sale, entwerten Sie verbrauchte Pässe automatisch und verhindern Sie Doppelscans.

In dieser Anleitung

Ü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 bei POST /api/v1/scans bzw. idempotencyKey in request payload bei POST /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 Fehler ALREADY_VOIDED anzuzeigen.

Architektur der Einmal-Einlösung

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
ATOMARE COUPON-EINLÖSUNG & WALLET-AUSGRAUUNG
BETEILIGTE SYSTEMKOMPONENTEN
P1 Kundengerät
P2 Scanner / POS-Terminal
P3 Passinstance API
SCHRITT 1 ANFRAGE / AKTION Coupon-Barcode vorzeigen
›
(PI-CPN-774109)
SCHRITT 2 ANFRAGE / AKTION POST/api/v1/scans
›
Header: x-scanner-key
›
Mode: VOIDED_AFTER_SCAN
SCHRITT 3 ANFRAGE / AKTION PassStatusRule (ACTIVE)
SCHRITT 4 ANFRAGE / AKTION ExpirationRule (< validUntil)
SCHRITT 5 ANFRAGE / AKTION Atomare DB-Transaktion:
›
statusVOIDED
›
oidedAtnow()
SCHRITT 6 ANTWORT 200 OK
SCHRITT 7 ANFRAGE / AKTION APNs / Google Push senden
SCHRITT 8 ANTWORT Wallet-Karte ausgegraut
›
(Apple voided: true .pkpass)
SCHRITT 9 ANFRAGE / AKTION Replay / Screenshot-Scan
SCHRITT 10 ANFRAGE / AKTION POST/api/v1/scans
SCHRITT 11 ANTWORT 200 OK
›
decision: "ALREADY_VOIDED"
›
reasonCode: "PASS_VOIDED_AFTER_SCAN"

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

POST /api/v1/scans
Headers
x-scanner-key sk_live_pos_register_01
x-idempotency-key pos-tx-20261116-99481
Content-Type application/json
JSON
{
  "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)

JSON
{
  "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:

JSON
{
  "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. 1
    Apple Wallet (.pkpass): Passinstance signiert ein aktualisiertes Pass-Paket mit "voided": true in pass.json sowie dem Pass-Type-Zertifikat der Vorlage (bundleId = Apple passTypeIdentifier) 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. 2
    Google Wallet: Passinstance ruft die Google Wallet REST API auf, um den state des Pass-Objekts auf COMPLETED / EXPIRED zu 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)TypBeschreibung
idempotencyKeystring (erforderlich, max. 255)Eindeutiger Idempotenzschlüssel (empfohlen: tenantId:terminalId:clientTxRef).
passRefstring (erforderlich, max. 500)Gescannte Barcode-Zeichenfolge, Download-Token, serialNumber oder externalId / passPublicId.
operationPosOperation (erforderlich)Passinstance database-Enum: DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID oder CUSTOM. Verwenden Sie VOID oder DISCOUNT für Einmal-Coupons.
terminalIdstring (optionale UUID)UUID des registrierten POS terminal (muss bei gebundenen Zugangsdaten übereinstimmen).
externalTerminalRefstring (optional)Externer Kassencode, sofern nicht die Passinstance-Terminal-UUID verwendet wird.
amount / currencynumber / stringOptionaler Rabatt- bzw. Transaktionsbetrag sowie ISO-4217-Währungscode (z. B. EUR).
clientTxRefstring (optional)POS-Beleg- oder Warenkorb-Transaktionsreferenz für den Buchhaltungsabgleich.
metadataobject (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.

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.