Architecture des adhésions récurrentes & abonnements
Pour les salles de sport, espaces de coworking, réseaux de transport, box par abonnement et associations professionnelles, les passes de portefeuille numérique servent de cartes de membre dynamiques en temps réel. Contrairement aux cartes statiques, un passe d'abonnement dans Apple Wallet et Google Wallet met à jour automatiquement sa date d'expiration, son statut d'adhésion et la validité de son code-barres au fil des cycles de facturation réussis, échoués ou résiliés.
Passinstance synchronise les contrats de facturation récurrente (issus de Stripe Billing, PayPal Subscriptions ou de moteurs d'abonnement personnalisés) avec le cycle de vie du passe grâce à des gestionnaires de webhooks automatisés et des notifications push silencieuses :
Lier les abonnements de paiement aux fiches de passes
Pour garantir une synchronisation fluide du cycle de vie récurrent, chaque passe doit être relié à l'abonnement du client à l'aide du champ externalId :
-
1
Lors de la souscription du client : lorsqu'un abonnement initial est créé dans Stripe ou PayPal, votre backend ou l'intégration de paiement Passinstance capture l'identifiant d'abonnement (par ex.
sub_1Q8xYz2e...) ou l'identifiant client (par ex.cus_987654...). -
2
Association à
externalId: Passinstance enregistre cet identifiant dansPass.externalId. -
3
Définition de l'expiration initiale : la valeur initiale
expirationDatedu passe est calée sur l'horodatage Unixcurrent_period_endfourni par le prestataire de facturation.
Événements webhook du cycle de vie & actions automatisées
Passinstance écoute les webhooks de facturation récurrente et déclenche les mises à jour d'état correspondantes sur le passe :
1. Abonnement renouvelé (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)
Lorsqu'une échéance mensuelle ou annuelle est réglée avec succès :
-
Action : Passinstance retrouve le passe correspondant à
externalIdet prolongepass.expirationDatejusqu'à la fin du nouveau cycle de facturation. -
Mise à jour des champs : tout champ dynamique affichant
{validUntil}ou{membershipExpiry}est actualisé avec la nouvelle date. -
Notification push : Apple Wallet reçoit une mise à jour APNs silencieuse ; Google Wallet met à jour l'objet via REST. L'écran verrouillé peut afficher un discret bandeau d'information (par ex. « Adhésion renouvelée jusqu'au 31 mars »).
2. Paiement échoué / en retard (invoice.payment_failed / INVOICE.PAYMENT_FAILED)
Si un prélèvement récurrent échoue en raison d'une carte expirée ou d'un solde insuffisant :
-
Action : le passe reste actif pendant la période de grâce configurée (par ex. 7 jours).
-
Mise à jour des champs : un champ auxiliaire ou secondaire passe de
"ACTIVE"à"PAYMENT PAST DUE". -
Notification d'alerte : une notification push est envoyée sur l'appareil du client : « Veuillez mettre à jour votre moyen de paiement pour maintenir votre adhésion active. »
3. Abonnement annulé ou résilié (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)
Lorsqu'un client met fin à son abonnement :
-
Action : à l'issue de la période déjà payée, Passinstance fait passer le statut du passe à
EXPIREDou définitpass.voided = true. -
Désactivation visuelle : Apple Wallet barre le code-barres de contrôle d'accès et affiche un badge « Passe invalidé ». Google Wallet marque la carte comme expirée.
-
Rejet au scanner : la validation physique aux portiques d'une salle de sport ou à l'accueil via Passinstance Scanner affiche immédiatement un écran rouge avec le statut
EXPIREDouVOIDED.
Configuration étape par étape : connecter Stripe Billing à Passinstance
Étape 1 : connecter Stripe dans les paramètres de l'espace de travail
-
1
Accédez à Paramètres -> Intégrations -> Paiements dans le tableau de bord Passinstance.
-
2
Connectez votre compte Stripe.
Étape 2 : enregistrer l'endpoint webhook Stripe
Dans votre Tableau de bord Stripe -> Développeurs -> Webhooks, ajoutez un endpoint pointant vers Passinstance :
https://api.passinstance.com/api/v1/webhooks/stripe-billing
Sélectionnez les événements suivants :
-
invoice.payment_succeeded -
invoice.payment_failed -
customer.subscription.created -
customer.subscription.updated -
customer.subscription.deleted
Étape 3 : configurer les règles d'expiration du passe d'abonnement
Dans les paramètres de votre modèle de passe :
-
1
Ouvrez Fonctionnalités -> Expiration & validité.
-
2
Sélectionnez Expiration dynamique d'abonnement (Dynamic Subscription Expiration).
-
3
Choisissez le comportement après résiliation : Expirer le passe (reste dans l'historique du portefeuille) ou Invalider le passe (barre immédiatement le code-barres).
Gérer le statut d'abonnement avec Passinstance Scanner
Lorsque le personnel d'accueil ou d'un club scanne le passe d'un membre à l'aide de l'application Passinstance Scanner (Passinstance Scanner) :
| État de l'abonnement | Écran du scanner | Réponse du scanner | Résultat |
|---|---|---|---|
| Actif & payé | Écran vert | VALID | Accès autorisé. Affiche le nom du membre et son palier actif. |
| Paiement en retard (période de grâce) | Écran ambre | WARNING | Personnel alerté : « Période de grâce active. Invitez le membre à mettre à jour sa carte. » |
| Résilié / Expiré | Écran rouge | EXPIRED | Le portique reste verrouillé. Affiche « Adhésion expirée le [Date] ». |
| Révoqué / Invalidé | Écran rouge | VOIDED | Contrôle bloqué. Affiche « La carte a été invalidée par l'émetteur ». |
Documentation connexe
-
Vendre des passes — Ventes ponctuelles de passes payants via PassFlow.
-
Modes de scan & règles de validation — Configurer les règles de scan et le contrôle d'accès aux portiques.
-
Moyens de paiement — Gérer les moyens de paiement de l'espace de travail.
-
Mettre à jour des passes existants — Mécaniques de mises à jour push en direct APNs et Google Wallet.
