Manuale PayPal Pro Italia

1. Introduzione

Il plugin per WooCommerce presentato in questo manuale integra il metodo di pagamento “PayPal Pro” nella sua versione per il circuito italiano (chiamata anche PayPal Pro Hosted Solution o HSS).

In questo post trovate informazioni importanti riguardo la comunicazione tra PayPal e il vostro sito.

Il plugin può essere acquistato in questo sito, all’indirizzo http://www.mauromascia.com/shop/product/woocommerce-paypal-pro-italia-payment-gateway/

Il plugin si occupa di reindirizzare il browser dell’utente verso la pagina di pagamento ospitata nei server sicuri di PayPal in cui l’acquirente potrà inserire le informazioni della propria carta di credito oppure utilizzare il proprio account PayPal o crearne uno (non obbligatorio, contrariamente alla versione Standard inclusa in WooCommerce).

In alternativa al reindirizzamento è possibile utilizzare la modalità iFrame che consiste nel mostrare il form di pagamento in una pagina del vostro sito: si noti che tale form non è ospitato sul vostro server ma è sempre e comunque ospitato nei server sicuri di PayPal.

Al termine della procedura di pagamento l’utente verrà reindirizzato verso il vostro sito (o, se si utilizza la modalità iFrame, su un’altra pagina del vostro sito) e nel frattempo arriverà (in modalità asincrona) la notifica del pagamento (attraverso IPN); il plugin, in base alla risposta ricevuta, si occuperà di aggiornare lo stato dell’ordine:

  • “in lavorazione” o “completato” in caso di risposta positiva (nota: lo stato dell’ordine viene impostato direttamente su “completato” solo ed esclusivamente se il tipo di prodotto è “virtuale” e “scaricabile”)
  • “annullato” o “fallito” in caso di rinuncia al pagamento o di errore nell’inserimento dei dati della carta

2. Configurazione Plugin

La configurazione del plugin è molto semplice e intuitiva: una volta installato il plugin (caricando il file zip dall’interfaccia oppure estraendo il contenuto del file zip e copiandolo all’interno della directory dei plugin di WordPress) è sufficiente recarsi nella pagina di amministrazione relativa ai sistemi di pagamento abilitati su WooCommerce, sotto il tab “Payment Gateways” o “Cassa” (nelle ultime versioni di WooCommerce) e cliccare sul link relativo a PayPal Pro, chiamato “PayPal Pro Italia”.

A questo punto verrà presentato un form di configurazione in cui andranno compilati i campi:

  • Abilita/Disabilita: un checkbox che se ha il segno di spunta (checked) abilita il metodo di pagamento PayPal Pro Italia, altrimenti lo disabilita
  • Titolo: il nome del metodo di pagamento mostrato agli utenti al momento del checkout (default “PayPal Pro”)
  • Descrizione: la descrizione del metodo di pagamento
  • PayPal Email: l’email dell’account PayPal Pro su cui ricevere i pagamenti; può essere inserito indistintamente l’account di test o quello di produzione. Nel primo caso (account di test), verificare che sia presente il segno di spunta su “PayPal sandbox”
  • Prefisso fattura: un eventuale prefisso per gli ordini
  • Payment Action: scegliere se catturare (default) o solo autorizzare i pagamenti.
  • URL di ritorno: la pagina su cui riportare l’utente una volta concluso il pagamento. Se non viene selezionato nulla verrà utilizzata la pagina di “Ordine Ricevuto” di WooCommerce. Si consiglia di non utilizzare la pagina “View Order” perché nel momento in cui il cliente viene rediretto in questa pagina lo stato dell’ordine non è ancora cambiato (le notifiche IPN di PayPal vengono inviate in modalità asincrona quindi separatamente e con un breve ritardo)
  • iFrame: se selezionato visualizza la pagina di pagamento di PayPal in un iFrame altrimenti redirige l’utente in una pagina esterna.
  • iFrame Mobile: se selezionato visualizza l’iFrame ottimizzato per i dispositivi mobile.
  • PayPal sandbox: un checkbox che, se ha il segno di spunta (checked), abilita gli acquisti fittizi verso il sito di test di PayPal (developer.paypal.com) in cui sarà possibile verificare le funzionalità del plugin prima di ufficializzarne la messa in produzione. Deselezionare questa voce per i pagamenti reali.
  • Log di debug: Consente di memorizzare gli eventi di PayPal, come le richieste di IPN, all’interno di un file di log (dentro wp-content/plugins/woocommerce/logs prima della versione 2.1 di WooCommerce oppure in wc-logs nella root del sito dalla versione 2.1 di WooCommerce in poi)

 

2.1 Extra: modificare icona PayPal

Se si desiderasse modificare l’icona di PayPal Pro presente nella pagina di pagamento è possibile utilizzare il filtro wc_gateway_paypal_pro_italia_icon.

Ad esempio:

add_filter( 'wc_gateway_paypal_pro_italia_icon', 'my_wc_gateway_paypal_pro_italia_icon' );
function my_wc_gateway_paypal_pro_italia_icon() {
    return get_template_directory_uri() . '/images/my-ppp.png';
}

dove “my-ppp.png” è un’immagine creata da voi e posizionata nella directory “images” del vostro tema (naturalmente questa posizione è puramente indicativa).

3. Configurazione account business

Qui di seguito verranno mostrate le impostazioni relative ad un account business nell’ambiente di test che, con buona approssimazione, saranno le stesse presenti nell’ambiente reale. Una volta effettuato l’accesso alla pagine dell’utente business:

  • https://www.sandbox.paypal.com

è possibile accedere alla pagina del profilo cliccando sul link “Profilo” in cui, sotto la voce “Impostazione dei Pagamenti sul sito web PayPal Pro”, è presente un link “Impostazioni”. Cliccando su tale link verrà mostrata la pagina delle impostazioni e in particolare siamo interessati alla sotto-sezione “Dati del cliente” mostrata nell’immagine seguente:

fig.2 – Raccolta dati cliente

Qui è possibile mettere un segno di spunta sui dati che verranno mostrati (ed eventualmente renderli modificabili) al cliente al momento del pagamento.

Si consiglia vivamente di non rendere tali dati modificabili in quanto così facendo si creerebbe una possibile incongruenza tra i dati presenti negli ordini di WooCommerce e quelli di PayPal.

Un’altra sotto-sezione di cui potremmo aver bisogno è quella relativa all’impostazione della redirezione dell’utente una volta completato il pagamento, a cui si accede tramite il link “Pagina di conferma del pagamento”:

fig.3 – Impostazioni pagina conferma pagamento

In questa sezione è necessario selezionare la voce “Nella pagina di conferma del mio sito” e più in basso è necessario specificare la URL verso la quale ricevere il cliente e mostrargli un messaggio di conferma dell’acquisto. Alternativamente si può utilizzare la pagina di conferma di PayPal in cui va comunque specificata la corretta URL di ritorno.

Nella sotto-sezione “URL e trasferimento dati” andranno – opzionalmente – specificate le pagine (le URL) per gestire la cancellazione dell’ordine e quella d’errore. Infine, nella sotto-sezione “Ricevuta via email” sarà possibile inserire le informazioni relative all’invio di un’email di conferma al cliente.

 

3.1. Configurazione indirizzo IPN

Infine, ma non per importanza, è necessario impostare la URL su cui ricevere le risposte PayPal sullo stato delle transazioni. Questo meccanismo consentirà a WooCommerce di rimanere in ascolto per le notifiche (inviate da PayPal in modo asincrono) e aggiornare così lo stato degli ordini.

Per attivare le notifiche, è necessario fare click su “Profilo” e poi su “Preferenze per la Notifica immediata di pagamento”

fig.4 – Preferenze per la Notifica immediata di pagamento

Qui va impostato il campo “URL notifica” su:

  • http://www.ilmiosito.com/?wc-api=WC_Gateway_PayPal_Pro_Italia

e il campo “Recapito messaggi” su “Abilitato”.

fig.5 – Abilitazione notifica immediata di pagamento

!!ATTENZIONE!! Questa parte è molto importante: senza questa configurazione non verranno aggiornati gli stati degli ordini!!

Le notifiche IPN possono essere abilitate solo se il sito è raggiungibile dall’esterno (quindi pubblico): per questo, per testare le notifiche IPN in locale, è necessario simulare localmente la notifica che invierebbe PayPal. In questa risposta su stackoverflow ho cercato di spiegare come fare:

http://stackoverflow.com/a/28127306/1992799

 

3.2. Configurazione notifiche con Trasferimento dati di pagamento (PDT)

Questo tipo di notifica è alternativo all’IPN descritto sopra e ha precedenza nel senso che, se sono configurati entrambi, PayPal utilizzerà prima la configurazione di PDT.

Rispetto alla IPN ha il pregio di aggiornare subito la pagina di ringraziamento: questo è importante nei casi in cui l’acquisto di un prodotto comporta il download di un file. Senza questa modalità, usando solo la IPN, l’utente dovrebbe aggiornare la pagina perché la notifica server-to-server che PayPal invia, arriva con un leggero ritardo rispetto all’arrivo dell’utente sul sito.

Detto questo passiamo alla configurazione lato backoffice di PayPal.

Una volta effettuato l’accesso e arrivati sulla pagina del profilo in basso trovate “Impostazioni dei Pagamenti su sito web” e cliccando su “Impostazioni” (sotto “PayPal Pro”) e poi su “Pagina di conferma del pagamento” avrete:

paypal-pro-italia-pdt-impostazioni

 

dovrete inserire la pagina dell’ordine ricevuto di WooCommerce relativa all’indirizzo del vostro sito:

http://www.ilmiosito.com/checkout/order-received

Mi raccomando: per PDT è importante che sia “/checkout/order-received”. Infatti il plugin sarà in ascolto su questa URL e quando PayPal riporterà l’utente su questa pagina aggiungerà il parametro “tx”, che rappresenta il numero della transazione; grazie a questo parametro è possibile chiedere a PayPal (grazie alle credenziali API) i dati dell’ordine e in base a quelli riportare l’utente verso la pagina corretta di ordine ricevuto.

A questo punto torniamo alla pagina del profilo e facciamo click su “Preferenze” sotto “Pagamenti su sito web e Pagamento express”. Qui potrebbe essere necessario attivare il ritorno automatico, impostandolo nuovamente su http://www.ilmiosito.com/checkout/order-received

Infine attivare Trasferimento dati di pagamento:

paypal-pro-italia-pdt-attiva-pdt

 

Qui prendete nota del “Token identità” perché ci servirà in seguito.

Le altre informazioni da recuperare sono quelle relative alle credenziali API: tornati al profilo selezioniamo “Richiedi credenziali API” che trovate sotto “Informazioni sul conto”.

paypal-pro-italia-pdt-informazioni-conto

La pagina mostrerà due opzioni:

paypal-pro-italia-pdt-impostazioni-api

Cliccando sul link “Visualizza firma API” della seconda opzione verrà mostrata la pagina:

paypal-pro-italia-pdt-impostazioni-api-credenziali

 

Qui è necessario cliccare sui vari “Mostra”. Ogni voce dovrà essere copiata e incollata nella pagina di configurazione del plugin:

paypal-pro-italia-pdt-attiva-pdt-plugin-configurazione

 

Copiate-incollate anche il “Token identità” che avete messo da parte prima.

Per testare la correttezza della configurazione potete disabilitare IPN e verificare che veniate riportati sulla corretta pagina di ordine ricevuto e che lo stato dell’ordine sia “completato” (o “in lavorazione”).

Se avete un ambiente locale in cui fare le prove, potete utilizzare – ad esempio – ngrok per avere un nome pubblico. In questo modo PayPal potrà inviarvi le notifiche e redirezionarvi correttamente al sito.

 

4. Note su Sandbox

Ecco alcuni link utili per comprendere la procedura di creazione degli account di test:

Aggiungo solo alcune note che non ho trovato in giro per il web e che potrebbe essere d’aiuto nella creazione di nuovi account di test.

Una volta creato l’account business sarà necessario verificare l’account e per questo, una volta raggiunta la pagina degli utenti:

bisogna cliccare sul link “Notifications” presente sotto il nome dell’account business appena creato. Questo aprirà un box in cui sono presenti le notifiche e tra queste dovrebbe essercene una in cui è presente un link da copiare e incollare sulla barra degli indirizzi del browser per rendere l’account, a tutti gli effetti, attivo.

Con il servizio Sandbox API di PayPal, tutti i partecipanti di ciascuna transazione (utenti di prova) sono fittizi e non dispongono di indirizzi email effettivi. Al fine di svolgere la prova, Sandbox è stato integrato con un sistema email indipendente. Ciascun sviluppatore API di PayPal dispone di una casella di posta in arrivo dove vengono spediti tutti i messaggi email indirizzati agli utenti di prova. Ciascun sviluppatore visualizza solo le email inviate agli utenti di prova collegati a uno sviluppatore specifico. Le email inviate a tutti gli utenti di prova collegati ad uno sviluppatore specifico saranno visualizzate nella stessa casella di posta in arrivo.

Si veda il link: https://www.paypal.com/it/cgi-bin/webscr?cmd=p/sell/ipn-test-outside per maggiori informazioni.

A questo punto, cliccando sul link “Sandbox site” (a fianco a “Notifications”), si arriverà al sito clone di quello reale in cui sarà necessario effettuare il login con l’account business precedentemente creato e richiedere le credenziali API.

Per far questo andare su “Profilo” e cliccare sul link “Richiedi credenziali API” o seguire il seguente link diretto:

https://paypalmanager.sandbox.paypal.com/reskinning.do?reskinExternalUrlServiceKey=paypal&reskinSection=profile&reskinRelativeUrl=cgi-bin/webscr?cmd=_profile-api-access

Nota: i link presenti in questa pagina potrebbero subire variazioni.

 

5. Identificare gli ordini pagati con un account PayPal o con carta

In seguito ad un ordine nella risposta restituita da PayPal tra i vari parametri è presente “payer_status“, che vale “verified” quando l’utente paga con un account PayPal valido, oppure “unverified” quando l’utente paga con carta.

Quindi per accedere a tale informazione si può aggiungere un filtro:


add_action( 'valid-paypal-pro-ita-ipn-request', 'my_valid_paypal_pro_ita_ipn_request' );
function my_valid_paypal_pro_ita_ipn_request( $posted ) {
	if (isset($posted['payer_status'])) {
		if ($posted['payer_status'] == 'unverified') {
			// Codice per il pagamento con carta, es.
			wp_mail( 'test.email@email.it', 'Pagamento con Carta', 'Pagamento con Carta' );
		}
		else {
			// Codice per il pagamento con paypal
			wp_mail( 'test.email@email.it', 'Pagamento con PayPal', 'Pagamento con PayPal' );
		}
	}
	
	// Oppure
	if (isset($posted['payer_status']) && !empty($posted['custom']) && !empty($posted['invoice'])) {

		$pp = new WC_Gateway_PayPal_Pro_Italia_IPN_Handler();
		$order = $pp->get_paypal_order($posted['custom'], $posted['invoice']);

		update_post_meta($order->id , '_paypalpro_payer_verified', ($posted['payer_status'] == 'verified'?true:false));
	}
}

Per poter utilizzare il form dei commenti di Disqus è necessario accettare l'utilizzo dei cookie di terze parti.