Skip to content
Hilfecenter-Anleitung · Pass-VerwaltungOnboarding-Phase 4
5 Min. LesezeitGeprüft 2026-11-16

Pass-Lebenszyklus & Status

Verstehen Sie die Zustände Erstellt, Nicht installiert, Installiert, Abgelaufen und Storniert sowie deren Auswirkung auf Abrechnung und Scans.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Live-Popover zum Wallet-Registrierungsstatus (Zoom)

Klicken Sie in einer Pass-Zeile auf das Apple Wallet- oder Google Wallet-Symbol, um aktive Registrierungen, Entfernungen und Zeitstempel zu prüfen.

Überblick

Passinstance steuert jeden ausgegebenen Pass über drei orthogonale Zustandsautomaten direkt auf dem Pass-Modell:

  1. 1
    pass status (11 Werte): Fachlicher Gültigkeitsstatus, der bestimmt, ob ein Pass installiert, gescannt oder eingelöst werden kann.
  2. 2
    PassLifecycleStatus (5 Phasen): Administrative Aufbewahrungs- und Widerrufsabfolge von ACTIVE bis DELETED.
  3. 3
    WalletPropagationStatus (5 Phasen): Asynchroner Cloud-Synchronisierungsstatus für die Zustellung von APNs- und Google-Wallet-Pushs.

Systemarchitektur: Pass-Lebenszyklus & Wallet-Propagation

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
PASS-LEBENSZYKLUS & WALLET-PROPAGATION
STUFE 01
1
FACHLICHER STATUS (pass status) [DRAFT] / [AWAITING_OPT_IN] / [PENDING_ACTIVATION]
[GENERATING][ACTIVE] <[INACTIVE] / [SUSPENDED] [REDEEMED] [EXPIRED] [CANCELLED] / [VOIDED]
STUFE 02
2
LEBENSZYKLUS-ABFOLGE (PassLifecycleStatus) [ACTIVE][VOIDING][VOIDED][DELETING][DELETED]
STUFE 03
3
CLOUD-SYNC-PIPELINE (WalletPropagationStatus) [NONE][PENDING][QUEUED][SUCCEEDED] (oder [FAILED] + Retry)

1. Alle 11 fachlichen pass status-Zustände

pass status-WertErgebnis der Scanner-PrüfungVisuelle Darstellung & Verhalten im Wallet
DRAFTAbgelehnt (INVALID)Pass-Datensatz existiert vor Signierung in der DB; Download-Link ist noch nicht aktiv.
AWAITING_OPT_INAbgelehnt (PENDING)Über PassFlow oder Kampagne erstellt; wartet auf E-Mail-/SMS-OTP oder DSGVO-Einwilligung.
PENDING_ACTIVATIONAbgelehnt (PENDING)Ausgegebener Pass wartet auf externe Zahlungsbestätigung oder POS-Aktivierungsscan.
GENERATINGAbgelehnt (PENDING)Kryptografisches .pkpass-Paket oder Google-Wallet-Objekt wird gerade durch einen Worker kompiliert.
ACTIVEAkzeptiert (SUCCESS)Gültiger Live-Pass, berechtigt für Scans, Punktegutschriften, NFC-Tap und Push-Mitteilungen.
INACTIVEAbgelehnt (INVALID)Vorübergehend durch Administration deaktiviert (POST /api/v1/batch-pass-operations/deactivate).
SUSPENDEDAbgelehnt (INVALID)Eingefroren wegen Betrugsverdacht, Zahlungsrückstand oder Sicherheitssperre; wieder auf ACTIVE rücksetzbar.
REDEEMEDAbgelehnt (ALREADY_USED)Einmal-Coupon oder Event-Ticket wurde gescannt und verbraucht (VOIDED_AFTER_SCAN scan mode).
EXPIREDAbgelehnt (EXPIRED)Aktueller Zeitstempel liegt hinter Pass.expirationDate; Barcode wird auf dem Kundengerät ausgegraut.
CANCELLEDAbgelehnt (ALREADY_VOIDED)Anmeldung oder Bestellung wurde vor Einlösung storniert (z. B. erstattetes Ticket).
VOIDEDAbgelehnt (ALREADY_VOIDED)Dauerhaft über Pass Voiding API entwertet; setzt "voided": true in Apple pass.json und STATE_EXPIRED/INACTIVE in Google Wallet.

2. Die 5 PassLifecycleStatus-Phasen

Die Spalte lifecycleStatus koordiniert sichere mehrstufige Sperrungen und Datenbankbereinigungen, ohne verwaiste Wallet-Objekte auf Endgeräten zu hinterlassen:

PhaseBeschreibung
ACTIVENormaler Betriebszustand über aktive, inaktive oder abgelaufene Pässe hinweg.
VOIDINGÜbergangssperre bei Eingang einer Entwertungsanfrage; reiht priorisierte Entwertungs-Pushs an Apple und Google Wallet ein.
VOIDEDAbschließender Widerruf abgeschlossen; Zeitstempel voidedAt und voidReason werden dauerhaft am Pass-Datensatz vermerkt.
DELETINGÜbergangssperre bei Anforderung dauerhafter Löschung; widerruft Download-Tokens und trennt Speicher-Assets.
DELETEDSoft-Delete-Markierung oder abgeschlossene Löschung vor der DSGVO-Bereinigung.

3. walletVoidStatus (WalletPropagationStatus), Löschmodi & Artefakte

Passinstance verfolgt asynchrone Cloud-Push-Auslieferung, Löschsemantik und Wallet-Artefakt-Kompilierung über eigene Passinstance database-Spalten und Enums auf Pass:

walletVoidStatus (WalletPropagationStatus)

Sobald ein Entwertungs- oder Statuswechsel an Apple APNs oder Google Wallet gesendet wird, dokumentiert Pass.walletVoidStatus den Auslieferungsfortschritt:

Phase (WalletPropagationStatus)Beschreibung
NONEPass wurde neu erstellt oder es steht kein Entwertungs-/Ausbreitungsvorgang in der Queue.
PENDINGEine Feldänderung oder ein Lebenszyklusübergang wurde in database festgeschrieben und wartet auf die Übergabe an den Dispatcher.
QUEUEDEin background job queue-Wallet-Sync-Job ist aktiv eingereiht, um den APNs-HTTP/2-Push bzw. die Google-Wallet-PATCH-Anfrage auszuführen.
SUCCEEDEDAlle registrierten Geräte bzw. Cloud-Objekte haben das Update bestätigt (bei Apple Wallet hat das Gerät das aktuelle .pkpass-Paket über GET /v1/passes/... abgerufen).
FAILEDDie Zustellung stieß auf einen Upstream-Fehler (z. B. abgemeldetes APNs-Token oder Google-API-Kontingentfehler); für erneute Versuche berechtigt.

PassDeletionMode & ArtifactStatus

  • PassDeletionMode (SOFT | HARD): DELETE /api/v1/passes/:id führt ein SOFT-Delete aus (setzt archivedAt, gibt die Mandanten-Eindeutigkeit (customerId, externalId) für Neuausgaben frei und bewahrt Audit-Logs), während DELETE /api/v1/passes/:id/hard eine endgültige HARD-Löschung durchführt.
  • ArtifactStatus (appleArtifactStatus, googleArtifactStatus): NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATED zeigt an, ob das kryptografische Paket bzw. Cloud-Objekt je Plattform kompiliert und aktuell ist.

Wichtige Invariante für Abrechnung & Wallet-Lebenszyklus

Wichtig: Das Entwerten oder Ablaufenlassen eines Passes weist künftige Scanner-Prüfungen ab und kennzeichnet die Karte im Wallet des Nutzers visuell als ungültig/ausgegraut — Apple iOS und Google Android erlauben es Drittanbieter-Servern jedoch nicht, einen Pass ohne Zutun der Nutzerin oder des Nutzers zwangsweise vom Gerät zu löschen. In Apple Wallet unterdrücken entwertete Pässe Sperrbildschirm-Meldungen, sofern auf der Vorlage nicht updateVoidedExpiredPasses: true aktiviert ist. Ein installierter Pass zählt weiterhin als aktive Geräteregistrierung, bis die Kundin oder der Kunde ihn aus dem Wallet entfernt oder die Gerätederegistrierung abgeschlossen ist.

API für Deaktivierung & Entwertung (Passes API / Pass Voiding API)

Passinstance stellt sowohl eine umkehrbare Deaktivierung (POST /api/v1/passes/:id/deactivate) als auch formelle Entwertungs-Endpunkte unter /api/v1/passes/voiding bereit (akzeptiert VoidingReason: EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER):

EndpunktGeltungsbereichBeschreibung
POST /api/v1/passes/:id/deactivateEinzelner PassSetzt den Pass-Status vorübergehend von ACTIVE auf INACTIVE.
POST /api/v1/passes/voiding/:id/voidEinzelner PassEntwertet (voided: true) oder reaktiviert (voided: false) einen einzelnen Pass (204 No Content).
POST /api/v1/passes/voiding/batch-voidArray von PässenEntwertet oder reaktiviert mehrere passIds in einer Anfrage (request payload).
POST /api/v1/passes/voiding/template-voidGesamte VorlageEntwertet massenhaft alle aktiven Pässe unter einer templateId (request payload).
GET /api/v1/passes/voiding/:id/voiding-historyAudit-ProtokollGibt chronologische Entwertungs- und Reaktivierungsereignisse für den Pass zurück.

Beispiel: Einzelnen Pass entwerten (request payload)

POST /api/v1/passes/voiding/pass_01j8k9m2n3p4q5r6/void Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Order refunded via Shopify webhook #SH-99412",
    "sendPushNotification": true,
    "pushNotificationMessage": "This pass has been voided following your order refund.",
    "updateGoogleWallet": true
  }
}

HTTP-Status: Gibt bei Erfolg 204 No Content zurück, setzt umgehend status = "VOIDED" und lifecycleStatus = "VOIDED" und aktualisiert walletVoidStatus (WalletPropagationStatus: NONE -> PENDING -> QUEUED -> SUCCEEDED) während die Hintergrund-Pushs laufen.

Beispiel: Mehrere Pässe im Batch entwerten (request payload)

POST /api/v1/passes/voiding/batch-void Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "passIds": [
    "pass_01j8k9m2n3p4q5r6",
    "pass_01j8k9m2n3p4q5r7"
  ],
  "voided": true,
  "options": {
    "reason": "EXPIRED",
    "customReason": "Expired seasonal VIP cohort",
    "sendPushNotification": true
  }
}

Beispiel: Alle Pässe einer Vorlage entwerten (request payload)

POST /api/v1/passes/voiding/template-void Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Summer 2026 promotional campaign concluded",
    "sendPushNotification": true
  }
}

Lesen Sie Massenaktionen für Array-basierte Aktivierungs-, Deaktivierungs- und Löschabläufe oder Aktive Pässe & Nutzungslimits für Regeln zur Kapazitätsbemessung.

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.