PayPal Express Checkout: implementazione
L'Express Checkout è il flusso di pagamento PayPal in cui il cliente clicca un bottone, viene reindirizzato a paypal.com per autenticarsi e tornare al sito merchant per il completamento dell'ordine. È il flusso di base storico di PayPal, oggi affiancato dai Smart Buttons che lo modernizzano. In questa guida vediamo l'implementazione completa, sia in chiave classica sia con SDK moderno.
Flusso utente
Quattro passaggi. Il cliente clicca il bottone PayPal in pagina (carrello, pagina prodotto o checkout). Viene reindirizzato a paypal.com con un token che identifica l'ordine. Si autentica con email/password PayPal e approva il pagamento. Viene reindirizzato al sito merchant alla "return URL" con il token. Il sito merchant completa la chiamata di cattura e mostra conferma ordine. Il vantaggio è il "frictionless": il cliente non inserisce carta, è già loggato in PayPal nella maggior parte dei casi.
Architettura server-side
Servono tre endpoint nel tuo backend. POST /paypal/create-order: il frontend chiama questo quando il cliente clicca PayPal. Il backend crea l'ordine via POST /v2/checkout/orders e torna l'order_id al frontend. POST /paypal/capture-order/{id}: dopo l'approvazione del cliente, il frontend chiama questo. Il backend cattura via POST /v2/checkout/orders/{id}/capture e finalizza. POST /paypal/webhook: riceve notifiche asincrone (refund, dispute) e aggiorna il database.
Procedura passo-passo
- Crea un'app REST nel Developer Dashboard, copia client_id/secret.
- Implementa l'endpoint backend /create-order che chiama PayPal Orders API.
- Imposta intent=CAPTURE, purchase_units con amount e description.
- Inserisci nello HTML del sito uno script con SDK PayPal: https://www.paypal.com/sdk/js?client-id=...¤cy=EUR.
- Aggiungi un div container e inizializza paypal.Buttons().
- In createOrder chiama il tuo backend /create-order e torna l'order_id.
- In onApprove chiama il backend /capture-order/{id} per finalizzare.
- Implementa onCancel per registrare l'abbandono.
- Implementa onError per loggare errori e mostrare messaggi utente.
- Configura webhook per refund e dispute asincroni.
- Testa in Sandbox e poi passa in Live.
Return URL e Cancel URL
Nelle vecchie integrazioni Express Checkout legacy si configuravano return_url (dove tornare dopo approvazione) e cancel_url (se il cliente annulla). Con i Smart Buttons moderni non servono più: il flusso resta nella stessa pagina e le callback gestiscono i due esiti. Se mantieni un flusso legacy con redirect server-to-server, configura le URL nel payload create-order sotto experience_context.
Differenza Express Checkout vs Smart Buttons
Express Checkout legacy: redirect completo a paypal.com, return URL, post-back con token. Smart Buttons: pop-up modale o overlay, esperienza in-page, callback JavaScript. Smart Buttons converte meglio (-30% abbandono carrello) perché il cliente non lascia visivamente il sito merchant. Per i nuovi progetti scegli sempre Smart Buttons; tieni Express legacy solo se hai integrazioni esistenti.
Considerazioni di sicurezza
Mai fidarsi del client per gli importi: il backend deve calcolare il totale e usarlo nella createOrder. Verifica server-side che l'amount nella createOrder sia coerente con il carrello del cliente nel tuo database. Implementa CSRF protection sull'endpoint /create-order. Usa rate limiting per evitare abuse (1000 ordini/minuto da stesso IP è sospetto). Logga tutte le transazioni con request_id per audit.
Errori comuni e come risolverli
- Cattura non eseguita: il pagamento resta authorized ma non addebitato. Esegui sempre capture in onApprove.
- Importo manomesso lato client: vulnerabilità di pricing. Calcola sempre server-side.
- Mancato handling di onCancel: il cliente annulla e tu non lo sai. Logga per analizzare il funnel.
- SDK caricato troppo tardi: il bottone appare con ritardo. Carica lo script in head con async.
Domande frequenti
D: Express Checkout sarà deprecato?
R: Il flusso a redirect classico resta ma è raccomandato passare a Smart Buttons.
D: Funziona con guest checkout?
R: Sì, il cliente può pagare con carta anche senza account PayPal.
D: Quanto pesa l'SDK?
R: Circa 80-120 KB compressi gzip. Carica solo dove serve.
Consigli operativi e best practice
Per consolidare quanto visto nei paragrafi precedenti tieni a mente alcuni accorgimenti pratici che fanno la differenza nel quotidiano. Documenta sempre ogni passaggio della configurazione in un registro interno aziendale: serve sia per il team sia in caso di audit fiscale o di richiesta di chiarimenti da parte di PayPal. Conserva una copia delle ricevute, delle email transazionali e degli screenshot dei pannelli di amministrazione per almeno dieci anni, come richiesto dalla normativa civilistica italiana.
Pianifica una revisione trimestrale della tua integrazione PayPal: verifica le commissioni applicate, controlla i tassi di contestazione, leggi gli avvisi nel Centro Risoluzioni e aggiorna eventuali plugin o SDK obsoleti. Le aziende che fanno questo controllo regolare riducono del 40-60% gli incidenti operativi rispetto a chi gestisce PayPal in modo reattivo. Coinvolgi anche il team di customer service: spesso sono loro i primi a notare pattern di richieste che possono indicare problemi nascosti nel flusso di pagamento.
Infine, abituati a monitorare i tempi di risposta nelle dispute e nei reclami: PayPal premia i merchant che rispondono entro 24-48 ore con score reputazionali migliori, che si traducono in minori riserve, commissioni più favorevoli al raggiungimento dei volumi e un'esperienza più fluida in caso di controlli antifrode. La gestione proattiva è sempre meno costosa di quella reattiva, in PayPal come nel resto del business online.
Hai bisogno di aiuto?
Se vuoi integrare PayPal nel tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.