Payment Data Transfer ( PDT )

Come scrive PayPal: "Il Trasferimento dei dati del pagamento ( PDT, Payment Data Transfer ) è un metodo sicuro per il recupero dei dettagli relativi a una transazione PayPal che puoi rendere visibili al tuo cliente. Viene utilizzato congiuntamente ai Pagamenti su sito web, in modo che quando torna nel tuo sito web dopo avere effettuato il pagamento nel sito PayPal, il cliente è in grado di visualizzare immediatamente un messaggio di conferma con i dettagli della transazione". Le informazioni che il server HTTPS di PayPal invia al vostro server HTTP sono molto simili alle informazioni che avete ricevuto con la pagina di ritorno classica, ma il meccanismo PDT è leggermente più complesso della pagina di ritorno, poichè prevede un passaggio intermedio, tra la fine della transazione e l'invio di tutti i dati, relativi alla transazione stessa. Da questo punto di vista, PDT è molto più vicino al meccanismo IPN ( Instant Payment Notification ). Inoltre, visto che sia la transazione PDT, sia la transazione IPN, prevedono una chiamata ad una URL "https", sarà necessario che il vostro server abbia installato un qualche supporto ai protocolli SSL ( Secure Sockets Layer ) o TLS ( Transport Layer Security TLS ).

L'ambiente virtuale SANDBOX

Potrete eseguire i test delle impostazioni che vedremo nei paragrafi successivi, utilizzando l'ambiente virtuale Sandbox di PayPal, che abbiamo visto nel secondo articolo di questa guida. Ricordate sempre che le form HTML vanno inviate a due indirizzi internet ( URL ) differenti, a seconda che stiate utilizzando l'ambiente virtuale Sandbox, oppure che vi troviate ad operare in ambiente reale PayPal. Per Sandbox, utilizzate sempre l'indirizzo:

	https://www.sandbox.paypal.com/cgi-bin/webscr

Quando, invece, vi trovate in PayPal, utilizzate sempre l'indirizzo:

	https://www.paypal.com/cgi-bin/webscr

Ricordate, inoltre, che il campo, contenuto nella vostra form di invio:

	business

indica al server HTTPS di PayPal il nome dell'account sul quale versare i soldi, frutto della transazione. L'identificativo dell'account virtuale Sandbox è diverso dall'identificativo dell'account reale PayPal, naturalmente.

Impostare PDT dal vostro account PayPal

Entrate nel vostro account PayPal e seguite il percorso:

	Strumenti vendita
	Preferenze per i pagamenti su sito web
		Aggiorna	

In questa pagina, due sono le opzioni da attivare:

• Funzionalità Ritorno automatico per i pagamenti su sito web: spuntare su "Attivato". Nella casella sottostante, immettere l'indirizzo internet ( URL ) del programma, installato sul vostro server, che PayPal userà come pagina di ritorno PDT. Possiamo ancora usare il file che abbiamo utilizzato nell'articolo precedente: "grazie.php" o "grazie.pl", per esempio:

  
  http://www.punto-bit.com/grazie.php
  http://www.punto-bit.com/cgi-bin/grazie.pl	
  
  

  Attenzione, però: sia il file PHP, sia il file Perl, per funzionare con PDT, devono essere modificati! Tra poco, capiremo perchè e come.

• Trasferimento dei dati del pagamento (opzionale): spuntare su "Attivato". Questo è il bottone che attiva il vero e proprio metodo PayPal PDT o Payment Data Transfer. Come spiega PayPal, proprio nella pagina in cui vi trovate: "PayPal registrerà un messaggio di controllo relativo alla transazione in oggetto; per ricevere i dettagli di pagamento associati alla transazione, devi semplicemente rispondere al messaggio e rispedirlo a PayPal. Sulla base dello script CGI con cui è stata scritta la pagina associata all'URL di ritorno, potrai inserire in maniera dinamica i dettagli della transazione e confermare al tuo cliente che il pagamento è stato eseguito. Per utilizzare la funzionalità di Trasferimento dei dati del pagamento, devi essere in grado di supportare questo sistema di notifica". Queste poche righe spiegano perchè i file PHP e Perl che abbiamo preparato, nell'articolo precedente, per la pagina di ritorno, con PDT non funzionano. Con PDT, il server HTTPS di PayPal, a fine transazione, invia al vostro server HTTP "un messaggio di controllo relativo alla transazione in oggetto" ( e non tutti i dati ). Per ricevere tutti i dati, il nostro programma dovrà inviare al server HTTPS di PayPal un messaggio di risposta.

Una volta impostate queste opzioni, premete il bottone "Salva". Nella nuova pagina che si aprirà, leggerete la conferma delle avvenute modifiche. Se rientrate nella pagina "Preferenze per i pagamenti su sito web", scoprirete che nella sezione "Trasferimento dei dati del pagamento (opzionale)", che ora è attivo, viene riportata una stringa alfanumerica ( token ), che rappresenta un codice identificativo del vostro account, per le transazioni PDT. Per esempio:

Messaggio di controllo dell'identità
817lWxbtmGGG1kW872k_F9qI5RWsCirOmjQJykh5eamqCihMaGMQTbwew78	

Questa stringa è una delle stringhe che il vostro programma PDT dovrà inviare al server HTTPS di PayPal, per poter ricevere tutti i dati relativi alla transazione appena avvenuta. Vediamo le fasi di una transazione finanziaria, con Payment Data Transfer ( PDT ) impostato:

1. Il vostro utente preme il bottone "Paga adesso", da una delle pagine web del vostro sito.

2. Il vostro utente viene inviato al server HTTPS di PayPal.

3. Il server HTTPS di PayPal guida il vostro utente, durante il processo di pagamento online.

4. Conclusa la transazione, il server HTTPS di PayPal invia un messaggo e-mail al vostro utente ed uno al venditore ( voi ) per informarlo dell'avvenuta transazione.

5. Immediatamente dopo, il server HTTPS di PayPal chiama automaticamente ( senza aspettare alcun input, da parte del vostro utente ) la vostra pagina di ritorno PDT, quella inserita nel campo "Funzionalità Ritorno automatico per i pagamenti su sito web". Questa chiamata viene effettuata, dal server HTTPS di PayPal, utilizzando il metodo HTTP GET, "attaccando" alla URL della vostra pagina PDT una coppia chiave/valore:

   
   tx=identificativo_della_transazione
   
   

6. Il programma contenuto nella vostra pagina di ritorno PDT ( "grazie.php" o "grazie.pl" ) riceve il valore di questo campo tx, chiama il server HTTPS di PayPal, utilizzando il metodo POST, ed invia, al server HTTPS di PayPal tre coppie chiave/valore:

   
   cmd=_notify-synch
   tx=identificativo_della_transazione
   at=identificativo_PDT_vostro_account
   
   

7. Se il server HTTPS verifica la correttezza dei dati inviati dal vostro server HTTP, reinvia, al programma contenuto nella pagina di ritorno PDT, installato sul vostro server HTTP, tutti i dati relativi alla transazione appena conclusa. Questi ultimi dati possono essere inviati, dal server HTTPS di PayPal, anche in forma criptata, sempre se, durante la prima fase della connessione, chiamata "handshake", il vostro server HTTP ha informato il server PayPal di avere installato un adeguato supporto per i protocolli SSL.

Il protocollo HTTPS

Abbiamo detto che il server HTTPS, durante la transazione PDT, chiede che i dati scambiati tra il vostro server HTTP ed il server HTTPS di PayPal vengano trasmessi in forma criptata. Chi effettua la codifica dei dati è proprio il protocollo di trasmissione HTTPS ( Secure HyperText Transfer Protocol ). Il protocollo HTTPS non sostituisce il protocollo HTTP, il protocollo normalmente usato in tutte le trasmissioni internet ( TCP ), ma lo affianca: mentre HTTP si occupa della trasmissione stessa dei dati, HTTPS si preoccupa che questa trasmissione avvenga in un ambiente sicuro. I protocolli utilizzati per l'implementazione della sicurezza nelle transazioni HTTP sono protocolli di crittografia/autenticazione come il Secure Sockets Layer ( SSL ) o il Transport Layer Security ( TLS ), tanto è vero che, nel caso di TLS, si parla di HTTP Over TLS. In realtà, TLS non è altro che una versione di SSL. SSL, originariamente, fu sviluppato da Netscape. Quando IETF ( Internet Engineering Task Force ) decise di adottare SSL come standard universale, decise di cambiarne il nome in TLS. La versione 1.0 di TLS è equivalente alla versione 3.1 di SSL. Per capire, anche se solo sommariamente, quali compiti esegua TLS e di quanti altri protocolli si serva, è sufficiente leggere la spiegazione che ne viene data nella RFC ufficiale( RFC 5246 ): "Il protocollo TLS garantisce la riservatezza delle comunicazioni inviate via internet, permettendo alle applicazioni client/server di comunicare fra loro, evitando che le loro comunicazioni siano intercettate, alterate o contraffatte. Il protocollo è composto da due strati ( livelli ):

1. il protocollo TLS Record

2. il protocollo TLS Handshake

Il protocollo TLS Record si occupa della sicurezza della connessione, garantendo due fondamentali proprietà di una connessione sicura:

1. la connessione è una connessione privata. TLS Record codifica i dati utilizzando una crittografia simmetrica ( quale AES, RC4, etc. ). Le chiavi per questa crittografia simmetrica vengono generate per ciascuna connessione e sono basate su una chiave segreta, negoziata da un altro protocollo ( per esempio, il protocollo TLS Handshake ).

2. La connessione è affidabile. Il trasporto del messaggio, infatti, include la verifica dell'integrità del messaggio, attuata tramite un keyed MAC ( Message Authentication Code ). Le funzioni di hash ( per esempio, SHA-1, etc. ) vengono utilizzate per il calcolo del MAC.

Il protocollo TLS Record viene utilizzato per incapsulare altri protocolli di livello superiore. Uno di questi protocolli incapsulati, il protocollo TLS Handshake, permette sia al server che al client:

• di autenticarsi vicendevolmente. L'identità delle singole macchine può essere autenticata utilizzando una cifratura asimmetrica, o a chiave pubblica ( RSA, DSS, etc. ). Questa procedura di autenticazione sarebbe opzionale, ma, generalmente, viene richiesta per almeno una delle macchine coinvolte.

• di negoziare un algoritmo di cifratura e le chiavi di cifratura, prima che il protocollo a livello applicazione trasmetta o riceva il suo primo byte di dati".

Il concetto importante da sottolineare è che una transazione SSL implica una prima fase, handshake ( negoziazione ), durante la quale le due macchine stabiliscono quali protocolli di cifratura utilizzare nel corso della successiva trasmissione dei dati veri e propri. I dati, le nostre stringhe POST, verranno, poi, inviati, criptati o no, utilizzando i normali header HTTP. Questo significa che i programmi che utilizzerete per effettuare la connessione al server HTTPS dovranno, quanto meno, essere in grado di gestire la prima fase, o handshake, di una transazione SSL. Se poi il vostro server ha installato un pieno supporto ai protocolli SSL, tutta la transazione verrà completata eseguendo una cifratura ed una decifratura dei dati. In caso contrario, visto che PayPal non richiede necessariamente, pur caldeggiandola calorosamente, la cifratura dei dati, la transazione potrà anche essere conclusa in chiaro. Per maggiori dettagli sulla fase di negoziazione ( o handshake ) SSL, leggete questo interessante articolo di Antonio Altana.

Creazione del bottone "Paga adesso"

Ora che avete impostato la pagina di ritorno PDT nel vostro account PayPal, rientrate nel vostro account e tornate alla pagina di creazione del bottone "Paga adesso", per creare un nuovo bottone.

	Profilo
	Strumenti Vendita
		Pulsanti PayPal
		Aggiorna
		Crea nuovo pulsante

Inserite i dati del vostro articolo in vendita:

• Scegli un tipo di pulsante: Paga adesso

• Nome oggetto: Il mio primo articolo

• ID oggetto: 1000

• Prezzo: 10 ( EUR )

• Usa il tuo ID conto commerciante sicuro

Ricordatevi di deselezionare la voce "Salva il pulsante su PayPal", nella scheda "Passaggio 2. Gestisci le giacenze di magazzino, i profitti e le perdite (opzionale)". Quindi, premete il bottone "Crea pulsante". A questo punto, vedrete il codice HTML della form, in forma criptata ( è la modalità di default di PayPal, nel caso in cui venga escluso il salvataggio del codice sul server Paypal ), ma vedrete anche un link, subito sopra il codice, con scritto: "Rimuovi protezione codice". Cliccate e vedrete apparire il codice HTML in chiaro. Copiate quel codice su una pagina HTML del vostro sito. Il codice HTML della vostra form dovrebbe essere il seguente:

#######################
## Questa è una riga unica

<form
action="https://www.sandbox.paypal.com/cgi-bin/webscr"
method="post">

## Questa è una riga unica
#######################

<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="8KM75GS8NBPFJ">
<input type="hidden" name="lc" value="IT">
<input type="hidden" name="item_name" value="Il mio primo articolo">
<input type="hidden" name="item_number" value="1000">
<input type="hidden" name="amount" value="10.00">
<input type="hidden" name="currency_code" value="EUR">
<input type="hidden" name="button_subtype" value="services">
<input type="hidden" name="no_note" value="0">

#######################
## Questa è una riga unica

<input type="hidden" name="cn"
	value="Aggiungi istruzioni speciali per il venditore:">

## Questa è una riga unica
#######################

<input type="hidden" name="no_shipping" value="2">

#######################
## Questa è una riga unica

<input type="hidden" name="bn"
	value="PP-BuyNowBF:btn_buynowCC_LG.gif:NonHosted">

## Questa è una riga unica
#######################

e dovrebbe comprendere gli stessi campi che avete utilizzato nel bottone "Paga adesso" del primo articolo, quando non avevate impostato alcuna pagina di ritorno. Questo significa che, con PDT, il server HTTPS di PayPal preleva le informazioni relative alla pagina di ritorno PDT direttamente dal vostro account PayPal. Prima di premere questo nuovo bottone "Paga adesso", dovrete creare la pagina di ritorno PDT. Iniziamo con PHP.

Il programma in PHP

<html>
<head>
<title>Esito della transazione</title>
</head>

<body>

<?php

$to = "https://www.sandbox.paypal.com/cgi-bin/webscr";
$token = "817lWxbtmGGG1kW872k_F9qI5RWsCirOmjQJykh5eamqCihMaGMQTbwew78";
$cmd = "_notify-synch";
$arVar;
$posted;

if($_GET['tx'])
  {

  $conn = curl_init($to);
  curl_setopt($conn, CURLOPT_HEADER, 0);
  curl_setopt($conn, CURLOPT_NOBODY, 0);
  curl_setopt($conn, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($conn, CURLOPT_USERAGENT, "Mozilla/5.0");
  curl_setopt($conn, CURLOPT_FOLLOWLOCATION, 1);
  curl_setopt($conn, CURLOPT_SSL_VERIFYPEER, 1);
  curl_setopt($conn, CURLOPT_POST, 1);
  curl_setopt($conn, CURLOPT_POSTFIELDS, array(
		'cmd'=>$cmd,
		'tx'=>$_GET['tx'],
		'at'=>$token));

  if(!$page = curl_exec($conn))
	{
	echo curl_error($conn);
	curl_close($conn);
	}
  else
    {

    $arVar = split("\n", $page);

    if($arVar[0] == "FAIL")
	{ echo "Errore nell'acquisizione dei dati"; }
    else if ($arVar[0] == "SUCCESS")
	{

	for($a=1; $a<count($arVar); $a++)
	  {

	  list($key, $val) = split("=", $arVar[$a]);
	  $val = preg_replace('/\+/', ' ', $val);

	  #########################
	  ## Questa è una riga unica 

	  $val = preg_replace('/%([\da-f][\da-f])/ei',
		"chr(hexdec('\\1'))", $val);

	  ## Questa è una riga unica 
	  #########################

	  $posted[$key]= $val;

	  }

	}

      curl_close($conn);

      if($posted['payment_status'] == "Completed")
        { echo "<p>Grazie per il tuo acquisto<br><br>"; }
      else
        { echo "<p>Ci dispiace, transazione interrotta<br><br>"; }

      foreach($posted as $key=>$val)
        { echo $key." ".$val."<br>"; }

    }

  }

?>

</body>
</html>

Salvate questo file con il nome "grazie.php" ed installatelo sul vostro server. Ora, premete il bottone "Paga adesso" appena salvato e verificate cosa accadrà al vostro utente, durante il processo di pagamento online. Vediamo, ora, il codice del vostro programma "grazie.php" più da vicino. Ricordate che il codice di programmazione, in un file PHP è sempre compreso tra le due TAG di apertura e chiusura:

<?php
	codice PHP
?>

Nelle prime righe, vengono dichiarate alcune variabili, che verranno utilizzate in seguito. La variabile:

	$posted;

è un array associativo ( sarà evidente solo più tardi ) che conterrà l'elenco delle variabili inviate dal server HTTPS di PayPal. E' l'equivalente dell'array associativo $_POST riempito da PHP. In questo caso, come vedremo, sarete voi a doverlo costruire e riempire, estraendo i dati dalla risposta inviata dal server HTTPS di PayPal. La variabile:

	$arVar;

è un array semplice, una lista, che utilizzerete come contenitore temporaneo dei dati inviati dal server HTTPS di PayPal. La variabile:

	$to = "https://www.sandbox.paypal.com/cgi-bin/webscr";

è l'indirizzo del server PayPal. Qui, ho inserito l'indirizzo dell'ambiente virtuale Sandbox: nel caso doveste installare questo programma per lavorare in ambiente reale PayPal, ricordatevi di modificare il valore di questa variabile in:

	$to = "https://www.paypal.com/cgi-bin/webscr";

La variabile:

	$token

contiene l'identificativo PDT del vostro account PayPal, l'identificativo che trovate all'interno del vostro account PayPal:

	Strumenti vendita
	Preferenze per i pagamenti su sito web
		Aggiorna
	Trasferimento dei dati del pagamento (opzionale)

In questo momento, quell'identificativo è l'identificativo PDT del vostro account virtuale Sandbox. Nel caso doveste installare questo programma per lavorare in ambiente reale PayPal, ricordatevi di modificare il valore di questa variabile, prelevandolo dal vostro account PayPal reale. La variabile:

	$cmd = "_notify-synch";

contiene il tipo di transazione che chiedete al server HTTPS di PayPal di eseguire. Questa stessa variabile era già contenuta nella form HTML che avete salvato nella vostra pagina web, ma con un valore differente. Nella vostra form HTML, il valore di questa variabile era:

	cmd = "_xclick"

che significa ( basta verificarlo sulla pagina di PayPal Variabili HTML per Pagamenti su sito web ): "Il pulsante selezionato è un pulsante Paga adesso". Il vostro utente, quindi, premendo il bottone "Paga adesso", ha avvisato il server HTTPS di PayPal che il bottone premuto è un bottone "Paga adesso". Il server HTTPS di PayPal, una volta completato il pagamento online, ha scoperto che, nel vostro account PayPal, avete impostato una pagina di ritorno PDT. Quindi, il server HTTPS di PayPal ha chiamato il programma "grazie.php", installato sul vostro server HTTP, inviandogli una variabile di verifica, chiamata tx e restando in attesa di un'ulteriore risposta di conferma, da parte del vostro server HTTP. E' questa ulteriore risposta di conferma che deve contenere la variabile:

	cmd = "_notify-synch"

che dice al server HTTPS di PayPal che questo è un messaggio di sincronizzazione, tra il vostro server HTTP ed il server HTTPS di PayPal, affinchè quest'ultimo invii al primo tutti i dati relativi alla transazione appena conclusa. Se la variabile $token contiene l'identificativo PDT del vostro account PayPal, la variabile tx, inviata al vostro server HTTP dal server HTTPS di PayPal, contiene l'identificativo PDT di questa singola transazione. Se il server HTTPS di PayPal, per un qualsiasi motivo, non inviasse alcuna variabile tx, la transazione PDT non potrebbe avvenire e verrebbe interrotta ( stiamo parlando solo della transazione PDT, poichè, è bene ricordarlo, il pagamento online è, ormai, già concluso ). Quindi, la prima operazione che deve eseguire il vostro programma "grazie.php" è verificare l'esistenza della variabile tx:

	if($_GET['tx'])

Se questa variabile tx esiste, il vostro programma eseguirà tutte le altre operazioni previste, altrimenti non verrà eseguito più nulla. Se tx esiste, il vostro programma deve:

1. chiamare il server HTTPS di PayPal

2. inviare al server HTTPS di PayPal i seguenti campi ( o variabili ):

   
   cmd=_notify-synch
   tx=$_GET['tx']
   at=$token
   
   

3. ricevere la risposta del server HTTPS di PayPal, contenente tutti i dati relativi alla transazione appena conclusa.

4. estrarre, dalla risposta del server HTTPS di PayPal, tutte le variabili relative alla transazione e salvarle in una qualche variabile locale ( un array associativo ), per poterle utilizzare.

Un'ultima importante annotazione sulla variabile tx: il server HTTPS di PayPal invia questa variabile utilizzando il metodo HTTP GET, vale a dire "aggiungendo" questa variabile alla URL ( indirizzo internet ) del vostro programma "grazie.php". Quindi, l'indirizzo che il vostro utente vede nella barra degli indirizzi del browser comprende la variabile tx:

	grazie.php?tx=ID_transazione

Se, in fase di test, doveste provare più volte la transazione PDT, non fatelo facendo un semplice RELOAD della pagina: in questo caso, infatti, il vostro programma utilizzerebbe più volte lo stesso ID di transazione, rispedendolo più volte al server HTTPS di PayPal. PayPal avverte che, nel caso il server HTTPS di PayPal ricevesse più volte lo stesso ID di transazione, PayPal sospenderebbe, in via precauzionale, l'identificativo PDT del vostro account PayPal ( $token ). Se aveste bisogno, quindi, di eseguire la stessa transazione più volte, fatelo tornando al vostro bottone "Paga adesso". A questo punto, possiamo passare alla connessione con il server HTTPS di PayPal:

	$conn = curl_init($to);

curl, o cURL ( Client URL ), è una libreria PHP che effettua la connessione al server. cURL supporta diversi protocolli, tra i quali HTTP e HTTPS. Le librerie SSL utilizzate da cURL sono: OpenSSL, GnuTLS, yassl, NSS, PolarSSL, axTLS o qssl. Nonostante cURL supporti SSL, è ancora possibile che, nell'eseguire il programma "grazie.php", voi riceviate un errore del tipo:

	SSL is disabled, https: not supported

Questo può avvenire per una varietà di motivi, ma significa, sostanzialmente, che l'istanza di cURL che state utilizzando è stata creata senza alcun supporto per SSL. In questo caso, non ci sono soluzioni alternative. In questa riga di codice, non avete ancora effettuato alcuna connessione, ma avete semplicemente aperto una nuova istanza di cURL, salvandola nella variabile $conn ( che rappresenta un FILEHANDLE, cioè un canale dedicato al flusso dei dati generati da questa connessione ). Prima di effettuare la connessione, dovete dare a cURL alcune istruzioni, impostando alcune opzioni per la vostra connessione $conn. Per impostare un'opzione, cURL mette a vostra disposizione la funzione:

	curl_setopt($conn, OPZIONE, VALORE)

L'elenco delle opzioni disponibili e dei valori ad esse assegnabili, lo trovate alla pagina curl_setopt della guida PHP. Vediamo le opzioni inserite nel vostro programma "grazie.php":

• CURLOPT_HEADER - Dice a cURL se volete ricevere, oltre ai dati ( BODY ) inviati al vostro server HTTP dal server HTTPS di PayPal, anche gli HEADER HTTP. Gli HEADER HTTP, o intestazioni, sono una serie di informazioni "di servizio", che un server invia sempre al server di destinazione. Nel nostro caso, dovreste ricevere una serie di header simili ai seguenti:

  
  HTTP/1.1 100 Continue
  
  HTTP/1.1 200 OK
  Date: Sun, 20 Nov 2011 15:10:54 GMT
  Server: Apache
  X-Frame-Options: SAMEORIGIN
  Set-Cookie: c9MW...
  Set-Cookie: -1ILhd...
  Set-Cookie: cookie_check=yes; expires=Wed, 17-Nov-2021 15:10:55 GMT
  Set-Cookie: navcmd=_notify-synch 
  Set-Cookie: navlns=0.0; expires=Sat, 15-Nov-2031 15:10:55 GMT
  Set-Cookie: Apache=10.72.109.11.1321801854190751
  X-Cnection: close
  Transfer-Encoding: chunked
  Content-Type: text/html; charset=UTF-8
  
  

  Come potete vedere, si tratta di informazioni che non sono utili al nostro programma "grazie.php". Potrebbero essere utili solo nel caso in cui, in fase di debug, voleste conoscere la risposta esatta inviata dal server HTTPS. I valori che l'opzione CURLOPT_HEADER può assumere sono solo due:

  • 0 ( zero ): non voglio ricevere gli HEADER HTTP.

  • 1 ( uno ): voglio ricevere gli HEADER HTTP.

  Il vostro programma "grazie.php" ha questa variabile impostata a zero: non vuole ricevere gli header HTTP. Ricordate che, nel caso aveste mai bisogno di impostare questa variabile a 1, dovreste anche modificare il codice successivo, esattamente nel punto in cui il vostro programma estrae i dati ricevuti dal server HTTPS di PayPal, visto che, in questo caso, la stringa ricevuta dal server HTTPS sarebbe più lunga.

• CURLOPT_NOBODY - Dice a cURL se volete ricevere il BODY del messaggio. Il BODY del messaggio è quella parte del messaggio che contiene le variabili PayPal, relative alla transazione appena conclusa. Quindi, ovviamente, il vostro programma "grazie.php" deve ricevere il BODY. I valori che l'opzione CURLOPT_NOBODY può assumere sono solo due:

  • 0 ( zero ): voglio ricevere il BODY del messaggio.

  • 1 ( uno ): non voglio ricevere il BODY del messaggio.

• CURLOPT_RETURNTRANSFER - Dice a cURL se volete memorizzare la stringa di risposta del server HTTPS di PayPal in una variabile ( valore 1 ), oppure se preferite che venga spedita direttamente sul monitor ( valore 0 ).

• CURLOPT_USERAGENT - Dice a cURL quale identificativo inviare al server HTTPS di PayPal come User Agent ( come nome di programma ). Se non specificato, cURL non invierebbe alcun nome. Nelle sessioni SSL, non inviare un nome di User Agent può compromettere l'esito della sessione stessa.

• CURLOPT_FOLLOWLOCATION - Dice a cURL se volete che riesegua la connessione automaticamente, nel caso in cui il server HTTPS di PayPal inviasse al vostro server HTTP l'avviso ( l'avviso viene inserito tra gli HEADER HTTP ) che l'indirizzo di destinazione è cambiato. Difficilmente PayPal deciderà di cambiare la URL del suo server HTTPS, ma, per dormire tranquilli, è meglio impostare questa opzione a 1 ( si, rieffettua la connessione automaticamente ). Se impostaste questa variabile a 0 ( zero ), il giorno in cui PayPal decidesse di modificare la URL del suo server HTTPS ( anche solo momentaneamente ), il vostro programma "grazie.php" smetterebbe di funzionare.

• CURLOPT_POST - Questa variabile è da impostare a 1 ( uno ) quando la trasmissione che stiamo inizializzando prevede l'invio di dati, utilizzando il metodo HTTP POST, proprio come nel nostro caso. I dati che siamo in procinto di inviare al server HTTPS di PayPal dovranno essere memorizzati nell'opzione seguente:

• CURLOPT_POSTFIELDS - Questa opzione contiene i dati, sotto forma di coppie chiave/valore, che stiamo inviando al server HTTPS di PayPal.

• CURLOPT_SSL_VERIFYPEER - Per capire il significato di questa opzione, è utile leggere l'interessante articolo di Peter Chng, Using cURL in PHP to access HTTPS ( SSL/TLS ) protected sites. Sintetizziamo: la nostra transazione HTTP è una transazione protetta ( HTTPS ). Le transazioni HTTPS hanno bisogno del supporto SSL o TLS. I protocolli SSL e TLS offrono due livelli di protezione:

  1. Certificano che il server HTTPS che stiamo contattando sia realmente il server che vorremmo contattare ( site authentication ).

  2. Eseguono una cifratura dei dati che stiamo inviando al server di destinazione ( il server HTTPS di PayPal ).

  Per eseguire l'autenticazione del server, il server HTTPS di PayPal invia al vostro server HTTP un certificato elettronico, emesso da una Autorità Certificatrice ( come VeriSign ), che contiene una chiave pubblica. Questa chiave pubblica ( una stringa testuale, apparentemente senza senso ) identifica la Società o il sito web che il vostro server HTTP deve contattare ( PayPal, nel nostro caso ). Questa chiave pubblica, in realtà, è una vera e propria chiave di codifica dei dati, ma è strettamente legata alla Società o al sito web che ha ottenuto la certificazione della propria identità. Il vostro server HTTP ( cURL, nel nostro caso ) deve verificare l'affidabilità di quel certificato elettronico, consultando una lista delle Autorità di Certificazione ritenute affidabili, lista che solitamente si trova sullo stesso vostro server HTTP ( o anche nei vostri PC di casa ). Generalmente, sulle macchine utente o sui server non specializzati viene installata una lista di Autorità di Certificazioni, considerate altamente affidabili, tanto da permettere ai browser o a cURL di considerare i certificati emessi da un'Autorità di Certificazione compresa in questa lista, affidabili. Ebbene: il signor Peter Chng ci informa che cURL non è configurato per considerare affidabile qualsiasi certificato. Non solo: cURL, di default, è impostato in modo tale da non considerare affidabile qualsiasi Autorità di Certificazione. Quindi, il signor Peter Chng ci informa che questa impostazione potrebbe non funzionare su tutti i siti. Questo non dovrebbe, certamente, essere il caso di PayPal. L'opzione CURLOPT_SSL_VERIFYPEER può assumere due valori:

  • 0 ( zero ): non eseguire la verifica del certificato elettronico inviato dal server HTTPS di PayPal.

  • 1 ( uno ): esegui la verifica del certificato elettronico inviato dal server HTTPS di PayPal.

Ora, possiamo effettuare la connessione al server HTTPS di PayPal:

  if(!$page = curl_exec($conn))
	{
	echo curl_error($conn);
	curl_close($conn);
	}

La connessione viene eseguita dalla funzione PHP curl_exec, che vuole, come argomento, il nome del filehandle associato alla connessione che desideriamo instaurare. Visto che abbiamo impostato l'opzione CURLOPT_RETURNTRANSFER a 1, cURL tenterà di connettersi alla URL specificata nel filehandle $conn e restituirà al vostro programma "grazie.php" la stringa che riceverà dal server HTTPS di PayPal, salvandola nella variabile $page. Quindi, se, una volta effettuata la connessione, la variabile $page dovesse essere vuota, significherebbe che qualcosa è andato storto, che curl_exec non è riuscito ad instaurare una connessione con il sito web connesso al filehandle $conn. La funzione curl_error restituisce l'ultimo errore registrato da cURL. In questo caso, il vostro programma stampa a video il messaggio di errore e chiude la connessione con il server HTTPS di PayPal. Se, al contrario, tutto fosse andato bene, la variabile $page conterrebbe la risposta ricevuta dal server HTTPS di PayPal, il messaggio contenente tutte le informazioni relative alla transazione finanziaria appena conclusa. Vediamo quale sarebbe il contenuto di $page:

SUCCESS
mc_gross=10.00
protection_eligibility=Ineligible
address_status=unconfirmed
payer_id=R592U9RZNQQY4
tax=0.00
address_street=Via+delle+Cornstars+43
payment_date=00%3A22%3A04+Nov+21%2C+2011+PST
payment_status=Completed
charset=windows-1252
address_zip=20127
first_name=Monica
mc_fee=0.69
address_country_code=IT
address_name=Monica+Laghi
custom=
payer_status=verified
business=mammamia%40htyrufjl.com
address_country=Italy
address_city=Miano
quantity=1
payer_email=business2007%40abracaduuu.it
txn_id=1506982009994945Y
payment_type=instant
last_name=Laghi
address_state=Milano
receiver_email=mammamia%40htyrufjl.com
payment_fee=
receiver_id=8KM75GS8NBPFJ
txn_type=web_accept
item_name=Il+mio+primo+articolo
mc_currency=EUR
item_number=1000
residence_country=IT
handling_amount=0.00
transaction_subject=Il+mio+primo+articolo
payment_gross=
shipping=0.00

La risposta del server HTTPS di PayPal contiene una prima riga che riporta l'esito della transazione PDT ( SUCCESS, in questo caso ), seguita da una serie di righe, ciascuna composta da una coppia chiave/valore delle variabili PayPal, relative al pagamento online appena concluso. Attenzione:

• La prima riga del BODY della risposta di PayPal riporta l'esito della transazione PDT e non l'esito del pagamento online del vostro utente! PDT, infatti, viene attivato, come tutte le pagine di ritorno, compresa IPN, solo dopo la conclusione della transazione finanziaria. In questa prima riga del BODY della risposta di PayPal, potete trovare solo due valori:

  • SUCCESS ( la transazione PDT è OK )

  • FAIL ( la transazione PDT è fallita )

• L'esito dell'avvenuto pagamento, da parte del vostro utente, è contenuto in una delle variabili inviate dal server HTTPS di PayPal, come abbiamo già visto nel precedente articolo, "La pagina di ritorno, PDT e IPN", e, più esattamente, nella variabile:

  
  payment_status
  
  

  il cui valore, nel nostro caso, è "Completed" ( transazione OK ). L'elenco della variabili utilizzate dal server HTTPS di PayPal, nelle transazioni PDT e IPN, e dei valori che possono assumere, lo trovate nella pagina PayPal Variabili IPN e PDT.

• Nel caso la prima riga del BODY della risposta del server HTTPS di PayPal fosse "FAIL", verificate i seguenti parametri:

  • siete certi di aver trasmesso, al server HTTPS di PayPal, il dato corretto, come ID della transazione ( l'ID ricevuto nella variabile $_GET['tx'] )?

  • siete certi di aver trasmesso, al server HTTPS di PayPal, il dato corretto, come ID PDT del vostro account PayPal ( quello contenuto nella variabile $token )?

  • avete verificato che $token non sia scaduto?

• l'esito della transazione PDT ( SUCCESS/FAIL ) si trova nella prima riga del BODY del messaggio del server HTTPS. Nel nostro caso, si trova nella prima riga del messaggio completo solo perchè il vostro programma "grazie.php" ha chiesto a cURL di escludere, dal messaggio di risposta, gli HEADER HTTP, impostando l'opzione cURL CURLOPT_HEADER a 0 ( zero ). Tenete a mente che, se mai aveste il bisogno di impostare l'opzione CURLOPT_HEADER a 1 ( uno ), questa riga verrebbe a trovarsi solo dopo l'elenco degli header HTTP.

Ora che abbiamo la risposta del server HTTPS di PayPal, il lavoro è tutto in discesa. Dobbiamo solo estrarre i dati da quella lunga stringa di testo appena ricevuta. Per fare questo, il vostro programma "grazie.php" utilizza la funzione PHP split e le espressioni regolari ( regex ), molto simili alla funzione split ed alle espressioni regolari di Perl, usate nell'articolo precedente: "La pagina di ritorno, PDT e IPN".

	$arVar = split("\n", $page);

Per separare le righe che compongono il messaggio ricevuto dal server HTTPS di PayPal, utilizziamo la funzione PHP split, che, come in Perl, splitta ( divide, separa ) una stringa di testo, utilizzando, come separatore, il carattere ( o i caratteri ) specificati come primo argomento ( \n ). Al termine dell'operazione, il carattere separatore viene eliminato ( poichè la stringa è stata scomposta ) e ciascuna riga della stringa viene salvata, come elemento singolo, nell'array semplice ( o lista ) $arVar. Il carattere che abbiamo usato come separatore è il carattere "a capo" ( \n ). Attenzione, perchè, nel caso il vostro server avesse Windows, come sistema operativo, è possibile che, come carattere "a capo", dobbiate usare la sequenza di caratteri usata da Windows, che utilizza due caratteri:

	$arVar = split("\r\n", $page);

anche se è possibile che questa conversione venga effettuata direttamente da PHP ( PHP legge \n, ma, sapendo di essere in ambiente Windows, lo converte in \r\n ).

	if($arVar[0] == "FAIL")
	{ echo "Errore nell'acquisizione dei dati"; }

La variabile $arVar[0] legge il valore contenuto nel primo elemento dell'array semplice $arVar. Questo primo elemento contiene la prima riga della risposta del server HTTPS di PayPal, cioè l'esito della transazione PDT. Se questo esito è negativo ( FAIL ), il programma stampa a video un messaggio di errore e termina. Se, invece, l'esito è positivo ( SUCCESS ):

	else if ($arVar[0] == "SUCCESS")

il programma esegue tutte le restanti righe del codice.

for($a=1; $a<count($arVar); $a++)
	  {

	  list($key, $val) = split("=", $arVar[$a]);
	  $val = preg_replace('/\+/', ' ', $val);

	  #########################
	  ## Questa è una riga unica 

	  $val = preg_replace('/%([\da-f][\da-f])/ei',
		"chr(hexdec('\\1'))", $val);

	  ## Questa è una riga unica 
	  #########################

	  $posted[$key]= $val;

	  }

Il blocco for esegue le operazioni comprese all'interno del blocco stesso su tutti gli elementi dell'array $arVar, eccetto il primo ( $arVar[0] ). Infatti, il contatore $a parte da 1 ed arriva fino all'ultimo elemento dell'array, count($arVar). Il fine ultimo di queste operazioni è il riempimento dell'array associativo $posted, che conterrà tutte le variabili, inviate dal server HTTPS di PayPal. Queste poche righe di codice eseguono le stesse operazioni eseguite nel nostro programma Perl, "grazie.pl", nel precedente articolo, "La pagina di ritorno, PDT e IPN". La sola differenza, tra Perl e PHP, risiede nella chiamata al motore delle espressioni regolari: mentre Perl utilizza l'operatore:

	=~

per eseguire una ricerca ( senza sostituzione ) all'interno di una stringa, e l'operatore:

	=~ s

per eseguire una ricerca con sostituzione all'interno di una stringa, PHP mette a disposizione le due funzioni:

	preg_match
	preg_replace

Per il resto, la sintassi delle espressioni regolari è esattamente la stessa usata negli esempi del precedente articolo. Identica è anche la parte finale del programma, che verifica il valore della variabile:

	$posted['payment_status']

per poi stampare tutte le variabili ricevute.

Il programma in Perl

Scrivere lo stesso programma in Perl, potrebbe rivelarsi un po' più complicato. Perl, infatti, per supportare le transazioni HTTPS, mette a disposizione alcune librerie, quali:

	Net::SSLeay
	Crypt::SSLeay
	IO::Socket::SSL

Se aveste installato la libreria Crypt::SSLeay sul vostro server, potreste tranquillamente riscrivere lo stesso programma PHP in linguaggio Perl, includendo le librerie LWP e Crypt::SSLeay, le quali, insieme, si occuperebbero di portare a termine il loro compito. Il problema è che le librerie SSL di Perl non sono installate sul server, in una configurazione standard. Il problema è che per caricare queste librerie serve un accesso privilegiato al server. Questo significa che, se possedete un server, oppure avete un account a pagamento del tipo VPS o server dedicato, che, solitamente, prevedono l'accesso privilegiato al server, potrete installare le librerie necessarie. In caso contrario, dovreste chiedere al vostro fornitore l'installazione dei moduli richiesti. Normalmente, questo genere di richieste non viene nemmeno preso in considerazione. Che fare? Se avete bisogno che le variabili PayPal siano rese disponibili in ambiente Perl, la soluzione potrebbe consistere nell'aggirare l'ostacolo, preparando un programma Perl da dare in pasto a PDT di PayPal, costringendo Perl ad utilizzare PHP per eseguire la connessione al server HTTPS di PayPal. Questo, a patto che almeno la libreria PHP cURL, installata sul vostro server, abbia il necessario supporto per le transazioni SSL. Cominciamo da questo caso.

Il programma in Perl senza supporto Perl SSL

Intanto, accedete al vostro account PayPal ( o Sandbox ) ed impostate la pagina di ritorno PDT, inserendo, come pagina di ritorno, un file Perl, che andremo a creare ora: "grazie.pl".

	http://www.dominio.com/cgi-bin/grazie.pl

I campi della form HTML, invece, saranno gli stessi generati nel precedente esempio PHP, visto che la pagina di ritorno PDT non prevede alcun campo HTML obbligatorio supplementare. Prima di creare il file Perl, dovremo creare il file PHP che avrà il solo compito di effettuare la connessione al server HTTPS di PayPal:

<?php
$tx;
$to = "https://www.sandbox.paypal.com/cgi-bin/webscr";
$token = "817lWxbtmGGG1kW872k_F9qI5RWsCirOmjQJykh5eamqCihMaGMQTbwew78";
$cmd = "_notify-synch";
$page;

if($_POST['tx'])
        {   $tx = $_POST['tx'];   }

if($tx)
        {

        $conn = curl_init($to);
        curl_setopt($conn, CURLOPT_HEADER, 0);
        curl_setopt($conn, CURLOPT_NOBODY, 0);
        curl_setopt($conn, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($conn, CURLOPT_FOLLOWLOCATION, 1);
        curl_setopt($conn, CURLOPT_SSL_VERIFYPEER, 1);
        curl_setopt($conn, CURLOPT_USERAGENT, "Mozilla/5.0");
        curl_setopt($conn, CURLOPT_POST, 1);

        curl_setopt($conn, CURLOPT_POSTFIELDS, array(
		'cmd'=>$cmd, 'tx'=>$tx, 'at'=>$token));

        if(!$page = curl_exec($conn))
                {

                echo curl_error($conn);
                curl_close($conn);

                }
        else
                {

                curl_close($conn);	
                echo "$page";

                }

        }

?>

Salvate questo file, con il nome "gr.php" ( o come preferite ) ed installatelo, sul vostro server HTTP, in una cartella a vostro piacimento. In questo esempio, lo mostrerò installato nella cartella "cgi-bin", insieme al file "grazie.pl". Come potete vedere, questo file è molto simile al programma PHP che abbiamo utilizzato prima, con due sostanziali differenze:

• la variabile tx non viene più estratta dall'array associativo $_GET, bensì dall'array associativo $_POST. Questo accade perchè, in questo caso, la variabile tx inviata dal server HTTPS di PayPal viene inviata al vostro programma Perl "grazie.pl", il quale la reinvia, via HTTP POST, al file PHP "gr.php".

• una volta effettuata la connessione, se tutto è andato bene, cURL si limita a stampare ( echo ) sull'output standard ( STDOUT ) la variabile $page che, come già sappiamo, contiene la risposta ricevuta dal server HTTPS di PayPal e, quindi, tutte le variabili relative alla transazione appena conclusa.

L'array associativo $_POST, come abbiamo già visto, viene creato, automaticamente, da PHP durante le transazioni HTTP. Questo significa che il vostro programma Perl "grazie.pl" dovrà effettuare una vera e propria chiamata HTTP al vostro programma PHP "gr.php". Perchè? Perchè, se il vostro server HTTP già non supporta le transazioni SSL, è molto probabile che non supporti nemmeno le chiamate all'interprete PHP. In pratica, per una serie di motivi che sarebbe troppo complicato affrontare in questa sede, molti server di hosting, ultimamente, hanno fatto la scelta di rendere disponibile PHP solo come applicazione CGI ( cioè, invocabile solo via HTTP ). PHP può essere compilato in molti modi differenti ( PHP Installation on UNIX systems ) ed utilizzare differenti interfacce utente/applicazione ( SAPI, Server Application Programming Interface ):

	aolserver
	apache
	apache2filter
	apache2handler
	caudium
	cgi (until PHP 5.3)
	cgi-fcgi
	cli
	continuity
	embed
	isapi
	litespeed
	milter
	nsapi
	phttpd
	pi3web
	roxen
	thttpd
	tux
	webjames

L'interfaccia utilizzata definisce le modalità di invocazione di PHP, oltre ad una serie di variabili e/o di funzioni disponibili. Le interfacce più utilizzate sono:

	cgi (until PHP 5.3)
	cgi-fcgi
	cli ( Command Line Interface )

Di default, i server, soprattutto i server di hosting, utilizzano la SAPI CGI, la quale non processa gli argomenti inviati da linea di comando ( o da QUERY_STRING ). Per sapere in quale modalità viene eseguito PHP sul vostro server, create un file "test.php" con scritto:

<?php
	echo php_sapi_name();
?>

e vedrete stampato a video il nome della SAPI utilizzata ( "cgi", "cli" ). Oppure, create lo stesso file "test.php" e scrivete:

<?php
	phpinfo();
?>

Una volta eseguito "test.php", cercate la voce "Server API". Naturalmente, se il vostro server supportasse le chiamate CLI ( Command Line Interface ), da riga di comando, sarà necessario apportare solo qualche lieve modifica sia al file Perl, sia al file PHP. Per semplicità, ho scelto la modalità CGI, anche se più dispendiosa, perchè dovrebbe funzionare in ogni caso. Vediamo ora il file "grazie.pl".

#!/usr/bin/perl -T

use warnings;
use strict;
use LWP::UserAgent;

$ENV{'PATH'}="";

my $to = "http://www.dominio.com/cgi-bin/gr.php";
my $ua = new LWP::UserAgent;
	$ua->agent('Mozilla/5.0');
my $req;
my $result;
my $p;
my @arVar;
my %posted;
my $key;
my $value;
my $postString;
my $errMsg;

if($ENV{'QUERY_STRING'})
        {

        @arVar=split(/&/, $ENV{'QUERY_STRING'});
        
        foreach my $t(@arVar)

                {

                ($key, $value)=split(/=/, $t);

                if($key eq "tx")
                        {

                        ## Untaint ##

                        if($key =~ /([^`]+)/)
                                { $key = $1; }

                        if($value =~ /([^`]+)/)
                                { $value = $1; }

                        last;

                        }

                }        

        $postString.="${key}=${value}";

        $req = new HTTP::Request("POST", $to);
        $req->content_type("application/x-www-form-urlencoded");
        $req->content($postString);
        $result = $ua->request($req);
        $p = $result->as_string;

        if($p)
                {

                @arVar = split(/\n\n/, $p);
                $p = $arVar[1];

                @arVar = split(/\n/, $p);

                if($arVar[0] eq "FAIL")
                { $errMsg = "Errore nell'acquisizione dei dati"; }

                elsif($arVar[0] eq "SUCCESS")
                  {

                     for(my $a=1; $a<=$#arVar; $a++)
                       {

                        ($key, $value) = split(/=/, $arVar[$a]);
                        $value =~ tr/+/ /;
                        $value =~ s/%([\da-f][\da-f])/chr(hex($1))/eig;
                        $posted{$key}=$value;

                        }

                  }
                }
        }

print "Content-type:text/html\n\n";
print $errMsg, "<br>" if ($errMsg);

if($posted{'payment_status'} eq "Completed")
  { print "Grazie per il tuo acquisto<br><br>"; }
else
  { print "Ci dispiace, transazione interrotta<br><br>"; }

foreach my $t(keys %posted)
        { print $t, " ", $posted{$t}, "<br>"; }

exit;

Una parte di questo file dovrebbe essere già comprensibile, visto che abbiamo utilizzato funzioni e meccanismi già usati nel precedente esempio in Perl. La riga:

	use LWP::UserAgent;

dice a Perl di caricare il modulo Perl LWP::UserAgent, un modulo compreso nella più vasta famiglia dei moduli Perl LWP, una libreria Perl che permette l'accesso al mondo web. In particolare, il modulo LWP::UserAgent simula un UserAgent, cioè un software simile ad un browser. LWP::UserAgent rappresenta una classe, cioè un browser "ideale", con le sue proprietà e le sue funzioni. Una classe è un po' come l'idea platonica: è un oggetto che esiste solo nel mondo iperuranio, un oggetto che esprime la perfezione della cosa che rappresenta. Affinchè una classe possa essere utilizzata da voi, qualcuno ( voi ) deve creare una "istanza" di quella classe, cioè un oggetto reale che abbia tutte o alcune delle proprietà dell'ogggetto ideale e che sia in grado di effettuare, o in tutto o in parte, le stesse operazioni ( funzioni ), che, potenzialmente, potrebbe eseguire l'oggetto ideale ( classe ). Proprietà e funzioni, quindi, sono già state definite all'interno della definizione della classe: nel creare la nostra istanza reale, noi dobbiamo solo decidere quali proprietà e quali funzioni assegnarle. Quando acquistate una macchina, il modello superaccessoriato è la classe di quella macchina, mentre il modello che, alla fine, comprerete, è un'istanza di quella classe. L'istanza del vostro UserAgent viene creata qualche riga dopo:

	my $ua = new LWP::UserAgent;
	$ua->agent('Mozilla/5.0');

Il nostro UserAgent $ua, in questo momento, è un oggetto spoglio, senza proprietà, ad eccezione dell'identificativo di un Agent ( Mozilla: ricordatevi di specificare sempre un Agent, soprattutto nelle connessioni SSL ), nè funzioni. Nelle righe successive, questo nuovo oggetto verrà "riempito". Un accenno alla riga:

	$ENV{'PATH'}="";

del vostro programma "grazie.pl". Nel precedente articolo, "PayPal: la pagina di ritorno, PDT e IPN", abbiamo parlato della modalità Perl di esecuzione Taint Mode, impostata nella prima riga del programma:

	#!/usr/bin/perl -T

Taint Mode è una modalità di esecuzione che costringe l'interprete di Perl a verificare costantemente che qualsiasi variabile, il cui valore sia prelevato dall'esterno, non venga mai passata alla shell dei comandi. La variabile d'ambiente PATH contiene i percorsi del server nei quali Perl cercherà gli eseguibili eventualmente invocati dal vostro programma ( quindi, anche dai moduli Perl inclusi ). Svuotare questa variabile significa costringere il programmatore ( voi ) a invocare uno script o una applicazione server specificandone, sempre, l'intero percorso e non solo il nome. Quando Perl incontra una chiamata ad un file, senza che ne sia specificato il percorso, se la modalità Taint è attiva, come nel nostro caso, Perl interrompe immediatamente l'esecuzione del programma, restituendovi un messaggio di errore, del tipo:

	Insecure dependency in ...

Le variabili, oggetto dell'attenzione di Taint, sono le variabili in arrivo dal server HTTPS di PayPal, tra le quali dovremmo trovare anche la variabile tx, identificativo della transazione in corso, che, a nostra volta, dovremo rispedire al server HTTPS di PayPal, insieme alle varibili cmd e at, per ottenere, da PayPal, le informazioni relative al pagamento appena concluso. Quindi, il primo compito del nostro programma è di isolare la variabile tx, inviata dal server HTTPS di PayPal:

	if($ENV{'QUERY_STRING'})

PayPal, chiamando il vostro programma PDT, invia alcune variabili, di cui la più importante, per voi, è la variabile tx. Questo invio viene fatto con il metodo HTTP GET, "attaccando" le variabili, come abbiamo già visto, alla URL del vostro programma. La variabile d'ambiente $ENV{'QUERY_STRING'} contiene proprio la stringa testuale inviata dal server HTTPS di PayPal, via GET. Nelle righe successive, eseguiamo la funzione Perl split, di cui conosciamo già sintassi e scopo, per estrarre la sola variabile che, in questo momento, ci interessa: tx, per poi salvarla nella variabile $value ( mentre $key ne contiene il nome: tx ).

@arVar=split(/&/, $ENV{'QUERY_STRING'});
        
foreach my $t(@arVar)

	{

	($key, $value)=split(/=/, $t);

	if($key eq "tx")
	  {

	  ## Untaint ##

	  if($key =~ /([^`]+)/)
	    { $key = $1; }

	  if($value =~ /([^`]+)/)
	    { $value = $1; }

	  last;

	  }

	}        

        $postString.="${key}=${value}";

La sola novità di queste righe è rappresentata da quelle espressioni regolari applicate alle variabili $key e $value. In realtà, queste espressioni regolari non fanno nulla:

	if($key =~ /([^`]+)/)
	if($value =~ /([^`]+)/)

Sappiamo già, dal precedente articolo, "PayPal: la pagina di ritorno, PDT e IPN", che le parentesi tonde, all'interno di una stringa di ricerca ( /pattern/ ), delimitano una parte della stringa che, se trovata, deve essere memorizzata nella variabile Perl $1. Sappiamo, altresì, che le parentesi quadre, all'interno di una stringa di ricerca, identificano una classe di caratteri. Le novità sono: l'accento circonflesso, che, se si trova all'interno delle parentesi quadre, è un operatore di negazione ed il segno + che indica la quantità di caratteri che mi aspetto di trovare in quella posizione: il segno più significa "almeno uno" ( ma, di caratteri, potrebbero essercene anche mille ). Quindi, l'espressione:

	if($key =~ /([^`]+)/)
	    { $key = $1; }

significa: salva in $1 e poi in $key quella parte della stringa $key che non contiene il carattere `, seguito da un certo numero di altri caratteri ( almeno 1 ). Ma noi già sappiamo che PayPal non ci invierebbe mai una stringa contenente quel carattere proibito, quindi, sappiamo già dall'inizio che in $1 e poi in $key verrà salvata l'intera stringa $key. A che serve, allora, questo blocco di codice? Serve a "liberare" le variabili $key e $value dalla morsa di Taint. Le variabili $key e $value, infatti, sono due variabili Tainted ( cioè, sotto il controllo del Taint Mode ), perchè sono state generate dall'array semplice @arVar, che era Tainted, visto che era stato generato, a sua volta, da $ENV{'QUERY_STRING'}, la quale è stata acquisita dall'esterno! Perchè il Taint Mode non si estende solo alle variabili espressamente acquisite dal mondo esterno, ma si propaga, come un virus, a tutte le variabili che vengono riempite con i valori delle variabili Tainted. Perl, per liberare una variabile Tainted, desidera che gli si venga dimostrato che qualcuno ( voi ) ha eseguito un qualche controllo su quella variabile. E Perl considera efficace solo il controllo effettuato con una espressione regolare contenente una coppia di parentesi tonde, in cui una variabile $1 abbia sostiuito almeno una parte della stringa originale. A questo punto, possiamo tranquillamente creare la stringa da inviare al vostro programma PHP:

	$postString.="${key}=${value}";

senza il timore che il modulo LWP::UserAgent la invii alla shell dei comandi, causando il blocco del programma. Nelle righe successive, prepariamo la connessione, per il nostro UserAgent $ua. Una connessione HTTP è composta da:

• una richiesta:

  
  $req = new HTTP::Request("POST", $to);
  $req->content_type("application/x-www-form-urlencoded");
  $req->content($postString);
  
  

  dove $to contiene la URL del vostro programma "gr.php" e $postString contiene la variabile Paypal tx, da inviare via HTTP POST.

• un socket, cioè, un programma che effettui la connessione:

  
  $result = $ua->request($req);
  
  

  salvando la risposta ottenuta in $result.

• Una risposta leggibile, così da poter essere manipolata:

  
  $p = $result->as_string;
  
  

A questo punto, la variabile $p contiene tutti i dati inviati al vostro programma "gr.php" dal server HTTPS di PayPal. Il vostro programma PHP, ha reinviato questi dati al vostro programma "grazie.pl". Ecco cosa contiene, in questo caso, la variabile $p:

HTTP/1.1 200 OK
Connection: close
Date: Sun, 27 Nov 2011 07:52:26 GMT
Server: Apache/2.2
Content-Type: text/html
Client-Date: Sun, 27 Nov 2011 07:52:29 GMT
Client-Peer: 62.149.140.21:80
Client-Response-Num: 1
Client-Transfer-Encoding: chunked
X-Powered-By: PHP/4.4.9

SUCCESS
mc_gross=10.00
protection_eligibility=Ineligible
address_status=unconfirmed
payer_id=R592U9RZNQQY4
tax=0.00
address_street=Via+delle+Cornstars+43
payment_date=23%3A52%3A13+Nov+26%2C+2011+PST
payment_status=Completed
charset=windows-1252
address_zip=20127
first_name=Monica
mc_fee=0.69
address_country_code=IT
address_name=Monica+Laghi
custom=
payer_status=verified
business=mammamia%40htyrufjl.com
address_country=Italy
address_city=Miano
quantity=1
payer_email=business2007%40abracaduuu.it
txn_id=7L913473NT172290J
payment_type=instant
last_name=Laghi
address_state=Milano
receiver_email=mammamia%40htyrufjl.com
payment_fee=
receiver_id=8KM75GS8NBPFJ
txn_type=web_accept
item_name=Il+mio+primo+articolo
mc_currency=EUR
item_number=1000
residence_country=IT
handling_amount=0.00
transaction_subject=Il+mio+primo+articolo
payment_gross=
shipping=0.00

Come potete vedere, la stringa di testo ricevuta è composta dagli header HTTP e dalla risposta del server HTTPS di PayPal. Gli header HTTP sono gli header relativi alla connessione tra il vostro programma Perl ed il vostro programma PHP. Quindi, sono gli header inviati dal vostro server HTTP e non dal server HTTPS di PayPal. Gli header del server PayPal, se ricordate, li avevamo esclusi, impostando l'opzione cURL CURLOPT_HEADER a 0 ( zero ). Visto che gli header HTTP non ci servono, la prima operazione è eliminarli, recuperando la stringa di PayPal, che è la sola ad interessarci:

        if($p)
                {

                @arVar = split(/\n\n/, $p);
                $p = $arVar[1];

                }

Gli header HTTP sono separati dal corpo del messaggio ( contenente le variabili PayPal ) da due caratteri consecutivi "a capo": \n\n. Quindi, per separare queste due entità, è sufficiente eseguire uno split, in cui l'elemento separatore sia proprio la sequenza di caratteri \n\n. Memorizziamo, temporaneamente, le due entità in un array @arVar, che sarà composto dai due elementi:

	$arVar[0] header HTTP
	$arVar[1] messaggio PayPal

Quindi, risalviamo in $p solo il messaggio PayPal. A questo punto, non ci resta che eseguire, sulla stringa $p, le stesse operazioni che abbiamo eseguito nel precedente programma PHP, per separare le variabili inviate dal server HTTS di PayPal e salvarle nell'array associativo $posted. Il significato delle righe del programma che eseguono queste operazioni è lo stesso significato delle righe del programma "grazie.pl" utilizzato nel precedente articolo "PayPal: la pagina di ritorno, PDT e IPN". Ricordate solo che quando memorizzate le singole righe della risposta del server HTTPS di PayPal:

	@arVar = split(/\n/, $p);

il contenuto del primo elemento del nuovo array @arVar:

	$arVar[0]

è la riga contenente l'esito della transazione PDT ( SUCCESS / FAIL ).

Il programma in Perl con supporto Perl SSL

Se il vostro server supporta le transazioni SSL e ha installato il modulo Perl Crypt::SSLeay, sarà sufficiente apportare qualche lieve modifica al programma precedente, affinchè tutto funzioni a meraviglia. La prima differenza è che, in questo caso, non abbiamo più bisogno del file intermedio "gr.php", visto che, ora, il lavoro verrà svolto interamente da Perl. Le uniche variazioni da apportare, rispetto al programma appena visto, sono da apportare nella sezione riservata alla dichiarazione delle variabili:

my $to="https://www.sandbox.paypal.com/cgi-bin/webscr";
my $token="817lWxbtmGGG1kW872k_F9qI5RWsCirOmjQJykh5eamqCihMaGMQTbwew78";
my $cmd = "_notify-synch";
my $ua = new LWP::UserAgent;
	$ua->agent('Mozilla/5.0');
my $req;
my $result;
my $p;
my @arVar;
my %posted;
my $key;
my $value;
my $postString="cmd=".$cmd."&at=".$token."&";
my $errMsg;

Apportate queste variazioni, il vostro programma "grazie.pl" eseguirà la transazione, chiamando la libreria Perl Crypt::SSLeay per gestire le transazioni SSL.

Alcune raccomandazioni finali

Nella guida PayPal Order Management Integration Guide troviamo alcune avvertenze utili, relative a PDT.

1)
A differenza della pagina di ritorno semplice, quella vista nell'articolo precedente, "PayPal: la pagina di ritorno, PDT e IPN", il reindirizzamento del vostro utente, a fine transazione, al vostro programma PDT, avviene in modo automatico. In realtà, il server HTTPS di PayPal attende qualche secondo prima di avviare questo reindirizzamento. In questi pochi secondi di attesa, il vostro utente potrebbe decidere di uscire dal sito di PayPal ( o chiudere il browser ). Se questo avvenisse, la vostra pagina di ritorno PDT non verrebbe mai chiamata.

2)
Se, all'interno del vostro account PayPal, avete mantenuto l'impostazione di default dell'opzione "Conto PayPal opzionale"

	Profilo
	Strumenti Vendita
		Vendite online
		Preferenze per i pagamenti su sito web
		Aggiorna
		Conto PayPal opzionale

i vostri utenti non saranno obbligati ad iscriversi a PayPal, prima di eseguire il pagamento. In questo caso, però, il reindirizzamento alla vostra pagina di ritorno PDT non sarà automatico. Come nel caso della pagina di ritorno semplice, al vostro utente verrà presentato un bottone "Continua". Solo se il vostro utente premerà quel bottone, verrà avviata la chiamata al vostro programma PDT.

3)
PayPal raccomanda di verificare la variabile di ritorno txn_id ( il numero identificativo originario della transazione ), al fine di controllare che non sia stata già utilizzata in una transazione precedente completata.

4)
PayPal raccomanda di verificare la variabile di ritorno receiver_email, che riporta sempre l'indirizzo email principale del vostro account. Nel caso in cui non stiate utilizzando un indirizzo email diverso, questa variabile ha lo stesso valore della variabile business.

5)
La URL del vostro programma PDT inserita all'interno del menù "Funzionalità Ritorno automatico per i pagamenti su sito web" del vostro account PayPal è la URL di default usata dal server HTTPS di PayPal per reindirizzare il vostro utente al vostro sito web, una volta terminata la transazione online. E' possibile impostare una URL differente per ciascuna transazione, utilizzando i campi rm e return, all'interno della vostra form HTML del bottone "Paga adesso". Sono gli stessi campi che abbiamo inserito nell'articolo precedente, "PayPal: la pagina di ritorno, PDT e IPN", nella sezione "La pagina di ritorno con invio dei dati POST". In sostanza:

• se, nella form HTML del bottone "Paga adesso" del vostro sito, sono presenti i campi rm ( 2 ) e return ( URL differente ) e, all'interno del vostro account PayPal è stato attivato il servizio "Trasferimento dei dati del pagamento" ( PDT ), il server PayPal, a fine transazione, chiamerà il programma, residente sul vostro server, la cui URL è contenuta nel campo return, in modalità PDT.

• se, nella form HTML del bottone "Paga adesso" del vostro sito, sono presenti i campi rm ( 2 ) e return ( URL differente ) e, all'interno del vostro account PayPal non è stato attivato il servizio "Trasferimento dei dati del pagamento" ( PDT ), il server PayPal, a fine transazione, chiamerà il programma, residente sul vostro server, la cui URL è contenuta nel campo return, in modalità "Pagina di ritorno con invio dei dati POST" ( dati non criptati ).