Architectuur voor terugkerende lidmaatschappen & abonnementen
Voor sportscholen, coworkingruimtes, vervoersnetwerken, abonnementsboxen en beroepsverenigingen fungeren digitale wallet-passen als dynamische, realtime lidmaatschapsbewijzen. In tegenstelling tot statische kaarten kan een abonnementspas in Apple Wallet en Google Wallet automatisch zijn vervaldatum, lidmaatschapsstatus en barcodegeldigheid bijwerken zodra terugkerende factuurcycli slagen, mislukken of worden opgezegd.
Passinstance synchroniseert lopende facturatieovereenkomsten (vanuit Stripe Billing, PayPal Subscriptions of eigen abonnementssystemen) met de paslevenscyclus via geautomatiseerde webhookhandlers en stille pushmeldingen:
Betaalabonnementen koppelen aan pasrecords
Voor een vlekkeloze synchronisatie van de terugkerende levenscyclus moet elke pas via het veld externalId worden gekoppeld aan het abonnementsrecord van de klant:
-
1
Wanneer een klant een abonnement afsluit: Zodra het eerste abonnement wordt aangemaakt in Stripe of PayPal, legt uw backend of de checkout-integratie van Passinstance de abonnements-ID (bijv.
sub_1Q8xYz2e...) of klant-ID (bijv.cus_987654...) vast. -
2
Koppelen aan
externalId: Passinstance slaat deze ID op inPass.externalId. -
3
Initiële vervaldatum instellen: De initiële
expirationDatevan de pas wordt ingesteld op het Unix-tijdstempel vancurrent_period_endvanuit de facturatieprovider.
Levenscyclusgebeurtenissen via webhooks & geautomatiseerde acties
Passinstance luistert naar webhooks van terugkerende betalingen en voert automatisch bijbehorende statusupdates op de pas uit:
1. Abonnement verlengd (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)
Wanneer een maandelijkse of jaarlijkse abonnementsbetaling slaagt:
-
Actie: Passinstance zoekt de pas op basis van
externalIden verlengtpass.expirationDatetot de einddatum van de nieuwe factuurcyclus. -
Veldupdate: Elk dynamisch veld dat
{validUntil}of{membershipExpiry}toont, wordt automatisch bijgewerkt naar de nieuwe datum. -
Pushmelding: Apple Wallet ontvangt een stille APNs-update; Google Wallet werkt het object bij via REST. Op het toegangsscherm kan een subtiele updatemelding verschijnen (bijv. "Lidmaatschap verlengd tot en met 31 maart").
2. Betaling mislukt / achterstallig (invoice.payment_failed / INVOICE.PAYMENT_FAILED)
Wanneer een periodieke afschrijving mislukt door een verlopen creditcard of onvoldoende saldo:
-
Actie: De pas blijft actief gedurende uw ingestelde respijtperiode (bijv. 7 dagen).
-
Veldupdate: Een hulpveld of secundair veld verandert van
"ACTIVE"naar"PAYMENT PAST DUE". -
Waarschuwingsmelding: De klant ontvangt een pushmelding op zijn toestel: "Werk uw betaalmethode bij om uw lidmaatschap actief te houden."
3. Abonnement opgezegd of beëindigd (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)
Wanneer een klant zijn abonnement beëindigt:
-
Actie: Na afloop van de betaalde factuurperiode werkt Passinstance de passtatus bij naar
EXPIREDof zetpass.voided = true. -
Visuele deactivering: Apple Wallet streept de incheckbarcode door en toont de badge "Pas ongeldig". Google Wallet markeert de kaart als verlopen.
-
Weigering door scanner: Fysieke toegangscontrole bij tourniquets van sportscholen of balies via de Passinstance Scanner toont direct een rood scherm met
EXPIREDofVOIDED.
Stapsgewijze configuratie: Stripe Billing koppelen aan Passinstance
Stap 1: Koppel Stripe in de werkruimte-instellingen
-
1
Ga in het Passinstance-dashboard naar Instellingen -> Integraties -> Betalingen.
-
2
Koppel uw Stripe-account.
Stap 2: Registreer het Stripe webhook-endpoint
Voeg in uw Stripe Dashboard -> Developers -> Webhooks een endpoint toe dat verwijst naar Passinstance:
https://api.passinstance.com/api/v1/webhooks/stripe-billing
Selecteer de volgende gebeurtenissen:
-
invoice.payment_succeeded -
invoice.payment_failed -
customer.subscription.created -
customer.subscription.updated -
customer.subscription.deleted
Stap 3: Configureer vervalregels voor abonnementspassen
In de instellingen van uw passjabloon:
-
1
Open Functionaliteiten -> Vervaldatum & geldigheid.
-
2
Selecteer Dynamische abonnementsvervaldatum.
-
3
Kies het gedrag na opzegging: Pas laten verlopen (blijft zichtbaar in de wallet-geschiedenis) of Pas ongeldig verklaren (streept de barcode onmiddellijk door).
Abonnementsstatus beheren met de Passinstance Scanner
Wanneer medewerkers van een sportschool of locatie een ledenpas scannen met de Passinstance Scanner App (Passinstance Scanner):
| Abonnementsstatus | Scannerscherm | Scannerrespons | Resultaat |
|---|---|---|---|
| Actief & betaald | Groen scherm | VALID | Lid krijgt toegang. Toont klantnaam en actief niveau. |
| Betaling achterstallig (respijtperiode) | Oranje scherm | WARNING | Medewerker gewaarschuwd: "Respijtperiode actief. Vraag het lid om de betaalkaart bij te werken." |
| Opgezegd / verlopen | Rood scherm | EXPIRED | Tourniquet blijft vergrendeld. Toont "Lidmaatschap verlopen op [Datum]". |
| Ingetrokken / ongeldig | Rood scherm | VOIDED | Inchecken geblokkeerd. Toont "Kaart is ongeldig verklaard door uitgever". |
Gerelateerde documentatie
-
Passen verkopen — Eenmalige betaalde pasverkoop via PassFlow.
-
Scanmodi & validatieregels — Scannerregels en toegangscontrole configureren.
-
Betaalmethoden — Betaalmethoden van de werkruimte beheren.
-
Bestaande passen bijwerken — Live pushmechanismen voor APNs en Google Wallet.
