Architettura per abbonamenti e iscrizioni ricorrenti
Per palestre, spazi di coworking, reti di trasporto, servizi in abbonamento e associazioni professionali, i pass per wallet digitali fungono da credenziali di iscrizione dinamiche in tempo reale. A differenza delle tessere statiche, un pass in abbonamento su Apple Wallet e Google Wallet aggiorna automaticamente la propria data di scadenza, lo stato dell'abbonamento e la validità del codice a barre man mano che i cicli di fatturazione ricorrenti vanno a buon fine, falliscono o vengono annullati.
Passinstance sincronizza gli accordi di fatturazione ricorrente (da Stripe Billing, PayPal Subscriptions o backend di abbonamento personalizzati) con il ciclo di vita del pass mediante gestori webhook automatici e notifiche push silenziose:
Collegare gli abbonamenti di pagamento ai record dei pass
Per garantire una sincronizzazione fluida del ciclo di vita ricorrente, ciascun pass deve essere associato al record dell'abbonamento del cliente tramite il campo externalId:
-
1
Quando il cliente si abbona: alla creazione del primo abbonamento su Stripe o PayPal, il tuo backend o l'integrazione checkout di Passinstance acquisisce l'ID abbonamento (ad es.
sub_1Q8xYz2e...) o l'ID cliente (ad es.cus_987654...). -
2
Associazione a
externalId: Passinstance memorizza tale identificatore inPass.externalId. -
3
Impostazione della scadenza iniziale: la
expirationDateiniziale del pass viene impostata sul timestamp Unix dicurrent_period_endrestituito dal provider di fatturazione.
Eventi webhook del ciclo di vita e azioni automatiche
Passinstance rimane in ascolto sui webhook di fatturazione ricorrente e attiva i corrispondenti aggiornamenti di stato del pass:
1. Abbonamento rinnovato (invoice.payment_succeeded / BILLING.SUBSCRIPTION.RENEWED)
Quando un pagamento mensile o annuale va a buon fine:
-
Azione: Passinstance individua il pass corrispondente a
externalIded estendepass.expirationDatealla data di fine del nuovo ciclo di fatturazione. -
Aggiornamento campi: qualsiasi campo dinamico che mostra
{validUntil}o{membershipExpiry}si aggiorna alla nuova data. -
Notifica push: Apple Wallet riceve un aggiornamento APNs silenzioso; Google Wallet aggiorna l'oggetto tramite REST. La schermata di blocco può visualizzare un discreto banner di aggiornamento (ad es. "Abbonamento rinnovato fino al 31 marzo").
2. Pagamento fallito / scaduto (invoice.payment_failed / INVOICE.PAYMENT_FAILED)
Se un addebito ricorrente fallisce per carta di credito scaduta o fondi insufficienti:
-
Azione: il pass rimane attivo durante il periodo di tolleranza configurato (ad es. 7 giorni).
-
Aggiornamento campi: un campo ausiliario o secondario passa da
"ACTIVE"a"PAYMENT PAST DUE". -
Notifica di avviso: viene inviata una notifica push al dispositivo del cliente: "Aggiorna il tuo metodo di pagamento per mantenere attivo l'abbonamento."
3. Abbonamento annullato o terminato (customer.subscription.deleted / BILLING.SUBSCRIPTION.CANCELLED)
Quando un cliente disdice il proprio abbonamento:
-
Azione: al termine del periodo già pagato, Passinstance aggiorna lo stato del pass a
EXPIREDoppure impostapass.voided = true. -
Disattivazione visiva: Apple Wallet barra il codice a barre di check-in e mostra il badge "Pass annullato". Google Wallet contrassegna la tessera come scaduta.
-
Rifiuto allo scanner: la validazione fisica ai tornelli della palestra o alla reception con Passinstance Scanner mostra immediatamente una schermata rossa con
EXPIREDoVOIDED.
Configurazione passo dopo passo: collegare Stripe Billing a Passinstance
Passaggio 1: collega Stripe nelle impostazioni del workspace
-
1
Vai su Impostazioni -> Integrazioni -> Pagamenti nella dashboard di Passinstance.
-
2
Collega il tuo account Stripe.
Passaggio 2: registra l'endpoint webhook su Stripe
Nella Stripe Dashboard -> Developers -> Webhooks, aggiungi un endpoint che punti a Passinstance:
https://api.passinstance.com/api/v1/webhooks/stripe-billing
Seleziona i seguenti eventi:
-
invoice.payment_succeeded -
invoice.payment_failed -
customer.subscription.created -
customer.subscription.updated -
customer.subscription.deleted
Passaggio 3: configura le regole di scadenza del pass in abbonamento
Nelle impostazioni del modello del pass:
-
1
Apri Funzionalità -> Scadenza e validità.
-
2
Seleziona Scadenza dinamica abbonamento.
-
3
Scegli il comportamento dopo la disdetta: Fai scadere il pass (resta nello storico del wallet) oppure Annulla il pass (barra immediatamente il codice a barre).
Gestione dello stato abbonamento con Passinstance Scanner
Quando lo staff della palestra o gli addetti all'accoglienza scansionano il pass di un socio con l'app Passinstance Scanner (Passinstance Scanner):
| Stato abbonamento | Schermata Scanner | Risposta Scanner | Risultato |
|---|---|---|---|
| Attivo e pagato | Schermata verde | VALID | Socio ammesso. Mostra nome del cliente e livello attivo. |
| Pagamento scaduto (Periodo di tolleranza) | Schermata ambra | WARNING | Staff avvisato: "Periodo di tolleranza attivo. Invitare il socio ad aggiornare la carta." |
| Annullato / Scaduto | Schermata rossa | EXPIRED | Tornello bloccato. Mostra "Abbonamento scaduto il [Data]". |
| Revocato / Annullato | Schermata rossa | VOIDED | Check-in bloccato. Mostra "La tessera è stata annullata dall'emittente". |
Documentazione correlata
-
Vendere pass — Vendite una tantum di pass a pagamento tramite PassFlow.
-
Modalità di scansione e regole di validazione — Configurazione delle regole scanner e dell'accesso ai tornelli.
-
Metodi di pagamento — Gestione dei metodi di pagamento del workspace.
-
Aggiornare pass esistenti — Meccaniche di aggiornamento push live per APNs e Google Wallet.
