Architektur für wiederkehrende Mitgliedschaften & Abonnements
Für Fitnessstudios, Coworking-Spaces, Verkehrsbetriebe, Abo-Boxen und Berufsverbände dienen digitale Wallet-Pässe als dynamische Mitgliedsausweise in Echtzeit. Anders als statische Karten kann ein Abo-Pass in Apple Wallet und Google Wallet sein Ablaufdatum, seinen Mitgliedschaftsstatus und die Barcode-Gültigkeit automatisch anpassen, sobald wiederkehrende Abrechnungszyklen erfolgreich verlängert werden, fehlschlagen oder gekündigt werden.
Passinstance synchronisiert Abonnement-Abrechnungsvereinbarungen (aus Stripe Billing, PayPal Subscriptions oder eigenen Abo-Backends) mithilfe automatisierter Webhook-Handler und stiller Push-Mitteilungen mit dem Pass-Lebenszyklus:
Zahlungsabonnements mit Pass-Datensätzen verknüpfen
Für eine nahtlose Synchronisierung des Abo-Lebenszyklus muss jeder Pass über das Feld externalId mit dem Abonnementdatensatz der Kundin bzw. des Kunden verknüpft werden:
-
1
Bei Abschluss des Abonnements: Wird ein initiales Abonnement in Stripe oder PayPal angelegt, erfasst Ihr Backend oder die Passinstance-Checkout-Integration die Abonnement-ID (z. B.
sub_1Q8xYz2e...) oder die Kunden-ID (z. B.cus_987654...). -
2
Bindung an
externalId: Passinstance speichert diese ID inPass.externalId. -
3
Initiales Ablaufdatum setzen: Das anfängliche
expirationDatedes Passes wird auf den Unix-Zeitstempel voncurrent_period_enddes Abrechnungsanbieters gesetzt.
Webhook-Lebenszyklusereignisse & automatisierte Aktionen
Passinstance verarbeitet eingehende Abrechnungs-Webhooks und löst die passenden Statusänderungen am Pass aus:
1. Abonnement verlängert (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)
Wenn eine monatliche oder jährliche Abo-Zahlung erfolgreich eingeht:
-
Aktion: Passinstance sucht den Pass anhand von
externalIdund verlängertpass.expirationDateauf das neue Ende des Abrechnungszeitraums. -
Feldaktualisierung: Jedes dynamische Feld, das
{validUntil}oder{membershipExpiry}anzeigt, wird auf das neue Datum aktualisiert. -
Push-Mitteilung: Apple Wallet erhält ein stilles APNs-Update; Google Wallet aktualisiert das Objekt per REST. Auf dem Sperrbildschirm kann optional ein dezenter Hinweis erscheinen (z. B. „Mitgliedschaft verlängert bis 31. März“).
2. Zahlung fehlgeschlagen / überfällig (invoice.payment_failed / INVOICE.PAYMENT_FAILED)
Schlägt eine wiederkehrende Abbuchung wegen einer abgelaufenen Kreditkarte oder mangelnder Deckung fehl:
-
Aktion: Der Pass bleibt während Ihrer konfigurierten Kulanzzeit aktiv (z. B. 7 Tage).
-
Feldaktualisierung: Ein Zusatz- oder Sekundärfeld wechselt von
"ACTIVE"auf"PAYMENT PAST DUE". -
Warnmeldung: Eine Push-Mitteilung wird an das Kundengerät gesendet: „Bitte aktualisieren Sie Ihre Zahlungsmethode, damit Ihre Mitgliedschaft aktiv bleibt.“
3. Abonnement gekündigt oder beendet (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)
Wenn eine Kundin oder ein Kunde das Abonnement kündigt:
-
Aktion: Am Ende des bezahlten Abrechnungszeitraums setzt Passinstance den Pass-Status auf
EXPIREDoder setztpass.voided = true. -
Visuelle Deaktivierung: Apple Wallet streicht den Check-in-Barcode durch und zeigt das Badge „Entwertet“ an. Google Wallet markiert die Karte als abgelaufen.
-
Scanner-Ablehnung: Die Zugangskontrolle an Drehkreuzen im Fitnessstudio oder am Empfang über den Passinstance Scanner zeigt sofort einen roten Bildschirm mit
EXPIREDoderVOIDED.
Schritt-für-Schritt-Einrichtung: Stripe Billing mit Passinstance verbinden
Schritt 1: Stripe in den Workspace-Einstellungen verbinden
-
1
Navigieren Sie im Passinstance-Dashboard zu Einstellungen -> Integrationen -> Zahlungen.
-
2
Verbinden Sie Ihr Stripe-Konto.
Schritt 2: Stripe-Webhook-Endpunkt registrieren
Fügen Sie in Ihrem Stripe Dashboard -> Developers -> Webhooks einen Endpunkt hinzu, der auf Passinstance zeigt:
https://api.passinstance.com/api/v1/webhooks/stripe-billing
Wählen Sie die folgenden Ereignisse aus:
-
invoice.payment_succeeded -
invoice.payment_failed -
customer.subscription.created -
customer.subscription.updated -
customer.subscription.deleted
Schritt 3: Ablaufregeln für Abo-Pässe konfigurieren
In den Einstellungen Ihrer Pass-Vorlage:
-
1
Öffnen Sie Funktionen -> Ablauf & Gültigkeit.
-
2
Wählen Sie Dynamischer Abonnement-Ablauf.
-
3
Legen Sie das Verhalten nach einer Kündigung fest: Pass ablaufen lassen (verbleibt im Wallet-Verlauf) oder Pass entwerten (streicht den Barcode sofort durch).
Abonnementstatus mit dem Passinstance Scanner prüfen
Wenn Mitarbeitende im Studio oder am Einlass den Pass eines Mitglieds mit der Passinstance Scanner App (Passinstance Scanner) scannen:
| Abonnementstatus | Scanner-Anzeige | Scanner-Antwort | Ergebnis |
|---|---|---|---|
| Aktiv & bezahlt | Grüner Bildschirm | VALID | Einlass gewährt. Zeigt Kundenname und aktive Mitgliedsstufe an. |
| Zahlung überfällig (Kulanzzeit) | Gelber Bildschirm | WARNING | Hinweis an das Personal: „Kulanzzeit aktiv. Mitglied bitten, Zahlungskarte zu aktualisieren.“ |
| Gekündigt / Abgelaufen | Roter Bildschirm | EXPIRED | Drehkreuz bleibt gesperrt. Anzeige: „Mitgliedschaft abgelaufen am [Datum]“. |
| Widerrufen / Entwertet | Roter Bildschirm | VOIDED | Check-in blockiert. Anzeige: „Karte wurde vom Aussteller entwertet“. |
Weiterführende Dokumentation
-
Pässe verkaufen — Einmalige kostenpflichtige Pass-Verkäufe über PassFlow.
-
Scan-Modi & Validierungsregeln — Scanner-Regeln und Einlasssteuerung konfigurieren.
-
Zahlungsmethoden — Workspace-Zahlungsmethoden verwalten.
-
Bestehende Pässe aktualisieren — Live-Push-Mechaniken für APNs und Google Wallet.
