Tutto il necessario per costruire un'integrazione Stripe che regge in produzione: come funzionano i pagamenti e il modello a oggetti di Stripe, Payment Element e Checkout, Billing e ciclo di vita degli abbonamenti, prezzi a consumo, Connect per piattaforme e marketplace, webhook e idempotenza, riconciliazione, dunning, regole Radar antifrode, riduzione del perimetro PCI e cosa comporta davvero una migrazione da un altro processore. Nessuna approssimazione, nessuna omissione.
Stripe è la piattaforma di pagamenti più completa disponibile, e quella completezza è anche il suo principale rischio di complessità. Esistono più modi per accettare un pagamento, più superfici prodotto per gli abbonamenti e un modello a eventi che richiede una gestione attenta a scala produzione. Questa guida descrive come pensiamo e implementiamo ogni livello, nell'ordine in cui si incontrano tipicamente.
Prima di scrivere una riga di codice di integrazione, vale la pena capire come Stripe modella il movimento di denaro, perché la gerarchia degli oggetti plasma ogni decisione successiva. I tre oggetti fondamentali sono il Customer, il PaymentMethod e il PaymentIntent.
Un Customer è un'identità in Stripe che possiede metodi di pagamento e ha una cronologia di fatturazione. Un PaymentMethod rappresenta uno strumento di pagamento memorizzato: una carta, un conto bancario, un wallet. Un PaymentIntent è un record di un tentativo di riscuotere denaro ed è l'oggetto che guida il flusso di pagamento. Tutto il resto, Subscription, Invoice, Charge, Transfer, è costruito su questi tre.
Una conseguenza di questo modello conta più di qualsiasi altra cosa in una prima integrazione: non evadete mai un ordine basandovi su un redirect del browser. I redirect possono fallire, essere aggiornati o falsificati. Il trigger corretto per l'evasione è il webhook payment_intent.succeeded consegnato da server a server da Stripe. Questo è il punto in cui la maggior parte delle prime integrazioni sbaglia.
Stripe offre due modi per raccogliere un pagamento sul frontend. Il Payment Element è un componente React integrabile che montate all'interno della vostra pagina, dandovi pieno controllo sull'interfaccia circostante mentre Stripe gestisce i campi carta sensibili e il flusso di autenticazione. Checkout è una pagina ospitata sul dominio di Stripe verso cui reindirizzate, richiedendo quasi nessun lavoro frontend in cambio di minore flessibilità nel design.
La scelta tra i due dipende in genere da quanto controllo serve e quanto perimetro PCI si vuole accettare. Entrambe le opzioni usano l'iframe di Stripe per gestire i dati carta, quindi nessuna delle due aumenta significativamente il perimetro PCI, ma il Payment Element richiede più codice frontend e un'implementazione dei webhook più attenta. Per la maggior parte dei prodotti SaaS il Payment Element è la scelta giusta perché il controllo sul design e sulla conversione vale il lavoro extra.
payment_intent.succeeded, payment_intent.payment_failed e charge.dispute.created come minimo.La regola della chiave di idempotenza. Ogni chiamata API Stripe che crea o modifica un oggetto dovrebbe includere un header Idempotency-Key. Usate un identificatore stabile derivato dall'elemento che state creando, ad esempio l'ID ordine interno, non un UUID casuale generato al momento della richiesta. In questo modo un retry da un errore di rete o un crash del server è sicuro.
Stripe comunica in modo asincrono tramite webhook: richieste HTTP POST a un endpoint sul vostro server, con un payload JSON che descrive un evento. Il webhook è la fonte di verità canonica per lo stato del pagamento. Se non lo elaborate, non sapete cosa è successo.
Stripe garantisce la consegna almeno una volta, il che significa che lo stesso evento può arrivare più di una volta, in particolare dopo che il vostro server restituisce un 5xx o va in timeout. Il vostro webhook handler deve essere idempotente: elaborare lo stesso evento due volte deve produrre lo stesso risultato che elaborarlo una volta. In pratica, questo significa memorizzare l'ID dell'evento Stripe nel database prima di fare qualsiasi lavoro e verificarlo prima di elaborare qualsiasi consegna successiva dello stesso evento.
customer.subscription.trial_will_end (ricorda all'utente), invoice.payment_failed (avvia la sequenza di dunning), customer.subscription.updated (sincronizza le modifiche al piano nel database), e customer.subscription.deleted (revoca l'accesso). Mancarne anche uno crea una situazione in cui Stripe e il vostro sistema non concordano su ciò a cui un cliente ha accesso.Verificate ogni webhook in arrivo usando la verifica della firma di Stripe prima di elaborarlo. La firma è nell'header Stripe-Signature e l'SDK di Stripe fornisce un metodo constructEvent che la valida rispetto al vostro webhook signing secret. Saltare questo controllo significa che qualsiasi attore che scopre il vostro URL webhook può inviare eventi falsi.
Restituite un 200 immediatamente dopo aver verificato la firma e messo in coda l'evento per l'elaborazione asincrona. Non fate il lavoro in modo sincrono nell'handler HTTP: la logica dei retry di Stripe tratta qualsiasi risposta che impiega più di 30 secondi come un fallimento, e la vostra elaborazione potrebbe richiedere più tempo.
Stripe Billing aggiunge un livello di oggetti sopra le primitive di pagamento fondamentali: Product, Price, Subscription e Invoice. Un Product è ciò che vendete; un Price definisce i termini (tariffa fissa, per postazione, a consumo, una tantum). Una Subscription collega un Customer a un Price e genera Invoice secondo un calendario. Un Invoice è il tentativo di addebito.
Il vantaggio di usare Billing rispetto a costruire la propria logica di abbonamento è che Stripe gestisce la pianificazione, la proration sui cambi di piano, la generazione di PDF delle fatture, le ricevute via email ai clienti e la logica di retry sui pagamenti falliti. Il costo è che il database deve rimanere sincronizzato con la rappresentazione di Stripe di ogni abbonamento, il che richiede una gestione attenta dei webhook.
Quando un cliente fa upgrade o downgrade a metà ciclo, Stripe calcola la proration di default: il valore residuo del vecchio piano viene accreditato e il nuovo piano viene addebitato per il resto del ciclo. Potete controllare il comportamento della proration quando aggiornate l'abbonamento, addebitando immediatamente, rinviando alla prossima fattura o disabilitando del tutto la proration. La scelta giusta dipende dal modello di pricing e da ciò che si aspettano i clienti.
Stripe supporta i periodi di prova a livello di Price, che li applica automaticamente a ogni nuovo abbonato, oppure a livello di Subscription per override personalizzati. Durante una prova, Stripe può raccogliere un metodo di pagamento in anticipo senza addebito immediato (il default per la maggior parte dei SaaS) oppure saltare il metodo di pagamento e richiederlo solo quando la prova termina. Richiedere una carta in anticipo riduce la frizione da prova a pagamento al costo di meno inizi di prova. I dati su quale approccio converte meglio variano significativamente per prodotto e fascia di prezzo.
I prezzi a consumo, detti anche metered billing, addebitano ai clienti in base a quanto usano piuttosto che a una tariffa fissa. Stripe supporta questo tramite Billing Meter, che accetta record di eventi di utilizzo e li aggrega in voci di riga della fattura alla fine di ogni periodo di fatturazione.
Il pattern di implementazione è: la vostra applicazione invia eventi di utilizzo all'API Meter Events di Stripe ogni volta che si verifica un'azione fatturabile. Alla fine del periodo di fatturazione, Stripe aggrega gli eventi secondo la strategia di aggregazione configurata (somma, massimo o ultimo valore) e genera la voce di riga della fattura dal risultato. Il database non deve mantenere un totale progressivo per la fatturazione; Stripe è la fonte di verità per l'utilizzo.
Idempotenza sugli eventi di utilizzo. I record di Meter Event accettano un campo identifier. Impostatelo su un ID stabile per l'azione specifica (ad esempio, il vostro ID evento interno). Se inviate lo stesso evento due volte con lo stesso identificatore, Stripe deduplicarà. Senza questo, un retry da un errore di rete raddoppia il conteggio di utilizzo e sovrafattura il cliente.
Il churn involontario, i clienti che smettono di pagare perché la carta è scaduta o rifiutata piuttosto che perché hanno scelto di andarsene, rappresenta tipicamente dal 20 al 40 percento del churn totale per un SaaS con fatturazione mensile. La maggior parte è recuperabile se costruite la sequenza giusta. Stripe offre Smart Retries, che usa il machine learning per temporizzare i tentativi di retry nei momenti in cui i tassi di approvazione sono più alti. Oltre a questo, dovreste costruire una sequenza di dunning nel vostro prodotto.
Una sequenza di dunning di base funziona così: su invoice.payment_failed, inviate al cliente una email con un link per aggiornare il metodo di pagamento. Aspettate da tre a quattro giorni e riprovate. Se il secondo tentativo fallisce, inviate una seconda email con un oggetto più incisivo. Riprovate dopo altri tre giorni. Se il terzo tentativo fallisce, portate il cliente in uno stato di grazia invece di cancellare immediatamente, inviate un avviso finale e cancellate dopo sette giorni senza azioni. Lo stato di grazia conta: preserva l'account e la relazione mentre il cliente risolve il problema della carta ed evita la frizione di un flusso di cancellazione e riattivazione.
Il customer portal di Billing di Stripe gestisce il flusso di aggiornamento del metodo di pagamento senza configurazione aggiuntiva se volete evitare di costruirlo voi stessi. È una pagina ospitata sul dominio di Stripe, simile a Checkout, su cui i clienti atterrano dal link nella email di dunning.
Stripe Connect è la superficie prodotto per piattaforme e marketplace dove il denaro scorre attraverso la vostra applicazione verso altre aziende o individui. Se trattenete una commissione di prenotazione e passate il resto a un fornitore di servizi, o addebitate a un acquirente e dividete il pagamento tra un marketplace e un venditore, state costruendo un'integrazione Connect.
Esistono tre tipi di account Connect e la scelta ha conseguenze reali. Gli account Standard hanno la propria dashboard Stripe e gestiscono le proprie contestazioni e rimborsi; la vostra piattaforma ha controllo limitato ma onere di conformità minimo. Gli account Express usano un flusso di onboarding ospitato da Stripe e una dashboard semplificata; la vostra piattaforma ha più controllo e Stripe gestisce la maggior parte della conformità. Gli account Custom danno alla vostra piattaforma pieno controllo sull'esperienza e sull'interfaccia, ma vi assumete una responsabilità di conformità significativamente maggiore. La maggior parte delle build marketplace inizia con Express.
Stripe trattiene i fondi nel saldo di un account connesso fino all'esecuzione di un payout. La pianificazione del payout può essere automatica su cadenza giornaliera, settimanale o mensile, oppure manuale attivata dal codice della vostra piattaforma. Per le piattaforme in cui la tempistica dei payout è una funzionalità di prodotto (ad esempio, un'opzione di pagamento on-demand), i payout manuali sono la scelta giusta. Per la maggior parte dei marketplace, i payout automatici settimanali o mensili sono più semplici e riducono il volume di assistenza.
La riconciliazione è il processo di conferma che ciò che Stripe mostra come pagato corrisponde a ciò che il database mostra come dovuto e ricevuto. A bassi volumi è gestibile manualmente; a qualsiasi scala reale richiede una pipeline. Il materiale grezzo è l'API Balance Transactions di Stripe, che elenca ogni movimento di fondi nel vostro account Stripe con tipo, importo, commissione, importo netto e l'addebito o payout collegato.
Una pipeline di riconciliazione di base: estraete Balance Transactions da Stripe su pianificazione notturna, memorizzate ciascuna nel data warehouse con chiave sull'ID Stripe, unite con i record degli ordini interni e segnalate eventuali discrepanze. Le discrepanze rientrano tipicamente in quattro categorie: addebiti in Stripe senza ordine corrispondente nel database (elaborazione webhook fallita), ordini nel database senza addebito corrispondente in Stripe (payment intent creato ma mai confermato), importi che non corrispondono (errore di conversione valuta o calcolo commissione) e differenze di timing che si risolvono entro pochi giorni.
I payout non sono fatturato. Un payout sposta denaro dal saldo Stripe al conto bancario. Non è una nuova transazione; è il regolamento di transazioni già avvenute. Molte prime implementazioni trattano l'evento payout come riconoscimento del fatturato, il che crea una discrepanza con la contabilità per competenza. Il fatturato va riconosciuto sull'evento charge.succeeded o invoice.paid, non sul payout.
Stripe Radar è il livello di rilevamento frodi integrato in ogni integrazione Stripe. Di default blocca le transazioni che corrispondono a pattern di frode noti, usando il machine learning addestrato sul volume di transazioni di tutti i merchant Stripe. Per la maggior parte delle aziende le regole di default sono un punto di partenza ragionevole. Per aziende con un profilo di frode specifico, le regole Radar personalizzate consentono di aggiungere logica sopra le impostazioni predefinite.
Le regole Radar sono scritte in un semplice linguaggio di espressioni booleane e valutate in ordine. Una regola può bloccare un addebito, consentirlo (sovrascrivendo un blocco di default) o richiedere un'autenticazione 3D Secure. Regole personalizzate comuni: blocco degli addebiti da paesi ad alto rischio non serviti, richiesta di 3DS per addebiti sopra una soglia, blocco di carte che sono apparse in troppe transazioni rifiutate nell'ultima ora e autorizzazione di addebiti da clienti aziendali verificati nel database anche quando il modello di default li segnala come sospetti.
Revisionate mensilmente il tasso di contestazione e il tasso di falsi positivi (addebiti legittimi bloccati da Radar). Un tasso di contestazione superiore allo 0,5 percento è un segnale di inasprire le regole; un volume significativo di reclami da clienti per pagamenti legittimi bloccati è un segnale di allentarle o aggiungere regole di lista bianca per clienti noti.
Il Payment Card Industry Data Security Standard (PCI DSS) definisce i requisiti di sicurezza per qualsiasi sistema che memorizza, elabora o trasmette dati dei titolari di carta. I prodotti di integrazione di Stripe sono progettati specificamente per ridurre al minimo il perimetro PCI, ovvero la superficie dei sistemi che rientra nei requisiti PCI.
Quando utilizzate Payment Element o Checkout, il numero della carta, la scadenza e il CVV vengono inseriti direttamente nell'iframe di Stripe o nella pagina ospitata e non passano mai attraverso i vostri server. Il vostro server vede solo l'ID del PaymentIntent e il token restituito da Stripe. Questo vi qualifica per SAQ A, il questionario di autovalutazione più semplice, che richiede circa 20 controlli invece delle centinaia richieste per SAQ D (archiviazione completa dei dati carta).
Cosa non fare: non registrate dati carta grezzi, non memorizzate il PAN completo nel database, non passate i dettagli della carta attraverso il backend anche brevemente, e non usate Stripe in un modo che faccia transitare i dati dei titolari di carta sulla vostra rete. Questi comportamenti disqualificano da SAQ A. La documentazione di Stripe è chiara sul confine; i pattern di integrazione in questa guida vi mantengono all'interno di esso.
La migrazione da un processore di pagamento esistente a Stripe è fattibile senza interrompere gli abbonamenti attivi, ma richiede una sequenza attenta. I due problemi difficili sono: migrare i metodi di pagamento memorizzati (dati carta che risiedono nel vault del vecchio processore) e migrare gli abbonamenti attivi (addebiti ricorrenti che il vecchio processore esegue su pianificazione).
La migrazione delle carte memorizzate richiede che il processore attuale esporti i dati carta cifrati in un formato che il team di migrazione di Stripe possa importare nel vault. Non tutti i processori lo supportano, e quelli che lo fanno richiedono un accordo formale di trasferimento dati. Stripe ha eseguito questo processo con la maggior parte dei principali processori e ha un processo documentato. L'alternativa è chiedere ai clienti di reinserire la carta, che è più semplice da implementare ma introduce un rischio di churn significativo nella fase di reinserimento.
Migrazione degli abbonamenti: una volta che i dati carta sono in Stripe, create oggetti Customer e Subscription corrispondenti con billing_cycle_anchor impostato per allineare la data di addebito con il vecchio processore, in modo che i clienti non vengano addebitati due volte o meno del dovuto durante la transizione. Eseguite i sistemi nuovo e vecchio in parallelo per almeno un ciclo di fatturazione completo, riconciliate l'output e fate il cutover solo quando i due corrispondono. Impostate una data di cutover, cancellate gli abbonamenti sul vecchio processore il giorno prima del prossimo rinnovo e lasciate che Stripe gestisca il ciclo successivo.
L'audit di migrazione copre: il processore che lasciate, se supporta l'export cifrato delle carte, il numero e la struttura dei piani di abbonamento, la logica di fatturazione non standard (durate di prova personalizzate, crediti a metà ciclo, piani multi-valuta) e la vostra tolleranza al rischio di cutover. Questo plasma il piano di migrazione prima che venga scritto qualsiasi codice.
Questo è il quadro completo dell'implementazione. Quando volete applicarlo al vostro prodotto, il passo successivo è un audit gratuito: guardiamo ciò che avete o ciò che state pianificando, mappiamo le lacune e vi diciamo cosa costruire e in quale ordine.
Un audit gratuito della vostra configurazione, le lacune mappate e un perimetro fisso per chiuderle. Risultati in una settimana.
Richiedi un audit Stripe gratuito