Configurare PayPal Smart Buttons su sito
I PayPal Smart Buttons sono i bottoni dinamici che si adattano automaticamente al cliente: mostrano PayPal, Pay in 3, carte di credito, Apple Pay o Google Pay in base alla geografia e al dispositivo. Sono l'integrazione raccomandata da PayPal per i siti moderni perché riducono fino al 35% l'abbandono carrello rispetto al checkout legacy. In questa guida vediamo come implementarli passo-passo.
Cosa servono Smart Buttons
Smart Buttons sostituiscono il vecchio bottone HTML "Acquista Ora" con un widget JavaScript caricato dall'SDK PayPal. Il widget conosce il cliente (geolocalizzazione IP, lingua browser, dispositivo) e mostra le opzioni di pagamento più convertenti. La sicurezza è gestita lato PayPal: il sito merchant non riceve mai i dati della carta, riducendo gli obblighi PCI-DSS.
Cosa serve per iniziare
Servono tre cose: un'account PayPal Business verificato, un'app REST creata nel Developer Dashboard (developer.paypal.com), il client_id Live e Sandbox associato. L'app può essere creata gratuitamente; otterrai client_id e client_secret usabili sia per le chiamate API server-side sia per l'SDK JavaScript lato client. Tieni il secret rigorosamente lato server, mai esposto nel JS.
Procedura passo-passo
- Accedi a developer.paypal.com e crea una nuova app REST.
- Copia il client_id dell'ambiente Sandbox per il primo test.
- Nel tuo HTML aggiungi lo script SDK: https://www.paypal.com/sdk/js?client-id=TUO_CLIENT_ID¤cy=EUR.
- Inserisci un div contenitore con id, es. paypal-button-container.
- Chiama paypal.Buttons() con le callback createOrder e onApprove.
- In createOrder definisci importo, valuta e descrizione dell'ordine.
- In onApprove gestisci la cattura del pagamento e la conferma al cliente.
- Verifica server-side l'ordine prima di rilasciare la merce.
- Sostituisci il client_id Sandbox con quello Live una volta passati i test.
Esempio minimo di integrazione
Nel body inserisci il container e lo script che inizializza il bottone. La struttura standard prevede createOrder che chiama il tuo backend per generare l'order_id PayPal, onApprove che chiama il tuo backend per fare la cattura tramite REST API. Mai gestire l'importo solo lato client: l'utente potrebbe manomettere il DOM. Il client passa al backend l'id prodotto, il backend calcola il prezzo e crea l'ordine PayPal con quel valore.
Personalizzazione
I bottoni accettano molte opzioni di stile: layout (vertical/horizontal), color (gold/blue/silver/white/black), shape (rect/pill), label (paypal/checkout/buynow/pay), height (25-55 px). Il consiglio è layout=vertical per mobile (più conversione), gold come colore primario (raccomandazione PayPal), shape=rect per coerenza con il resto del sito. Evita personalizzazioni estreme che rendono il bottone irriconoscibile.
Funding sources dinamiche
Smart Buttons mostrano per default tutti i metodi disponibili. Puoi forzare un sottoinsieme con il parametro enable-funding (es. venmo, paylater) o escludere con disable-funding (es. credit, sepa). Per BNPL Pay in 3 italiano basta non disabilitare paylater: il bottone appare automaticamente per ordini idonei (sopra i 30 euro, sotto i 2.000).
Errori comuni e come risolverli
- Mostrare prezzo lato client e fidarsi: il prezzo va sempre calcolato server-side. Mai accettare l'importo dal POST del client.
- Mancata cattura: dopo onApprove devi chiamare orders/capture lato server. Senza cattura il pagamento resta autorizzato ma non addebitato.
- Currency mismatch: l'SDK è caricato in una valuta diversa da quella dell'ordine. Allinea sempre.
- Caricare SDK su HTTPS misto: PayPal richiede HTTPS sul sito merchant. Configura SSL ovunque.
Domande frequenti
D: Smart Buttons funzionano senza account PayPal cliente?
R: Sì, il flusso "Carta di credito" accetta pagamenti da utenti senza account.
D: Posso usare Smart Buttons in pagina carrello e checkout insieme?
R: Sì, ma assicurati che createOrder generi un nuovo ordine ogni volta.
D: Come passo in produzione?
R: Sostituisci il client_id Sandbox con quello Live nell'URL dell'SDK. Niente altro cambia.
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.