Evadere ordini con Checkout
Dopo aver effettuato l’integrazione di Stripe Checkout o creato uno Stripe Payment Link per portare i tuoi clienti alla pagina del modulo di pagamento, dovrai comunicare al cliente che potrai evadere l’ordine a pagamento avvenuto.
In questa guida, imparerai a:
- Ricevere una notifica dell’evento quando un cliente effettua un pagamento.
- Gestire l’evento.
- Utilizzare la CLI di Stripe per eseguire rapidamente il test del nuovo gestore eventi.
- (Facoltativo) Gestire ulteriori modalità di pagamento.
- Attivare il gestore eventi nell’ambiente di produzione.
Installare la CLI di Stripe
La CLI di Stripe è il modo più veloce per sviluppare e verificare localmente i webhook.
Innanzitutto, segui la guida all’installazione della CLI di Stripe.
Una volta installata la CLI di Stripe e completata la procedura di accesso, puoi passare al passaggio successivo.
Creare un gestore eventiLato server
In questa sezione scopri come creare un gestore eventi in modo tale che Stripe possa inviarti un evento checkout.session.completed
quando il cliente completa il pagamento.
Innanzitutto, crea un nuovo percorso per il gestore eventi. Inizia a stampare l’evento ricevuto. Potrai verificare il corretto funzionamento della consegna nel passaggio successivo:
Test
Avvia il tuo server (ad esempio su localhost:4242
). Poi configura la CLI di Stripe in modo tale che inoltri gli eventi sul tuo server locale per consentirti di verificare il gestore eventi localmente.
stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)
Poi accedi a Checkout come cliente:
- Fai clic sul pulsante di pagamento, che probabilmente hai configurato nella Guida all’accettazione di un pagamento
- Compila il modulo di pagamento con i dati di test:
- Inserisci
4242 4242 4242 4242
come numero della carta - Inserisci una data di scadenza futura per la carta
- Inserisci un numero di 3 cifre per il CVV
- Inserisci qualsiasi CAP di addebito (
90210
)
- Inserisci
- Fai clic sul pulsante Paga.
Dovresti visualizzare:
checkout.session.completed
nell’outputstripe listen
- Una stampa rendiconto dei registri degli eventi del tuo server con l’evento
checkout.session.completed
Dopo aver verificato la consegna dell’evento, rendi questa procedura più sicura in modo tale da ricevere solo gli eventi provenienti da Stripe.
Verificare gli eventi provenienti da Stripe
Chiunque può inviare dati al gestore eventi. Prima di considerare l’evento attentidibile e di elaborarlo, verifica sempre che provenga da Stripe. La libreria ufficiale di Stripe prevede un’assistenza integrata per verificare gli eventi webhook con cui aggiornare il tuo gestore eventi:
Test
Segui il flusso della procedura di testing illustrato nel passaggio precedente. Dovresti comunque visualizzare l’evento checkout.session.completed
stampato correttamente.
Adesso prova a inviare una richiesta non firmata all’endpoint:
curl -X POST \ -H "Content-Type: application/json" \ --data '{ "fake": "unsigned request" }' \ -is http://localhost:4242/webhook HTTP/1.1 400 Bad Request ... more headers
Dovresti ricevere un messaggio di errore 400 Bad Request
perché hai cercato di inviare una richiesta non firmata all’endpoint.
Una volta completata la configurazione di base del gestore eventi, puoi passare all’evasione dell’ordine.
Evadere l'ordineLato server
Gestisci l’evento checkout.session.completed
per evadere l’ordine. A seconda delle modalità di pagamento accettate (ad esempio carte di credito o wallet mobili), potresti dover gestire alcuni eventi aggiuntivi. Questo evento include l’oggetto Checkout Session, che contiene dettagli sul cliente e sul suo pagamento. Quando si gestisce questo evento, si potrebbe anche prendere in considerazione:
- Salva una copia dell’ordine nel tuo database.
- Invia al cliente una ricevuta via email.
- Esegui la riconciliazione delle voci riga e della quantità acquistata dal cliente se utilizzi
line_item.adjustable_quantity
. Se la sessione di Checkout ha molte voci riga, puoi ordinarle con line_items.
Gestire il comportamento di reindirizzamento
Puoi configurare Checkout per reindirizzare i tuoi clienti dopo aver ricevuto eventi webhook. Checkout gestisce questi reindirizzamenti attivati da webhook in modo leggermente diverso a seconda che tu utilizzi il modulo incorporato o una pagina in hosting su Stripe.
Pagina in hosting su Stripe | L’endpoint del webhook reindirizza il cliente al success_url dopo che confermi la ricezione dell’evento. Negli scenari in cui l’endpoint non funziona o l’evento non viene confermato in modo appropriato, il gestore reindirizza il cliente al success_url 10 secondi dopo un pagamento andato a buon fine. |
Modulo incorporato | L’endpoint del webhook reindirizza immediatamente il cliente al return_url . Non devi confermare di avere ricevuto l’evento. |
Test
Verifica che stripe listen
sia ancora in esecuzione. Accedi a Checkout come utente di test, esattamente come nei passaggi precedenti. Il gestore eventi dovrebbe ricevere un evento checkout.session.completed
e dovresti averlo gestito correttamente.
Gestire le modalità di pagamento con notifica differitaLato server
Attenzione
Questo passaggio è necessario solo se prevedi di utilizzare le seguenti modalità di pagamento: addebito diretto Bacs, bonifici bancari, Boleto, addebiti preautorizzati per il Canada, Konbini, OXXO, addebito diretto SEPA, SOFORT o addebito diretto ACH.
Quando ricevi pagamenti effettuati con una modalità di pagamento con notifica differita, i fondi non sono disponibili immediatamente. L’elaborazione di questi fondi potrebbe richiedere più giorni, quindi dovresti ritardare l’evasione dell’ordine fino a quando i fondi non sono disponibili sul tuo account. Quando il pagamento va a buon fine, lo stato del PaymentIntent corrispondente passa da processing
a succeeded
.
Dovrai gestire i seguenti eventi di Checkout:
Nome evento | Descrizione | Passaggi successivi |
---|---|---|
checkout.session.completed | Il cliente ha autorizzato il pagamento con addebito inviando il modulo di Checkout. | Attendi l’esito positivo o negativo del pagamento. |
checkout.session.async_payment_succeeded | Il pagamento del cliente è andato a buon fine. | Evadi l’ordine delle merci o dei servizi acquistati. |
checkout.session.async_payment_failed | Il pagamento è stato rifiutato o non è andato a buon fine per qualche altro motivo. | Contatta il cliente via email e chiedigli di effettuare un nuovo ordine. |
Tutti questi eventi includono l’oggetto Checkout Session.
Aggiorna il gestore eventi per evadere l’ordine:
Test
Verifica che stripe listen
sia ancora in esecuzione. Accedi a Checkout come utente di test, come hai fatto nei passaggi precedenti. Il gestore eventi dovrebbe ricevere un evento checkout.session.completed
e dovresti averlo gestito correttamente.
Una volta completati questi passaggi, puoi passare in modalità live nell’ambiente di produzione non appena decidi di farlo.
Passare in modalità live nell'ambiente di produzione
Una volta distribuito l’endpoint del gestore eventi nell’ambiente di produzione, devi registrare l’URL in modalità live su Stripe. Segui questa guida per registrare un webhook.