Come aggiungere pagamenti alla tua app: checkout, abbonamenti e webhook

Il modo più semplice per aggiungere pagamenti alla tua app è Stripe: usa un Payment Link se ti serve solo un pulsante "Acquista" e puoi gestire gli ordini a mano; usa Stripe Checkout se la tua app deve sapere chi ha pagato e reagire automaticamente; e usa Checkout in modalità abbonamento più il portale clienti di Stripe per la fatturazione ricorrente. In ogni caso, tranne nel più semplice, ti serve anche un webhook — un endpoint del server che Stripe chiama quando un pagamento va a buon fine — e dovresti testare tutto con le chiavi di test e le carte di prova di Stripe prima di passare alle chiavi live.

Questa guida spiega ciascuna opzione, la parte sui webhook che la maggior parte delle guide salta, e cosa controllare prima di incassare denaro vero. I dettagli su Stripe provengono dalla documentazione ufficiale di Stripe aggiornata a settembre 2026.

Perché usare un fornitore di pagamenti

Non raccogliere mai i numeri di carta nei tuoi moduli. Gestire direttamente i dati della carta ti porta sotto l'ambito del PCI DSS (lo standard di sicurezza del settore delle carte) ed è una responsabilità seria. Un fornitore come Stripe ospita il modulo di pagamento, memorizza la carta, gestisce l'autenticazione bancaria e comunica alla tua app il risultato. La tua app vede solo "il cliente X ha pagato per Y".

Questa guida usa Stripe perché è molto diffuso, ben documentato e supportato dalla maggior parte dei builder di app basati sull'IA. Esistono altri fornitori, e alcuni operano come "merchant of record" che si fanno carico della gestione dell'IVA per te; se la conformità fiscale ti preoccupa, vale la pena confrontare quel modello.

I tre modi per accettare pagamenti con Stripe

Payment Link

Un Payment Link è una pagina di pagamento ospitata da Stripe che crei nella Dashboard di Stripe senza codice. Ottieni un URL da mettere dietro un pulsante nella tua app, condividere in un'email o mostrare come codice QR. La documentazione di Stripe indica che i Payment Link possono vendere un prodotto, un abbonamento o raccogliere una donazione, e puoi lasciare che i clienti scelgano cosa pagare o limitare il numero di acquisti.

Il punto debole: la tua app non sa automaticamente che un certo utente loggato ha pagato. Per una pagina di donazioni o un piccolo negozio in cui evadi gli ordini a mano dalle notifiche email di Stripe, va bene. Per "paga per sbloccare le funzioni Pro", non va bene.

Stripe Checkout

Checkout è una pagina di pagamento che il tuo server crea su richiesta per un acquisto specifico. Il tuo server dice a Stripe cosa viene acquistato (e facoltativamente quale cliente sta comprando), Stripe restituisce un URL e tu mandi il cliente lì. La documentazione di Stripe lo descrive come supportato sia per pagamenti una tantum sia per abbonamenti, come pagina completa ospitata da Stripe, come pagina incorporata nel tuo sito o come modulo incorporato.

Il flusso:

1. Il cliente clicca Acquista nella tua app.
2. Il tuo server crea una Checkout Session usando la tua chiave segreta, includendo un ID che la collega al tuo utente o ordine.
3. Il cliente viene reindirizzato a Stripe e paga.
4. Stripe lo riporta alla tua pagina di successo.
5. Stripe invia un evento checkout.session.completed al tuo webhook, e il tuo server segna l'ordine come pagato o sblocca l'accesso.

Il passo 2 deve avvenire sul server, perché usa la tua chiave segreta. È il motivo principale per cui Checkout richiede un backend.

Abbonamenti

Gli abbonamenti usano Checkout in modalità abbonamento con un prezzo ricorrente che configuri in Stripe. Il primo pagamento funziona come il flusso descritto sopra. Dopo, rinnovi, carte rifiutate, upgrade e cancellazioni avvengono nel tempo — spesso quando il cliente non è affatto nella tua app — quindi la tua app ne viene a conoscenza solo tramite i webhook.

Per permettere ai clienti di gestire da soli il proprio abbonamento, Stripe offre un portale clienti ospitato. Secondo la documentazione di Stripe, i clienti possono aggiornare i metodi di pagamento e i dati di fatturazione, cambiare o cancellare gli abbonamenti, e visualizzare e scaricare le fatture. Lo configuri nella Dashboard di Stripe e aggiungi un pulsante "Gestisci fatturazione" che porta il cliente lì. Così eviti di costruire tu quelle schermate.

Webhook: la parte che non puoi saltare

Un webhook è una richiesta HTTP che Stripe invia al tuo server quando succede qualcosa. (Vedi cos'è un webhook per l'idea generale.) La guida di Stripe sull'evasione è esplicita: non puoi affidarti solo alla pagina di successo per evadere gli ordini, perché un cliente può pagare e poi perdere la connessione prima che quella pagina si carichi. Per gli abbonamenti e i metodi di pagamento differiti, i webhook sono obbligatori.

Eventi da gestire

Regole per un gestore di webhook corretto

Sono tratte direttamente dalla documentazione di Stripe sui webhook, e i gestori generati dall'IA a volte ne saltano una:

• Verifica la firma. Ogni evento include un header Stripe-Signature. Il tuo gestore la controlla usando il segreto di firma dell'endpoint (inizia con whsec_). Senza questo, chiunque potrebbe inviare al tuo server un falso "pagamento riuscito".
• Usa il corpo grezzo della richiesta. I controlli della firma falliscono se il framework analizza o modifica prima il corpo.
• Rispondi rapidamente con un 2xx, poi svolgi il lavoro più lento. I timeout contano come errori.
• Gestisci i duplicati. Stripe potrebbe consegnare lo stesso evento più di una volta. Registra gli ID degli eventi elaborati, oppure fai in modo che l'evasione sia sicura anche se eseguita due volte.
• Non dare per scontato l'ordine. Stripe non garantisce che gli eventi arrivino nell'ordine in cui sono avvenuti.
• Aspettati nuovi tentativi. In modalità live Stripe ritenta le consegne fallite fino a tre giorni, quindi una breve interruzione non fa perdere pagamenti — ma il tuo gestore deve gestire anche gli eventi in ritardo.

I webhook richiedono un indirizzo HTTPS pubblico, quindi di solito funzionano solo quando la tua app è pubblicata (la CLI di Stripe può inoltrare gli eventi a una macchina locale per gli sviluppatori).

Un prompt che copre l'intero flusso

Aggiungi un acquisto una tantum con Stripe Checkout per il "Pro pack" (ID del prezzo in STRIPE_PRICE_ID). Crea la Checkout Session sul server usando STRIPE_SECRET_KEY dai segreti, e includi nella sessione l'ID dell'utente loggato. Aggiungi un endpoint POST /api/stripe/webhook che verifica la firma Stripe con STRIPE_WEBHOOK_SECRET usando il corpo grezzo della richiesta, gestisce checkout.session.completed e segna quell'utente come in possesso del Pro pack. Rendilo sicuro se lo stesso evento arriva due volte. Pagine di successo e di annullamento. Non esporre mai la chiave segreta al browser.

Per gli abbonamenti, aggiungi: "Usa la modalità abbonamento con STRIPE_PRICE_ID. Gestisci invoice.paid, invoice.payment_failed, customer.subscription.updated e customer.subscription.deleted. Aggiungi un pulsante Gestisci fatturazione che apre il portale clienti di Stripe."

Modalità di test

Stripe ha ambienti separati sandbox (test) e live, con chiavi separate. Le chiavi sandbox iniziano con pk_test_, sk_test_ o rk_test_; quelle live con pk_live_, sk_live_ o rk_live_. Le transazioni di test non movimentano denaro.

Carte di test utili dalla documentazione di test di Stripe (qualsiasi data di scadenza futura, qualsiasi CVC di tre cifre):

Testa almeno:

• Un pagamento riuscito sblocca la cosa giusta per l'utente giusto
• Una carta rifiutata mostra un messaggio chiaro e non sblocca nulla
• Chiudere la scheda del browser subito dopo il pagamento porta comunque all'accesso (questo prova che funziona il webhook, non solo la pagina di successo)
• Annullare nella pagina di Stripe riporta l'utente nella tua app senza addebiti
• Per gli abbonamenti: annulla nel portale clienti e verifica che l'accesso termini quando deve

Passare alla modalità live

1. Attiva il tuo account Stripe con i dati della tua attività e della tua banca.
2. Inserisci le chiavi live nei segreti della tua app. Stripe consiglia chiavi con restrizioni, con solo i permessi di cui la tua integrazione ha bisogno, invece di una chiave segreta senza restrizioni.
3. Crea un endpoint webhook live che punti alla tua app pubblicata. Ha un proprio segreto di firma, diverso da quello di test — aggiornalo.
4. Ricrea prodotti e prezzi in modalità live; gli ID della modalità di test lì non esistono.
5. Fai un piccolo acquisto reale e rimborsalo.

Tieni ogni chiave nei segreti del progetto, mai nel codice o in chat. La nostra checklist di sicurezza copre più in dettaglio chiavi e verifica dei webhook.

Tasse, rimborsi e documenti

I pagamenti portano obblighi che il codice non risolve. Non è consulenza fiscale; chiedi a un commercialista.

• IVA e imposte sulle vendite. A seconda di dove siete tu e i tuoi clienti, potresti dover registrarti, applicare e dichiarare l'imposta. Stripe Tax può calcolare e riscuotere l'imposta al checkout, monitorare dove le tue vendite potrebbero generare un obbligo, e aiutare con le registrazioni e le dichiarazioni — ma la responsabilità resta tua. I fornitori merchant of record sono un'alternativa che si fa carico di più di questo.
• Rimborsi e contestazioni. Decidi la tua politica di rimborso prima del lancio e pubblicala sul sito. Le contestazioni (chargeback) succedono; conserva le registrazioni di cosa è stato acquistato e consegnato.
• Ricevute e fatture. Stripe può inviare ricevute via email; le attività possono aver bisogno di fatture vere e proprie.
• Commissioni. Ogni fornitore addebita una commissione per transazione. Controlla la pagina dei prezzi aggiornata del fornitore invece di fidarti delle cifre negli articoli.

Quale configurazione si adatta alla tua app

• Donazioni o una manciata di prodotti: Payment Link. Vedi come costruire un sito di donazioni per associazioni non profit.
• Un negozio con carrello: Checkout con voci d'ordine e un webhook. Vedi come costruire un negozio online.
• SaaS o abbonamenti: Checkout in modalità abbonamento, webhook e portale clienti. Vedi come costruire un MVP SaaS e come definire il prezzo di un prodotto SaaS.
• Un marketplace che paga i venditori: una configurazione diversa e più regolamentata (Stripe Connect o simili). Pianificala a parte.

Aggiungere pagamenti in Mythex

I pagamenti nelle app che crei su Mythex usano il tuo account Stripe e le tue chiavi; non esiste un "Collega Stripe" con un clic per la tua app. Il flusso tipico:

1. Ottieni le chiavi test di Stripe.
2. Aggiungi STRIPE_SECRET_KEY (e più tardi il segreto del webhook) ai segreti del progetto — tramite /secrets, le impostazioni del progetto, o la scheda dei segreti che l'agente mostra quando ha bisogno di una chiave.
3. Chiedi all'agente Checkout con un prompt simile a quello sopra.
4. Testa in Anteprima con le carte di test. Pubblica prima di registrare il webhook, perché richiede il tuo URL pubblico.
5. Dopo il passaggio alle chiavi live, pubblica di nuovo perché l'app live le recepisca.

Vedi Accettare pagamenti con Stripe e Gestire i webhook nel tuo backend nella documentazione.

Domande