For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /it/docs/web/stripe-payments.md (or send Accept: text/markdown).
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.
Creare l'account Stripe
1. Apri 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 toggleVerificare 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.
Per continuare la configurazione, leggi Aggiungi l'email con Resend.