> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # Aggiungi i pagamenti con Stripe Crea un account Stripe gratuito, un prodotto con un prezzo ricorrente, una chiave segreta e il webhook firmato che concede gli entitlement dopo il checkout. ## Procedura dettagliata per principianti Prerequisiti: l'app in esecuzione in locale (Online in 5 minuti) e un database migrato per account reali (Configura il database). Serve un indirizzo email per l'account Stripe — niente carta e nessun addebito. Tutto in questa guida avviene in modalità test: soldi finti, numeri di carta di prova, tentativi illimitati prima di andare in produzione. Terminologia rapida: la modalità test è la sandbox di Stripe — l'interruttore Test mode della dashboard tiene finti ogni chiave, prodotto e pagamento finché non lo spegni. Una secret key (`sk_test_…`) è la password del tuo server verso Stripe. Un prodotto con un prezzo è ciò che i clienti comprano; un price id (`price_…`) lo nomina nel codice. Un webhook è Stripe che chiama il tuo server quando un pagamento riesce o un abbonamento cambia, e il signing secret (`whsec_…`) prova che la chiamata arriva davvero da Stripe. Cosa crei: un account Stripe, un prodotto con un prezzo ricorrente, una chiave API segreta e un endpoint webhook — una ventina di minuti. Stripe ospita la pagina di checkout stessa; il kit crea la sessione lato server e reindirizza, quindi non serve nessuna publishable key da browser. Tieni a mente l'ambito: questa guida vende solo abbonamenti web. Gli acquisti dentro l'app iOS/Android devono passare per la fatturazione di Apple e Google — mai per Stripe Checkout — ecco perché il mobile usa RevenueCat al suo posto. [Configura il database](https://supastack.dev/it/docs/web/setup-database.md) [Configura RevenueCat per gli acquisti mobile](https://supastack.dev/it/docs/mobile/revenuecat.md) ## Creare l'account Stripe 1. Apri [stripe.com](https://stripe.com) → Start now e registrati con la tua email. 2. L'onboarding chiede della tua attività — in modalità test puoi saltare ogni domanda e usare comunque tutta la sandbox; completa l'attivazione solo prima di accettare pagamenti reali. Atteso: arrivi sulla dashboard con l'interruttore Test mode visibile nell'intestazione. Lascialo attivo per tutto quello che segue — le chiavi live vanno più avanti nel secret store di produzione, mai in un file env del portatile. ## Copiare le chiavi API 1. Nella dashboard apri Developers → API keys. 2. Vedi due chiavi di test: una Publishable key `pk_test_…` e una Secret key mascherata. Fai clic su Reveal test key accanto al segreto e copia il valore `sk_test_…`. Al kit serve solo la secret key: le sessioni di checkout vengono create sul server e l'utente viene reindirizzato alla pagina ospitata di Stripe, quindi nessuna publishable key finisce nelle variabili env. Se un prodotto che costruirai in seguito aggiungesse Stripe.js useresti la publishable key lato client; il flusso di fatturazione del kit non lo fa. La chiave `sk_test_…` è una credenziale completa per l'account sandbox: vive in `apps/web/.env.local` o in un secret store, mai in variabili `NEXT_PUBLIC_`/`EXPO_PUBLIC_` e mai in Git. ## Creare il prodotto e il prezzo 1. Apri Product catalog → Add product. 2. Chiamalo come il tuo piano — `Pro` corrisponde al piano incluso del kit — dagli un prezzo e scegli Recurring (mensile, per esempio): il checkout del kit crea sessioni in modalità abbonamento, che richiedono un prezzo ricorrente, non uno una tantum. 3. Salva, apri il prodotto e copia il price id — inizia con `price_…` (non `prod_…`, che è l'id del prodotto). Il piano `pro` incluso mostra già un commutatore Monthly/Yearly: il mensile paga con `STRIPE_PRICE_ID`, e l'opzione annuale ha bisogno di un secondo prezzo ricorrente in `STRIPE_PRICE_ID_PRO_YEARLY` — senza, un checkout annuale fallisce con `price-unconfigured`. Cambia i nomi dei piani, gli importi e ciò che concede un acquisto in `apps/web/src/product-plans.ts` — Stripe conserva il lato denaro, il file dei piani conserva il lato entitlement. ## Aggiungere l'endpoint webhook Il webhook è ciò che concede davvero l'accesso: il kit attiva l'entitlement solo dopo l'arrivo di un evento Stripe firmato, quindi una sola redirezione di checkout non prova nulla. 1. Apri Developers → Webhooks → Add endpoint. 2. Endpoint URL: il tuo URL pubblico più `/api/billing/webhook` — per esempio `https://yourdomain.com/api/billing/webhook`. Gli altri provider di fatturazione hanno il proprio percorso sotto quella directory; il ricevitore di Stripe vive alla radice. 3. In Select events scegli gli eventi che il kit gestisce: `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed`, `invoice.paid`, `invoice.payment_failed`, `customer.subscription.created`, `customer.subscription.updated` e `customer.subscription.deleted`. 4. Crea l'endpoint, apri la sua pagina, fai clic su Reveal sotto Signing secret e copia il valore `whsec_…` — ogni endpoint ha il proprio segreto. Lo sviluppo locale non può ricevere i server di Stripe, quindi usa la Stripe CLI al suo posto: `stripe login` una volta, poi `stripe listen --forward-to localhost:3000/api/billing/webhook` in un secondo terminale. Stampa un `whsec_…` temporaneo — quel valore, non quello della dashboard, va in `.env.local` finché `stripe listen` è in esecuzione. ## Aggiungere i valori all'app Inserisci le righe qui sotto in `apps/web/.env.local`. `BILLING_PROVIDER=stripe` seleziona l'adattatore; le altre tre sono la chiave, il prezzo e il signing secret. Attivare il provider con una di esse mancante fa fallire l'avvio e nomina la variabile. Tutti e tre i valori `STRIPE_*` restano lato server — mai `NEXT_PUBLIC_`/`EXPO_PUBLIC_`, mai committati; la produzione li riceve tramite il gestore di segreti dell'hosting (la guida al deployment copre Secret Manager). Riavvia il server di sviluppo dopo le modifiche. ``` # apps/web/.env.local BILLING_PROVIDER=stripe STRIPE_SECRET_KEY=sk_test_… STRIPE_PRICE_ID=price_… STRIPE_WEBHOOK_SECRET=whsec_… # `stripe listen` value locally; endpoint signing secret in production # STRIPE_PRICE_ID_PRO_YEARLY=price_… # required for the shipped Yearly toggle ``` ## Verificare e risolvere i problemi Avvia `stripe listen --forward-to localhost:3000/api/billing/webhook` e lascialo in esecuzione, riavvia il server di sviluppo, poi apri `/billing`, scegli il piano Pro e completa il checkout ospitato di Stripe con la carta di prova `4242 4242 4242 4242`, una scadenza futura qualsiasi e un CVC qualsiasi. Atteso: l'app torna su `/billing?checkout=success` e l'entitlement del workspace passa ad attivo — il terminale di listen registra gli eventi consegnati, e Developers → Webhooks → il tuo endpoint nella dashboard mostra consegne verdi. Per esercitare il ricevitore senza cliccare nel checkout, `stripe trigger checkout.session.completed` invia un evento sintetico attraverso l'inoltro di listen. Fallimenti comuni: un 400 a ogni consegna significa che il signing secret non corrisponde a quell'endpoint — ricopia il `whsec_…` dell'endpoint giusto e aggiorna l'env; effetti nulli silenziosi significano che `BILLING_PROVIDER` è ancora `local`; e chiavi `sk_live_` mischiate in un montaggio di test significano che hai copiato le chiavi della modalità sbagliata — tieni test e live rigorosamente separati. Il kit include lo stesso adattatore a contratto unico per Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo e PayPal — stesso flusso, console e nomi env diversi — e gli acquisti mobile restano su RevenueCat, non su Stripe. [Confronta i provider di fatturazione](https://supastack.dev/it/docs/web/setup-payments.md) [Aggiungi poi l'email con Resend](https://supastack.dev/it/docs/web/resend-email.md) [Gli acquisti mobile usano RevenueCat](https://supastack.dev/it/docs/mobile/revenuecat.md) Per continuare la configurazione, leggi [Aggiungi l'email con Resend](https://supastack.dev/it/docs/web/resend-email.md). ## Successivo [Aggiungi l'email con Resend](https://supastack.dev/it/docs/web/resend-email.md)