Collegare Stripe a un ecommerce significa dotare il sito di un sistema di incasso professionale, capace di accettare carte di credito, carte di debito, wallet come Apple Pay e Google Pay e metodi di pagamento locali. Per un’azienda che vende online non è un dettaglio tecnico secondario: è l’infrastruttura che trasforma un visitatore in un cliente pagante. Questa guida spiega nel dettaglio tutto il percorso, dall’iscrizione alla piattaforma fino alla messa online dei pagamenti reali, con particolare attenzione all’ambiente di test, alle chiavi API e ai codici che spesso generano confusione in chi affronta l’integrazione per la prima volta.
Perché scegliere Stripe per l’ecommerce
Stripe è uno dei gateway di pagamento più diffusi al mondo e in Italia è pienamente legale e operativo. La sua forza sta nella combinazione di tre elementi: commissioni trasparenti, assenza di costi fissi mensili sul piano base e una documentazione tecnica tra le più curate del settore.
Sul fronte dei costi, la tariffa standard per le carte emesse nell’Area economica europea è dell’1,5% più 0,25 € per ogni transazione andata a buon fine, mentre le carte extra-europee hanno una commissione più alta, del 3,25% più 0,25 €. Non ci sono canoni mensili né costi di attivazione sul piano standard: si paga soltanto quando si incassa. Per un confronto rapido, PayPal applica commissioni sensibilmente superiori sui pagamenti europei, il che rende Stripe più conveniente per chi vende prevalentemente a clienti dell’area euro.
Un limite da conoscere fin da subito riguarda la fatturazione: Stripe non emette fatture elettroniche nel formato XML richiesto dall’Agenzia delle Entrate italiana con invio al Sistema di Interscambio. La gestione fiscale delle fatture va quindi affrontata separatamente, con un software di contabilità dedicato.
Fase 1: la registrazione dell’account Stripe
Il primo passo è creare l’account sulla piattaforma. La procedura è gratuita e richiede pochi minuti.
Si accede a stripe.com e si sceglie di iniziare la registrazione. Vengono richiesti l’indirizzo email, un nome e una password. È fondamentale usare una password univoca, diversa da quelle utilizzate su altri servizi: se un altro sito venisse compromesso, credenziali riutilizzate potrebbero esporre anche l’account di incasso. Subito dopo, Stripe invia un’email di conferma all’indirizzo indicato per verificare che sia reale.
Appena l’account è creato, è già utilizzabile in modalità di test. Questo è un punto importante: non serve completare tutta la verifica dell’attività per iniziare a lavorare all’integrazione tecnica. Si può sviluppare e collaudare tutto prima ancora di poter incassare denaro vero.
Fase 2: l’ambiente di test (sandbox)
L’ambiente di test, chiamato anche sandbox, è lo spazio in cui si simulano transazioni senza che venga mai movimentato denaro reale. È qui che si costruisce e si verifica l’intera integrazione in totale sicurezza.
Nella dashboard di Stripe esiste un interruttore che permette di passare dalla modalità di test a quella live. In modalità test tutte le operazioni sono fittizie: gli ordini, i pagamenti, i rimborsi e le notifiche funzionano esattamente come in produzione, ma non producono alcun addebito effettivo. Questo consente di riprodurre l’intero flusso di acquisto e di correggere eventuali errori prima di esporre il sistema ai clienti veri.
Per simulare i pagamenti, Stripe mette a disposizione numeri di carta di prova. Il più noto è il numero che inizia con 4242 4242 4242 4242: inserito nel checkout in modalità test, simula un pagamento con carta andato a buon fine. Esistono anche carte di test specifiche per simulare pagamenti rifiutati, fondi insufficienti o richieste di autenticazione aggiuntiva, così da verificare come il sito reagisce in ogni scenario. Come data di scadenza si usa una qualsiasi data futura e come codice di sicurezza tre cifre a piacere.
Chiudere questa fase con test approfonditi è ciò che distingue un’integrazione affidabile da una fragile: conviene provare pagamenti riusciti, pagamenti falliti, rimborsi e casi limite prima di andare online.
Fase 3: le chiavi API e i codici da conoscere
Il cuore del collegamento tra il sito e Stripe sono le chiavi API. Si trovano nella dashboard, nella sezione dedicata agli sviluppatori, alla voce che raccoglie le chiavi (API Keys), collocata poco sopra i webhook.
Esistono due tipi di chiave e ciascuno esiste sia in versione test sia in versione live.
La chiave pubblicabile (Publishable key) è quella che può stare nel codice visibile al browser, ad esempio nel frontend del checkout. Nella versione di test comincia con il prefisso pk_test_, in quella di produzione con pk_live_. Serve a inizializzare gli elementi di pagamento lato cliente e non è un segreto critico.
La chiave segreta (Secret key) è invece la chiave riservata, quella che autorizza le operazioni sensibili come la creazione degli addebiti. Nella versione di test comincia con sk_test_, in quella di produzione con sk_live_. Questa chiave non deve mai finire nel codice inviato al browser né essere pubblicata da nessuna parte: va conservata esclusivamente sul server, idealmente in un archivio di segreti e non scritta direttamente nel codice sorgente. Dove possibile, è buona pratica usare chiavi API con restrizioni al posto della chiave segreta completa, limitando i permessi allo stretto necessario. Vale la pena ricordare che il personale di Stripe non chiede mai le chiavi: qualunque richiesta in tal senso è un tentativo di frode.
La logica dei prefissi (test contro live) è la salvaguardia più importante da tenere a mente: usare per errore le chiavi di test in produzione impedisce di incassare davvero, mentre usare le chiavi live durante lo sviluppo rischia di generare addebiti reali indesiderati.
Fase 4: la scelta del metodo di integrazione
A questo punto entra in gioco il modo in cui il sito dialoga con Stripe. Le strade principali sono due e la scelta dipende dalla tecnologia dell’ecommerce.
Se il negozio è costruito su una piattaforma diffusa come WooCommerce per WordPress, la via più pulita è il plugin ufficiale del gateway Stripe. Dopo averlo installato, è sufficiente incollare le chiavi API nelle impostazioni dei pagamenti, partendo dalle chiavi di test. Il plugin gestisce automaticamente il flusso di pagamento, i wallet come Apple Pay e Google Pay e l’autenticazione forte del cliente richiesta dalla normativa europea. Molte piattaforme offrono anche un pulsante che avvia direttamente la creazione o la connessione dell’account Stripe dal pannello di amministrazione, senza dover copiare manualmente le chiavi.
Se invece l’ecommerce è sviluppato su misura, la soluzione più comoda è Stripe Checkout, ovvero la pagina di pagamento ospitata direttamente da Stripe. In questo scenario il server dell’ecommerce crea una sessione di pagamento con i dati dell’ordine (importo, valuta, indirizzi di ritorno) e reindirizza il cliente verso la pagina sicura di Stripe. Al termine, il cliente viene riportato sul sito. Questo approccio riduce moltissimo le responsabilità in materia di sicurezza dei dati della carta, perché i dati sensibili non transitano mai direttamente dal server dell’ecommerce.
Fase 5: la configurazione dei webhook
I webhook sono uno degli aspetti più trascurati e allo stesso tempo più critici dell’integrazione, ma il concetto di base è semplice. Un webhook è una chiamata automatica che Stripe invia al tuo server ogni volta che succede qualcosa di rilevante: un pagamento riuscito, un pagamento fallito, un rimborso, una contestazione. Il flusso è l’opposto di quello a cui si è abituati: di solito è il sito a interrogare Stripe, mentre qui è Stripe che, appena l’evento accade, avvisa il sito senza che nessuno debba chiedere nulla.
La regola d’oro è non confermare mai un ordine basandosi solo sul fatto che il cliente è tornato sulla pagina di conferma. Quella pagina può essere raggiunta anche senza aver realmente pagato, ad esempio ricaricando un vecchio link o chiudendo il pagamento a metà. La conferma affidabile arriva soltanto dal webhook, in particolare dall’evento che segnala il completamento della sessione di pagamento. È lì, e solo lì, che il sito deve considerare l’ordine pagato e sbloccare la merce o il servizio.
Per far funzionare un webhook servono due estremità che si parlano. La prima è un endpoint sul tuo sito, cioè un indirizzo web dedicato che sa ricevere e interpretare i messaggi di Stripe: non è una pagina pensata per gli utenti, ma un punto di ricezione tecnico che risponde soltanto a Stripe. La seconda è la registrazione di quell’indirizzo dentro la dashboard di Stripe, nella sezione dedicata agli sviluppatori, dove si comunica a Stripe dove inviare le notifiche e quali eventi far arrivare. In genere non serve iscriversi a tutti gli eventi disponibili, ma solo a quelli utili all’attività, come il completamento del pagamento.
Al momento della registrazione dell’endpoint, Stripe fornisce un codice riservato chiamato signing secret, che inizia con il prefisso whsec_. Questo codice va salvato sul server e serve a verificare la firma di ogni notifica in arrivo: il sito ricalcola la firma a partire dal contenuto del messaggio e da questo codice, e accetta la notifica solo se le due firme coincidono. Senza questa verifica chiunque potrebbe inviare al sito notifiche fasulle, simulando pagamenti mai avvenuti per ottenere merce o servizi senza pagare. La validazione della firma è quindi una misura di sicurezza irrinunciabile.
Vale la pena ricordare due dettagli pratici. Il primo è che l’ambiente di test e quello di produzione hanno endpoint e signing secret distinti: l’endpoint registrato in modalità test non vale in modalità live, e viceversa. Il secondo è che la dashboard di Stripe mostra, per ogni notifica inviata, se il sito l’ha ricevuta correttamente e con quale esito, permettendo di reinviare manualmente le notifiche non andate a buon fine. Questo rende la sezione dei webhook anche un prezioso strumento di controllo e di diagnostica quando qualcosa non funziona come previsto.
Fase 6: l’attivazione dell’account per incassare davvero
Finché si resta in modalità test non si incassa denaro. Per passare ai pagamenti reali occorre attivare l’account, superando la verifica dell’attività richiesta dalle normative antiriciclaggio (le cosiddette regole KYC, Know Your Customer). Questi controlli non sono un’invenzione di Stripe: sono imposti dai partner finanziari e dalle autorità di vigilanza per prevenire gli abusi del sistema finanziario.
Per completare l’attivazione servono alcuni elementi:
- le informazioni sull’attività, comprensive di codice fiscale e partita IVA, e i dati dell’assetto proprietario con i dettagli su titolari e amministratori;
- il tipo di attività, scegliendo tra impresa individuale e società a seconda della forma giuridica;
- un documento di identità, come carta d’identità o passaporto, e in alcuni casi un selfie per confermare l’identità della persona collegata all’account;
- l’IBAN del conto su cui ricevere gli incassi, intestato all’azienda o al titolare;
- l’indirizzo del sito web, che Stripe verifica realmente per capire cosa viene venduto.
Proprio perché Stripe controlla il sito, conviene assicurarsi che siano ben visibili i termini di servizio, la privacy policy e una descrizione chiara di prodotti e servizi: pagine complete e trasparenti velocizzano l’approvazione.
Due dettagli meritano attenzione particolare. Il primo è il descrittore dell’estratto conto (statement descriptor), cioè il testo che i clienti vedranno sull’estratto della propria carta: deve contenere tra 5 e 22 caratteri, con almeno 5 lettere, e non può includere caratteri speciali come minore, maggiore, apice, virgolette o asterisco. Conviene renderlo riconoscibile, ad esempio con il nome del negozio, per ridurre le contestazioni dovute a pagamenti non riconosciuti. Il secondo è la scelta del Paese: una volta attivato l’account, il Paese di origine dell’attività non si può più modificare. Se l’azienda opera in Italia, l’account va aperto come italiano fin dall’inizio.
Va infine ricordato che il primo bonifico verso il conto bancario è soggetto a un periodo di attesa fisiologico, previsto per ragioni di mitigazione del rischio: non è un malfunzionamento ma una prassi standard.
Fase 7: dal test alla produzione
Quando l’integrazione è stata collaudata a fondo in sandbox e l’account risulta attivato, si compie il passaggio finale. Si sostituiscono le chiavi di test con le chiavi live corrispondenti, si verifica che i webhook puntino all’endpoint di produzione con il relativo signing secret e si esegue un ultimo controllo reale, idealmente con una piccola transazione vera che poi si può rimborsare.
Da questo momento il sito incassa pagamenti reali. È buona norma monitorare i primi ordini dalla dashboard, controllare che le notifiche webhook arrivino correttamente e tenere sotto controllo l’area delle contestazioni, ricordando che rispondere manualmente a una contestazione comporta una commissione dedicata, rimborsata solo se la contestazione viene vinta.
Errori da evitare nell’integrazione di Stripe
Alcuni errori ricorrono con frequenza e vale la pena anticiparli:
- esporre la chiave segreta nel codice frontend o in repository pubblici: va trattata come una password;
- considerare pagato un ordine sulla sola base del ritorno del cliente sulla pagina di successo, senza attendere la conferma del webhook;
- dimenticare di verificare la firma dei webhook, lasciando aperta la porta a notifiche contraffatte;
- confondere chiavi di test e chiavi live: un controllo sistematico dei prefissi evita sia mancati incassi in produzione sia addebiti reali durante lo sviluppo.
Configurazione Stripe
Collegare Stripe a un ecommerce è un percorso lineare se affrontato nell’ordine giusto: prima la registrazione dell’account, poi lo sviluppo e il collaudo in sandbox con le chiavi di test e le carte di prova, quindi la configurazione dei webhook per gestire in modo affidabile le conferme di pagamento, l’attivazione dell’account con la verifica dell’attività e infine il passaggio alle chiavi live. La cura riposta nell’ambiente di test e nella corretta gestione delle chiavi e dei webhook è ciò che determina la solidità del sistema di incasso. Un’azienda che segue questi passaggi ottiene un checkout professionale, sicuro e conforme alle normative europee, pronto a convertire i visitatori del sito in clienti effettivi.