Ogni buon sito di che vende prodotti, servizi o abbonamenti on-line utilizza un provider per consentire il pagamento on-line del bene venduto. Tra i più utilizzati al mondo ci sono PayPal a Stripe.
In questo articolo ti spiegherò come configurare correttamente PayPal per accettare pagamenti dal tuo sito web.
Account Personale o Business?
Prima di procedere bisogna fare una distinzione tra i diversi tipi di account PayPal, poiché ciascuno di essi ha diverse condizioni contrattuali e relative limitazioni d’uso.
Secondo la documentazione ufficiale, puoi avere due tipi di conto: Personale e Business.
L’account Personale è riservato all’uso individuale. È adatto all’utente che usa PayPal per acquistare o vendere come privato.
Quello Business invece è adatto all’uso da parte di aziende. Può essere intestato a una ragione sociale e consente l’accesso multiutente (fino a 20 utenti).
Entrambi consentono di gestire le API ma non tutte le funzionalità che andrò a descrivere in questo articolo sono abilitate per l’account Personale.
Chiaramente se stai vendendo dei prodotti, dei servizi o prevedi di ricevere dei pagamenti ricorrenti tramite PayPal, si presuppone che ci sia un’attività imprenditoriale alle spalle, pertanto il conto più indicato è quello Business.
La configurazione
Una volta che avrai creato il tuo conto PayPal come account Business vai all’indirizzo https://developer.paypal.com/developer/applications se non sei ancora autenticato ti verrà chiesto di fornire le tue credenziali di accesso.
Vedrai quindi un pannello di controllo dove gestire tutte le tue App (le indico semplicemente come App, ma mi riferisco alle REST API apps).
Come noterai, In testa a questa sezione c’è la possibilità di passare dall’ambiente Sandbox all’ambiente Live. Tale funzionalità non è disponibile però per gli account Personali.
Sandbox o Live?
Sandbox è una modalità utile agli sviluppatori per effettuare l’integrazione ed il test delle funzionalità implementate su un sito web che deve accettare pagamenti tramite PayPal.
Questa modalità ti consente di creare degli utenti finti permettendoti di simulare pagamenti andati a buon fine e pagamenti falliti per le più disparate situazioni (es. carta di credito scaduta, codice CVV errato, numero carta non valido, credito insufficiente, ecc.), pagamenti tramite carte di credito, pagamenti tramite conto corrente bancario, pagamenti tramite credito PayPal, senza però intaccare il tuo reale conto PayPal e senza utilizzare la tua reale carta di credito.
Live è la modalità per quando il pagamento deve essere messo in produzione. In questo modo l’utente che acquista il servizio, trasferirà realmente il compenso sul tuo conto PayPal.
Quanto descriverò in questo articolo può essere fatto sia in ambiente Sandbox che in ambiente Live.
Suggerisco a tutti coloro che si cimenteranno nelle successive operazioni di procedere prima in ambiente Sandbox, testare le varie configurazioni e successivamente replicare gli stessi passaggi nell’ambiente Live.
Creare un app di test PayPal
La prima cosa da fare per creare un’app di test PayPal è cliccare sul pulsante “Create App“
Il processo di creazione di una nuova App PayPal è stato estremamente semplificato nel tempo, in passato erano richieste molte più informazioni, ma il dipartimento tecnico di PayPal ha letteralmente ridotto all’osso il processo di configurazione semplificando enormemente l’operazione di creazione.
Semplificare però non sempre coincide con limitare il funzionamento.
App Name
Definito il nome di nostro gradimento dell’app nel campo “App Name” (suggerisco di usare un nome che sia facilmente riconducibile allo scopo. Solitamente io uso il nome del cliente e il servizio a cui è associato l’account, es. “Mio Cliente – example.com“). Quello che scriverai non è comunque importante ai fini della configurazione in sè, ma è fondamentale se gestisci diverse App tramite il tuo account business e vuoi essere sempre in grado di abbinare un’app ad un cliente.
App Type
Qui la prima vera differenza nella scelta del tipo di app. Molte persone spesso tendono a scegliere erroneamente la seconda opzione (Platform) perché leggono nella descrizione di approfondimento la magica parola e-commerce platform.
In realtà l’opzione Merchant è rivolta a chi ha intenzione di vendere beni, prodotti o servizi attraverso il proprio sito, proponendosi come unico beneficiario dell’incasso da parte di PayPal. L’opzione Platform è rivolta invece a quei soggetti che si pongono come intermediari e che come tali, ridistribuiscono una percentuale degli incassi al reale venditore.
Per dirla in maniera ancora più semplice: se il tuo sito mette a disposizione di altri soggetti una vetrina di vendita dei loro prodotti, sui quali tu percepirai compenso, allora l’opzione giusta per te è Platform. Nei casi in cui tu vendi dei beni che acquisti attraverso altri canali o stai vendendo un bene di tua proprietà e non devi alcuna percentuale sul venduto ad altri beneficiari, allora la scelta da adottare ricade su Merchant.
Business Account
Questa opzione ti permette di scegliere qual’è l’account Business al quale associare il servizio. Solitamente l’impostazione predefinita è quella giusta nella maggior parte dei casi.
Le chiavi
Dopo che avrai confermato la creazione dell’App, ti saranno presentate le chiavi per l’integrazione dell’app che avrai appena creato con il tuo sistema di vendite on-line.
Tieni traccia dei 3 valori che riceverai in questa sezione perchè ti torneranno utili in fase di integrazione delle API Rest con il tuo sito.
Mi riferisco nello specifico ai 3 valori Sandbox account (o Business Account, se il processo di creazione delle chiavi è svolto in contesto Live), Client ID e Secret.
Sempre con il principio della semplificazione del processo di registrazione, nella maggior parte dei casi è sufficiente lasciare le altre impostazioni intatte. Ci sono però quelle eccezioni per le quali hai bisogno di una maggiore personalizzazione dell’integrazione.
App Settings, Cosa può fare l’app?
PayPal offre un elevato livello di personalizzazione del servizio pur garantendo una semplicità e completezza nella configurazione.
Di default un’app appena creata può accettare pagamenti, generare fatture a fronte di un pagamento gestire contenziosi con i clienti, consentire l’autenticazione al tuo servizio tramite l’autenticazione di PayPal ed eseguire una ricerca nella cronologia delle operazioni PayPal. Analizziamo una per una queste funzionalità.
Return URL
Una volta che il cliente avrà provveduto al pagamento, sarà dirottato verso uno specifico URL del tuo sito web di vendita on-line. È possibile che questo URL coincida con l’indirizzo di provenienza al quale PayPal fornirà una serie di dettagli sulla transazione appena avvenuta, ma potrebbe essere differente. Il mio suggerimento personale è che, a prescindere da quello che sia l’URL di destinazione, che sia sempre esplicitamente indicato nelle APP Settings. Ciò ti permetterà di aumentare la sicurezza nel processo di pagamento.
App feature options – Funzionalità dell’app
Cosa può fare il tuo sito Web con le API di PayPal? Potrebbe fare di tutto. Ma ti serve davvero fare tutto?
Anche in questo caso è importante attivare solo i servizi di cui realmente il sito web ha bisogno, quindi,
- se abbiamo bisogno di gestire i pagamenti, attiviamo “Accept payments“
- se vogliamo gestire la fatturazione attraverso PayPal, attiveremo “Invoicing“
e così via…
Ridurre al minimo essenziale le autorizzazioni dell’app ti aiuterà a mantenere in generale alto il livello di sicurezza della tua App e mantenere traccia delle funzionalità di cui hai realmente bisogno da PayPal.
Conoscere di cosa hai bisogno, sempre, ti aiuta a valutare eventuali costi di migrazione verso altro servizio o, nel caso in cui, PayPal dovesse introdurre dei costi per specifiche feature, essere consapevole di quali dei tuoi servizi ne fanno uso e a quali costi di gestione vai incontro.
Webhooks – se succede qualcosa su PayPal il tuo sistema viene avvisato
Una tra le feature che ritengo più interessanti è la gestione dei Webhooks.
Per chi si è già occupato di integrazione di sistemi di terze parti probabilmente già sa cos’è un webhook. Per tutti gli altri parte lo spiegone…
Webhook (estratto da Wikipedia)
Un Webhook (in italiano letteralmente: “gancio del web“) nella programmazione web è un metodo per aumentare o alterare il comportamento di una pagina web, o di un’applicazione web, con chiamate di ritorno (callback) personalizzate. Queste chiamate di ritorno o callback possono essere mantenute, modificate e gestite da utenti di terze parti e chi le sviluppa non fa necessariamente parte del sito o applicazione d’origine.
Ok secondo me può essere spiegata in modo ancora più facile.
Quando su PayPal un utente esegue un’azione che riguarda il servizio che ha acquistato sul tuo sito, PayPal si preoccuperà di richiamare un URL del tuo sito, attraverso una chiamata in POST, fornendo tutti i dettagli sull’evento.
Di default l’app appena creata non ha webhook e magari non ne ha bisogno ma, PayPal mette a disposizione numerosissimi eventi che permettono una notifica al sito web per ogni occasione.
In conclusione: cosa devo ricordarmi?
Come avrebbe detto un mio vecchio professore, sarebbe importante ricordare tutto. Ma il limite della mente umana è che si ha una memoria selettiva, alcune cose le ricordiamo altre le riteniamo inconsciamente o consapevolmente superfue.
Quindi ricordati che per integrare PayPal nel tuo sito web:
- dopo aver configurato l’app su PayPal in Sandbox,
- ti sarà necessario prender nota delle tue chiavi applicative
- effettuare tutti i necessari test in ambiente di sviluppo e
- replicare la configurazione in ambiente Live.
- Imposta le chiavi applicative di produzione nel tuo ambiente
- Sei pronto ed operativo.
Proprio per il punto 5, se utilizzi un sistema basato su file .env (per esempio Laravel), potrai impostare nel tuo .env.local le chiavi generate per la modalità Sandbox di PayPal e nel file .env di produzione mettere quelle generate per il Live.
Ecco di solito il mio file .env che mi permette di passare da ambiente Sandbox ad ambiente Live in modo estremamente agevole.
PAYPAL_MODE=sandbox
PAYPAL_SANDBOX_CLIENT_ID="my_sandbox_client_id"
PAYPAL_SANDBOX_CLIENT_SECRET="my_sandbox_app_secret"
PAYPAL_SANDBOX_APP_ID="my_sandbox_app_id"
PAYPAL_LIVE_CLIENT_ID="my_live_client_id"
PAYPAL_LIVE_CLIENT_SECRET="my_live_app_secret"
PAYPAL_PAYMENT_ACTION=Sale
PAYPAL_CURRENCY=EUR
PAYPAL_NOTIFY_URL=
PAYPAL_LOCALE=it_IT
PAYPAL_VALIDATE_SSL=trueVuoi sapere come integrare PayPal nel tuo sito web? Ogni CMS ha i suoi moduli/plugin per l’integrazione, esiste l’SDK ufficiale di PayPal ed esistono tanti tuorial in giro per la rete che ti spiegano come farlo nei linguaggi più disparati.
Ma, in cambio di una birra ti potrò raccontare come ho integrato la gestione dei pagamenti PayPal in Laravel.
Se invece cerchi qualcuno in grado di aiutarti nel processo di integrazione di un sistema di pagamento sul tuo sito, nel tuo e-commerce o nella tua App, puoi contattare i professionisti di Axio Studio, ti forniranno un valido supporto e la massima competenza.
Foto di copertina a cura di rupixen.com on Unsplash