Come aggiungere abbonamenti con Stripe: piani, prove gratuite, webhook e pagamenti falliti
Per aggiungere abbonamenti con Stripe, crea un prodotto con un prezzo ricorrente nella Dashboard di Stripe, invia i clienti a Stripe Checkout in modalità abbonamento dal tuo server, e lascia che un webhook comunichi alla tua app quando ogni pagamento riesce, fallisce, cambia o termina. Memorizza lo stato dell'abbonamento associato all'utente e concedi l'accesso in base a quello, non in base alla pagina di successo. Aggiungi un pulsante Gestisci fatturazione che apre il portale clienti ospitato da Stripe, così le persone possono cambiare carta, cambiare piano e cancellarsi senza che tu debba costruire quelle schermate.
Questa guida si basa su come aggiungere pagamenti alla tua app, che copre Checkout una tantum, la modalità di test e la messa in produzione. Qui ci concentriamo su ciò che è diverso nella fatturazione ricorrente. I dettagli su Stripe provengono dalla documentazione di Stripe aggiornata a settembre 2026.
Perché gli abbonamenti sono più difficili dei pagamenti una tantum
Un pagamento una tantum avviene mentre il cliente è nella tua app. Un abbonamento continua ad avvenire dopo che il cliente se n'è andato: rinnovi ogni mese, carte che scadono, upgrade a metà ciclo, cancellazioni che hanno effetto alla fine del periodo. La tua app ne viene a sapere solo tramite i webhook. La maggior parte dei bug sugli abbonamenti nasce dal considerare il primo pagamento come l'intera storia.
Le tue opzioni
| Approccio | Cosa costruisci | Ideale per |
|---|---|---|
| Payment Link con un prezzo ricorrente | Nient'altro che un link | Testare la domanda; gestire l'accesso a mano |
| Checkout (modalità abbonamento) + portale clienti | Una route del server, un webhook, un pulsante di fatturazione | La maggior parte delle app SaaS e degli abbonamenti |
| API degli abbonamenti con un tuo modulo di pagamento | Molto di più: interfaccia di pagamento, autenticazione, nuovi tentativi | App con flussi di fatturazione insoliti |
| Fornitore merchant of record | Simile a Checkout | Venditori che vogliono che il fornitore gestisca l'imposta sulle vendite |
Per la maggior parte delle app, Checkout più il portale è il compromesso giusto. Confronta i fornitori in Stripe vs Paddle vs Lemon Squeezy se la gestione fiscale ti preoccupa.
Pianifica prima i prezzi in Stripe
In Stripe, un prodotto è ciò che vendi ("piano Pro") e un prezzo è come lo addebiti ("20 $ al mese", "200 $ all'anno"). Un prodotto può avere più prezzi. Decidi:
- Quali livelli offri e cosa sblocca ciascuno nella tua app
- Mensile, annuale, o entrambi
- Se offri una prova gratuita, e se richiede subito una carta
Crea prodotti e prezzi in modalità di test e conserva i loro ID prezzo; la tua app li richiama. Se non hai ancora definito i prezzi, leggi come definire il prezzo di un prodotto SaaS e freemium vs prova gratuita.
Il ciclo di vita dell'abbonamento che devi gestire
La panoramica degli abbonamenti di Stripe elenca gli stati che un abbonamento può avere. Quelli che contano di più per l'accesso:
| Stato | Cosa significa | Concedi l'accesso? |
|---|---|---|
trialing | In periodo di prova | Sì |
active | In regola | Sì |
incomplete | Primo pagamento non ancora completato; Stripe dà al cliente 23 ore | No |
incomplete_expired | Il primo pagamento non è mai andato a buon fine | No |
past_due | L'ultimo pagamento è fallito o non è stato tentato; possono seguire nuovi tentativi | A tua scelta; molte app concedono un breve periodo di tolleranza |
unpaid | I tentativi sono finiti, le fatture restano aperte, nessun altro tentativo | No, la documentazione di Stripe dice di revocare l'accesso |
canceled | Terminato; non può essere riavviato | No |
paused | Una prova è terminata senza un metodo di pagamento ed è stata impostata in pausa | No |
Memorizza lo stato nel record del tuo utente o account e basa l'accesso su di esso. Aggiornalo ogni volta che arriva un webhook pertinente.
Gli eventi webhook da gestire
| Evento | Cosa fa la tua app |
|---|---|
checkout.session.completed | Collega i nuovi ID cliente e abbonamento Stripe al tuo utente |
invoice.paid | Segna l'abbonamento come attivo e registra la nuova fine del periodo |
invoice.payment_failed | Avvisa l'utente che la carta è stata rifiutata e lo collega al portale |
invoice.payment_action_required | Chiede all'utente di completare l'autenticazione della carta |
customer.subscription.updated | Aggiorna piano, stato ed eventuali cancellazioni programmate |
customer.subscription.deleted | Rimuove l'accesso a pagamento |
customer.subscription.trial_will_end | Ricorda all'utente la fine della prova; Stripe lo invia tre giorni prima |
Le regole per il gestore indicate nella documentazione di Stripe sui webhook valgono ancora: verifica la firma usando il corpo grezzo, rispondi rapidamente con un 2xx, gestisci eventi duplicati e fuori ordine, e aspettati nuovi tentativi. La guida cos'è un webhook spiega l'idea, e la guida sui pagamenti elenca le regole in dettaglio.
Passo dopo passo
- Crea prodotti e prezzi in modalità di test di Stripe.
- Aggiungi i segreti: la chiave segreta, gli ID dei prezzi e, più tardi, il segreto di firma del webhook. Non metterli mai nel codice frontend.
- Pagina dei prezzi: il pulsante di ogni piano chiama il tuo server, che crea una Checkout Session in modalità abbonamento per l'utente loggato. Passa il tuo ID utente così il webhook può associare il pagamento all'account.
- Endpoint webhook: verifica le firme e gestisci gli eventi qui sopra, aggiornando un record di abbonamento per utente.
- Limita le funzionalità in base allo stato e al piano memorizzati, verificati sul server per ogni azione protetta, non solo sui pulsanti nascosti.
- Portale clienti: configuralo nella Dashboard di Stripe (a quali piani si può passare, se si può cancellare), poi aggiungi un pulsante Gestisci fatturazione che crea una sessione del portale sul server e reindirizza lì.
- Pagamenti falliti: nelle impostazioni di fatturazione di Stripe, scegli il comportamento dei tentativi e cosa succede dopo l'ultimo. Mostra un banner nell'app mentre lo stato è
past_due. - Testa l'intero ciclo di vita, poi pubblica e registra il webhook live.
Prompt da dare al tuo builder IA
Aggiungi la fatturazione ad abbonamento con Stripe. Piani: Starter (ID prezzo in STRIPE_PRICE_STARTER) e Pro (STRIPE_PRICE_PRO). La pagina dei prezzi crea una Checkout Session in modalità abbonamento sul server usando STRIPE_SECRET_KEY, con l'ID dell'utente loggato allegato. Salva sull'utente l'ID cliente Stripe, l'ID abbonamento, il piano e lo stato. Non esporre mai la chiave segreta al browser.
Aggiungi POST /api/stripe/webhook. Verifica la firma con STRIPE_WEBHOOK_SECRET usando il corpo grezzo della richiesta. Gestisci checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted e customer.subscription.trial_will_end. Registra gli ID degli eventi elaborati così i duplicati vengono ignorati. Aggiorna lo stato dell'utente dall'oggetto abbonamento, non dall'ordine in cui arrivano gli eventi.
Limita le funzionalità Pro sul server: consentile solo quando lo stato è active o trialing e il piano è Pro. Mostra un banner "pagamento fallito, aggiorna la tua carta" quando lo stato è past_due. Aggiungi un pulsante Gestisci fatturazione che apre il portale clienti Stripe per questo utente.
Upgrade, downgrade e proration
Quando un cliente cambia piano, la documentazione di Stripe indica che il cambio spesso crea una proration: il nuovo prezzo viene applicato al resto del periodo di fatturazione in corso. Puoi visualizzare in anteprima le proration o disattivarle. Se i piani hanno lo stesso intervallo, le date di fatturazione restano le stesse; passando da mensile ad annuale, la data di fatturazione si sposta al giorno del cambio. Lasciare che i clienti cambino piano nel portale ti evita di scrivere questa logica, ma nelle impostazioni del portale decidi quali cambi sono consentiti.
Checklist di test
Usa la modalità di test di Stripe e le carte di prova, e percorri ogni stato:
- Un nuovo abbonamento concede il piano giusto all'utente giusto
- Chiudere la scheda subito dopo il pagamento concede comunque l'accesso (prova che il webhook funziona)
- Una carta rifiutata in fase di iscrizione non concede nulla
- Un rinnovo fallito porta l'account in past_due e mostra il banner
- Aggiornare la carta nel portale ripristina lo stato active
- Passare a un piano superiore o inferiore cambia correttamente le funzionalità
- Cancellare alla fine del periodo mantiene l'accesso fino alla data di fine, poi lo rimuove
- Gli utenti in prova ottengono l'accesso, ricevono il promemoria, e passano a pagamento o perdono l'accesso correttamente
- Inviare due volte lo stesso evento webhook non cambia nulla
I test clock di Stripe permettono di simulare il passare del tempo, così puoi testare i rinnovi senza aspettare un mese. Consulta la documentazione di test aggiornata di Stripe per sapere come usarli.
Errori comuni
- Concedere l'accesso sulla pagina di successo. I clienti possono pagare senza mai arrivarci. Usa il webhook.
- Gestire solo il primo pagamento. Rinnovi, fallimenti e cancellazioni arrivano dopo, come eventi.
- Controllare lo stato del piano solo nel frontend. Chiunque può chiamare direttamente la tua API.
- Un utente con più abbonamenti per errore. Controlla se esiste già un abbonamento prima di creare una nuova Checkout Session, oppure manda i clienti esistenti al portale.
- Revocare l'accesso al primo rinnovo fallito. Le carte falliscono per motivi banali. Un breve periodo di tolleranza con un banner chiaro trattiene i clienti.
- Dimenticare il webhook live. Gli endpoint di test e quelli live hanno segreti di firma diversi.
- Ignorare tasse e rimborsi. Decidi la politica di rimborso e verifica gli obblighi fiscali con un commercialista prima del lancio.
Abbonamenti su Mythex
Le app che crei su Mythex usano il tuo account Stripe e le tue chiavi; non esiste una connessione Stripe con un clic per la tua app. Aggiungi le chiavi di test e gli ID prezzo come segreti del progetto, usa prompt come quelli sopra, e testa con le carte di prova di Stripe nell'Anteprima. I webhook richiedono l'URL pubblico della tua app, quindi pubblica prima di registrare l'endpoint in Stripe, e pubblica di nuovo dopo il passaggio alle chiavi live perché l'app live le recepisca. Vedi Accettare pagamenti con Stripe e Gestire i webhook nel tuo backend. Per il prodotto nel suo insieme, come costruire un MVP SaaS spiega cosa costruire attorno alla fatturazione.
Domande
Qual è il modo più semplice per aggiungere abbonamenti con Stripe?
Crea un prodotto con un prezzo ricorrente nella Dashboard di Stripe, invia i clienti a Stripe Checkout in modalità abbonamento, gestisci gli eventi dell'abbonamento con un webhook, e collega un pulsante Gestisci fatturazione al portale clienti ospitato da Stripe. Così non devi costruire tu i moduli delle carte e le schermate per cambiare piano.
Quali eventi webhook di Stripe mi servono per gli abbonamenti?
Come minimo checkout.session.completed per collegare il nuovo abbonamento al tuo utente, invoice.paid per confermare ogni pagamento riuscito, invoice.payment_failed per avvisare dei rinnovi falliti, e customer.subscription.updated e customer.subscription.deleted per seguire i cambi di piano e le cancellazioni.
Cosa succede quando un pagamento di abbonamento fallisce?
Secondo la documentazione di Stripe aggiornata a settembre 2026, l'abbonamento di solito passa a past_due e Stripe può ritentare il pagamento in base alle tue impostazioni. Dopo l'ultimo tentativo, le impostazioni della tua Dashboard decidono se viene cancellato, segnato come non pagato o lasciato past_due.
Posso offrire una prova gratuita senza chiedere una carta?
Sì. Stripe supporta le prove gratuite, e la sua documentazione descrive uno stato paused per le prove che terminano senza un metodo di pagamento, se configurato in quel modo. Chiedere subito la carta di solito significa meno iscrizioni ma più clienti paganti; verifica cosa si adatta al tuo prodotto.