Skip to content
Guida del Centro assistenza · Distribuzione pass
4 min di letturaVerificato 2026-11-16

Vendere abbonamenti

Vendi abbonamenti digitali ricorrenti, sincronizzando Stripe Billing o PayPal Subscriptions con le date di scadenza e i cambi di stato del pass.

In questa guida

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:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
SINCRONIZZAZIONE CICLO DI VITA ABBONAMENTI RICORRENTI
FASE 01 MOTORE DI FATTURAZIONE ABBONAMENTI CLIENTI
Stripe Billing | PayPal Subscriptions | Motore ricorrente custom
FASE 02 LISTENER WEBHOOK PASSINSTANCE (/webhooks/billing)
Associa l'ID abbonamento o l'e-mail cliente in ingresso a Pass.externalId
FASE 03 (Rinnovo riuscito) | (Pagamento fallito) | (Annullato)
1
ESTENDI SCADENZA
Aggiorna expirationDate a fine nuovo periodo
Push APNs silenziosa
Aggiornamento Google
2
AVVISO PERIODO DI TOLLERANZA
Aggiorna campo:
"Pagamento scaduto"
Avviso lockscreen
Grace allo scanner
3
SCADI O ANNULLA
Imposta EXPIRED o voided: true
Codice a barre barrato
Scanner rifiuta pass

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. 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. 2
    Associazione a externalId: Passinstance memorizza tale identificatore in Pass.externalId.
  3. 3
    Impostazione della scadenza iniziale: la expirationDate iniziale del pass viene impostata sul timestamp Unix di current_period_end restituito 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 externalId ed estende pass.expirationDate alla 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 EXPIRED oppure imposta pass.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 EXPIRED o VOIDED.

Configurazione passo dopo passo: collegare Stripe Billing a Passinstance

Passaggio 1: collega Stripe nelle impostazioni del workspace

  1. 1
    Vai su Impostazioni -> Integrazioni -> Pagamenti nella dashboard di Passinstance.
  2. 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:

TEXT
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. 1
    Apri Funzionalità -> Scadenza e validità.
  2. 2
    Seleziona Scadenza dinamica abbonamento.
  3. 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 abbonamentoSchermata ScannerRisposta ScannerRisultato
Attivo e pagatoSchermata verdeVALIDSocio ammesso. Mostra nome del cliente e livello attivo.
Pagamento scaduto (Periodo di tolleranza)Schermata ambraWARNINGStaff avvisato: "Periodo di tolleranza attivo. Invitare il socio ad aggiornare la carta."
Annullato / ScadutoSchermata rossaEXPIREDTornello bloccato. Mostra "Abbonamento scaduto il [Data]".
Revocato / AnnullatoSchermata rossaVOIDEDCheck-in bloccato. Mostra "La tessera è stata annullata dall'emittente".

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.