Configurare pagamenti futuri
L’API Setup Intents ti consente di salvare i dati di pagamento del cliente senza un pagamento iniziale. Questa funzionalità è utile se vuoi configurare i pagamenti dei clienti quando li attivi e addebitare gli importi in un secondo momento, quando sono offline.
Utilizza questa integrazione per configurare i pagamenti ricorrenti o per creare pagamenti una tantum con un importo finale determinato in un secondo momento, spesso dopo che il cliente riceve il servizio.
Conformità
You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer’s payment details. These requirements generally apply if you want to save your customer’s payment method for future use, such as displaying a customer’s payment method to them in the checkout flow for a future purchase or charging them when they’re not actively using your website or app. Add terms to your website or app that state how you plan to save payment method details and allow customers to opt in.
When you save a payment method, you can only use it for the specific usage you have included in your terms. To charge a payment method when a customer is offline and save it as an option for future purchases, make sure that you explicitly collect consent from the customer for this specific use. For example, include a “Save my payment method for future use” checkbox to collect consent.
To charge them when they’re offline, make sure your terms include the following:
- Il consenso del cliente a disporre un pagamento o una serie di pagamenti per suo conto per determinate transazioni.
- La tempistica e la frequenza dei pagamenti previste (ad esempio, se gli addebiti sono per rate programmate, pagamenti di abbonamenti o ricariche non programmate).
- Il modo in cui determini l’importo del pagamento.
- I tuoi termini di cancellazione, se la modalità di pagamento è per un servizio in abbonamento.
Assicurati di conservare una copia scritta del consenso fornito dal cliente relativamente a questi termini.
Nota
Se devi utilizzare la conferma manuale lato server o la tua integrazione richiede l’indicazione separata della modalità di pagamento, consulta la nostra guida alternativa.
Configurare StripeLato server
Innanzitutto crea un account Stripe o accedi.
Utilizza le nostre librerie ufficiali per accedere all’API Stripe dalla tua applicazione:
Abilitare modalità di pagamento
Visualizza le impostazioni delle modalità di pagamento e abilita le modalità di pagamento che vuoi accettare. Per creare un SetupIntent è necessario che sia abilitata almeno una modalità di pagamento.
Per impostazione predefinita, Stripe abilita le carte e altre modalità di pagamento tra le più utilizzate per aiutarti a raggiungere più clienti. Detto ciò, ti consigliamo di attivare ulteriori modalità pertinenti per la tua azienda e i tuoi clienti. Per ulteriori informazioni sul supporto di prodotti e modalità di pagamento, consulta la pagina Opzioni di integrazione delle modalità di pagamento; per le commissioni consulta la nostra pagina delle tariffe.
Creare un oggetto CustomerLato server
Per configurare una modalità di pagamento per pagamenti futuri, è necessario associarla a un Customer. Crea un oggetto Customer
quando il cliente crea un account con la tua azienda. Gli oggetti Customer
permettono di riutilizzare le modalità di pagamento e di monitorare più pagamenti.
Creare un SetupIntentLato server
Nota
Se vuoi presentare Payment Element senza prima creare un SetupIntent, consulta la sezione Raccogliere i dati di pagamento prima di creare un intento.
Un SetupIntent è un oggetto che rappresenta l’intenzione di configurare una modalità di pagamento per i pagamenti futuri di un cliente. Le modalità di pagamento mostrate ai clienti in fase di completamento della transazione sono incluse anche nel SetupIntent. Puoi consentire a Stripe di acquisire automaticamente le modalità di pagamento dalle impostazioni della Dashboard oppure puoi elencarle manualmente.
A meno che la tua integrazione non richieda un’opzione con codice per offrire le modalità di pagamento, Stripe consiglia l’opzione automatica. Questo perché Stripe valuta le limitazioni delle modalità di pagamento, la valuta e altri parametri per determinare l’elenco delle modalità di pagamento accettate. Le modalità di pagamento che migliorano la conversione e che sono più pertinenti alla valuta e alla posizione del cliente hanno la priorità. Le modalità di pagamento con priorità più bassa sono nascoste sotto un menu extra.
Recuperare la chiave privata client
L’oggetto SetupIntent contiene una chiave privata client, che il lato client usa per completare la procedura di pagamento in modo sicuro. Per specificare la chiave privata sul lato client, puoi utilizzare approcci diversi.
Utilizzo di Radar
Quando viene salvata la modalità di pagamento di un cliente senza un pagamento iniziale, Radar non agisce sul SetupIntent per impostazione predefinita. Se vuoi attivare questa opzione per impostazione predefinita, vai su Impostazioni Radar e attiva Usa Radar per le modalità di pagamento salvate per uso futuro.
Acquisire i dati di pagamentoLato client
A questo punto è tutto pronto per acquisire i dati di pagamento sul client con Payment Element. Payment Element è un componente di interfaccia utente preintegrato che semplifica l’acquisizione dei dati di pagamento per varie modalità di pagamento.
Payment Element contiene un iframe che invia a Stripe informazioni sul pagamento in modo sicuro tramite una connessione HTTPS. Affinché l’integrazione funzioni, l’indirizzo della pagina di pagamento deve iniziare con https://
anziché con http://
. Puoi testare l’integrazione senza usare questo metodo, ma ricorda di abilitare la connessione HTTPS quando sarà tutto pronto per accettare i pagamenti in modalità live.
Il Payment Element visualizza un modulo dinamico che consente al cliente di scegliere una modalità di pagamento. Per ogni modalità di pagamento, il modulo richiede automaticamente al cliente di inserire tutti i dati di pagamento necessari.
Personalizza l’aspetto
Personalizza Payment Element in base al design del tuo sito specificando l’oggetto appearance in options
al momento della creazione del provider Elements
.
Richiedi il token esercente di Apple Pay
Se accetti pagamenti con Apple Pay, ti consigliamo di configurare l’interfaccia di Apple Pay in modo che restituisca un token esercente che consente di abilitare le transazioni avviate dall’esercente (MIT). Richiedi il tipo di token esercente pertinente nel componente Payment Element. L’esempio che segue mostra una richiesta di token esercente per i pagamenti dilazionati.
const paymentElement = elements.create('payment', { applePay: { deferredPaymentRequest: { paymentDescription: 'My deferred payment', managementURL: 'https://example.com/billing', deferredBilling: { amount: 2500, label: 'Deferred Fee', deferredPaymentDate: new Date('2024-01-05') }, } }, // Other options });
Configura valuta
Quando utilizzi SetupIntents con automatic_payment_methods, se specifichi la valuta in options
durante la creazione del provider Elements
, ci saranno effetti sulle modalità di pagamento visualizzate da Payment Element. Payment Element visualizza le modalità di pagamento abilitate nella Dashboard di Stripe che supportano la valuta fornita. Per ulteriori informazioni, consulta le Opzioni di integrazione delle modalità di pagamento.
Raccogli indirizzi
Per impostazione predefinita, Payment Element raccoglie solo i dettagli relativi all’indirizzo di fatturazione necessari. Per acquisire l’indirizzo di fatturazione completo di un cliente (ad esempio, per calcolare l’imposta su beni e servizi digitali) o l’indirizzo di spedizione, utilizza Address Element.
Inviare i dati di pagamento a StripeLato client
Usa stripe.confirmSetup per completare la configurazione con i dati raccolti da Payment Element. Fornisci a questa funzione un return_url in modo che Stripe possa reindirizzare l’utente dopo il completamento della configurazione. L’utente può essere dapprima reindirizzato su un sito intermedio, come una pagina di autorizzazione bancaria, e poi al return_url
.
Se il cliente salva i dati della carta, li reindirizziamo immediatamente al return_url
quando la configurazione ha esito positivo. Se vuoi impedire il reindirizzamento per i pagamenti con carta, puoi impostare il reindirizzamento su if_required
. In questo modo vengono reindirizzati solo i clienti che utilizzano modalità di pagamento basate sul reindirizzamento.
Assicurati che il return_url
corrisponda a una pagina del tuo sito web che fornisce lo stato del SetupIntent
. Quando Stripe reindirizza il cliente al return_url
, fornisce i seguenti parametri di ricerca dell’URL per verificare lo stato. Quando specifichi il return_url
, puoi anche aggiungere i tuoi parametri di ricerca che saranno mantenuti durante la procedura di reindirizzamento.
Parametro | Descrizione |
---|---|
setup_intent | Identificativo univoco per il SetupIntent |
setup_intent_client_secret | La chiave privata client dell’oggetto SetupIntent . |
Puoi usare stripe.retrieveSetupIntent per recuperare il SetupIntent usando il parametro di ricerca setup_intent_client_secret
. Se la conferma del SetupIntent ha esito positivo, l’ID PaymentMethod
risultante (in result.setupIntent.payment_method
) viene salvato per il Customer
fornito.
Attenzione
Se disponi di strumenti che tracciano la sessione del browser del cliente, potresti aver bisogno di aggiungere il dominio stripe.com
all’elenco di esclusione dei referrer. I reindirizzamenti fanno sì che alcuni strumenti creino nuove sessioni, il che ti impedisce di tracciare la sessione completa.
Addebita in un secondo momento l'importo sulla modalità di pagamento salvataLato server
Conformità
Quando salvi i dati di pagamento di un cliente, sei responsabile della conformità a tutte le leggi, le normative e le regole del circuito applicabili. Quando presenti al cliente finale modalità di pagamento utilizzate in passato per acquisti futuri, accertati di elencare le modalità di pagamento per le quali hai raccolto il consenso a salvare i dettagli della modalità di pagamento per gli usi futuri specifici. Per differenziare le modalità di pagamento legate ai clienti che possono o non possono essere presentate al cliente finale come modalità di pagamento salvate per acquisti futuri, utilizza il parametro allow_redisplay.
Quando hai la certezza di voler addebitare l’importo al cliente al di fuori della sessione, utilizza gli ID Customer e PaymentMethod per creare un PaymentIntent. Per trovare una modalità di pagamento per l’addebito, elenca le modalità di pagamento associate al tuo cliente. Questo esempio elenca le carte, ma puoi aggiungere qualsiasi altro tipo di modalità supportato.
Quando hai gli ID Customer e PaymentMethod, crea un PaymentIntent con l’importo e la valuta del pagamento. Per effettuare il pagamento al di fuori della sessione, imposta alcuni altri parametri:
- Imposta off_session su
true
per indicare che il cliente non si trova nel tuo flusso di pagamento durante il tentativo di pagamento e non può soddisfare una richiesta di autenticazione fatta da un partner, come un emittente di carte, una banca o un altro istituto di pagamento. Se, durante il flusso di pagamento, un partner richiede l’autenticazione, Stripe richiede le esenzioni utilizzando le informazioni del cliente presenti in una precedente transazione all’interno della sessione. Se le condizioni per l’esenzione non sono soddisfatte, PaymentIntent potrebbe generare un errore. - Imposta su
true
il valore della proprietà confirm del PaymentIntent. Di conseguenza, viene generata una conferma immediata al momento della creazione del PaymentIntent. - Imposta payment_method sull’ID del PaymentMethod e customer sull’ID del cliente.
Quando un tentativo di pagamento non va a buon fine, anche la richiesta non riesce. Viene visualizzato un codice di stato HTTP 402 e lo stato del PaymentIntent è requires_payment_method. Devi chiedere al cliente di tornare nell’applicazione per completare il pagamento (ad esempio inviando un’email o una notifica in-app).
Verifica il codice dell’errore generato dalla libreria Stripe API. Se il pagamento non è riuscito a causa di un codice di rifiuto authentication_required, utilizza la chiave privata PaymentIntent rifiutata con confirmPayment per consentire al cliente di autenticare il pagamento.
const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const {error} = await stripe.confirmPayment({ // The client secret of the PaymentIntent clientSecret, confirmParams: { return_url: 'https://example.com/order/123/complete', }, }); if (error) { // This point will only be reached if there is an immediate error when // confirming the payment. Show error to your customer (for example, payment // details incomplete) const messageContainer = document.querySelector('#error-message'); messageContainer.textContent = error.message; } else { // Your customer will be redirected to your `return_url`. For some payment // methods like iDEAL, your customer will be redirected to an intermediate // site first to authorize the payment, then redirected to the `return_url`. } });
Nota
Il completamento della fase stripe.confirmPayment
può richiedere diversi secondi. Nel frattempo, disabilita il nuovo invio del modulo e mostra un indicatore di attesa, ad esempio una rotellina che gira. Se viene restituito un errore, mostralo al cliente, riabilita il modulo e nascondi l’indicatore di attesa. Se il cliente deve eseguire operazioni aggiuntive per completare il pagamento, ad esempio l’autenticazione, Stripe.js guida l’utente nella procedura.
Se il pagamento non va a buon fine per altri motivi, ad esempio fondi insufficienti sulla carta, indirizza il cliente a una pagina di pagamento dove inserire una nuova modalità di pagamento. Puoi riutilizzare l’oggetto PaymentIntent esistente per tentare di nuovo il pagamento con i dati della nuova modalità di pagamento.
Testa l'integrazione
Usa i dettagli di pagamento e la pagina di reindirizzamento di test per verificare se il funzionamento dell’integrazione è quello atteso. Per visualizzare i dettagli relativi a ciascuna modalità di pagamento, fai clic sulle seguenti schede:
Eseguire il test dell’addebito con un PaymentMethod con addebito SEPA salvato
La conferma del SetupIntent usando iDEAL, Bancontact o Sofort genera un PaymentMethod riutilizzabile con addebito diretto SEPA. L’addebito diretto SEPA è una modalità di pagamento con notifica differita che transita da uno stato intermedio processing
prima di passare a uno stato succeeded
o requires_payment_method
alcuni giorni dopo.
Comunicare ai clienti l'utilizzo di Stripe
Stripe raccoglie informazioni sulle interazioni dei clienti con Elements per fornirti servizi, prevenire le frodi e migliorare i propri servizi. Ad esempio, utilizza cookie e indirizzi IP per identificare quali Elements sono stati visualizzati da un cliente durante una singola sessione di pagamento. Sei responsabile della comunicazione e della raccolta di tutti i diritti e i consensi necessari affinché Stripe utilizzi i dati in questi modi. Per ulteriori informazioni, visita il nostro Centro privacy.