Instant Payment Notification ( IPN )

Il meccanismo IPN non è molto dissimile dal meccanismo PDT. La differenza sostanziale è che IPN non è da utilizzare come pagina di ritorno per il vostro utente. Una transazione IPN può avvenire subito dopo la chiusura della transazione finanziaria, oppure uno o due giorni dopo. L'unica cosa certa è che con IPN il server HTTPS di PayPal invierà le informazioni, relative al pagamento online appena concluso, sempre e comunque, a prescindere dal comportamento del vostro utente. Quindi, IPN è da utilizzare solo ed esclusivamente se a voi servono i dati inviati da PayPal per aggiornare il vostro database. IPN, naturalmente, può coesistere con una delle pagine di ritorno viste nei precedenti capitoli:

• la pagina di ritorno, con invio dei dati POST, o senza invio dei dati POST.

• Payment Data Transfer ( PDT ).

La pagina di ritorno ( semplice o PDT ) serve a stampare a video, per il vostro utente, le informazioni relative alla transazione appena conclusa, mentre il programma IPN serve a voi per eseguire, in background, tutte quelle operazioni che riterrete opportuno eseguire sul vostro database. Di IPN, dovete tenere a mente alcuni punti essenziali:

• Come le pagine di ritorno, IPN viene attivato, dal server HTTPS di PayPal, solo a transazione finanziaria conclusa.

• Come PDT, le comunicazioni, tra il vostro server ed il server PayPal, dovranno essere indirizzate ad una URL HTTPS. Questo significa che, prima di poter inviare i dati dal vostro server al server Paypal, il vostro programma dovrà essere in grado di eseguire, quanto meno, la procedura SSL iniziale di handshake ( negoziazione ).

• La procedura IPN prevede che il server HTTPS chiami il programma IPN, residente sul vostro server, inviandogli immediatamente tutte le informazioni relative alla transazione appena conclusa. Appena ricevute queste informazioni, il vostro programma IPN dovrà inviare, al server HTTPS di Paypal, una conferma di ricezione ( notification validation ). Il server HTTPS di PayPal, ricevuta questa conferma di ricezione, invierà, al vostro programma IPN, un messaggio di chiusura della transazione IPN. Se, per un qualsiasi motivo, il server Paypal non ricevesse il vostro messaggio di avvenuta ricezione ( notification validation ), non sarebbe in grado di chiudere la transazione IPN corrente. La mancata chiusura di una transazione IPN comporta la riattivazione della procedura IPN, per la singola transazione IPN non conclusa, a distanza ravvicinata. Il sistema PayPal ricontatterà il vostro programma IPN, fino a quando quest'ultimo non invii a PayPal il messaggio di avvenuta ricezione. Questo significa che è possibile che il vostro programma IPN riceva, dal server HTTPS di PayPal, più di una notifica IPN per la stessa transazione, anche se, apparentemente, quella transazione fosse stata già processata correttamente. E' compito del vostro programma IPN verificare, immediatamente, se la transazione IPN corrente sia una nuova transazione oppure una transazione già chiusa in precedenza. Se la transazione corrente fosse una transazione già chiusa, è possibile che il vostro programma IPN abbia già apportato, sul vostro database, le modifiche necessarie. Quindi, è possibile che la transazione corrente sia da non processare ulteriormente. Per effettuare questa verifica, è necessario controllare il valore della variabile PayPal txn_id che contiene il codice identificativo della singola transazione. Nel caso di una nuova transazione IPN, il valore della variabile txn_id deve essere salvato da qualche parte, in modo da poter, in seguito, verificare che Paypal non stia ritrasmettendo i dati di una transazione IPN che, per voi, è già conclusa.

• Durante la fase di test del vostro programma IPN, ricordate che, nel caso in cui il vostro programma IPN non funzionasse ( per esempio, per un vostro errore di scrittura ), per il server PayPal quella singola transazione non sarà considerata chiusa e verrà riattivata periodicamente. Questo significa che, se doveste simulare dieci acquisti, prima di raggiungere un buon funzionamento del vostro programma IPN, non appena avrete caricato sul vostro server il programma IPN funzionante, riceverete, a cascata, tutti i messaggi IPN relativi alle transazioni IPN che non eravate stati in grado di portare a termine.

• Lo scopo del meccanismo IPN è di automatizzare tutte le procedure di registrazione di un pagamento online. Questo significa che una transazione IPN verrà considerata chiusa solo quando il valore della variabile PayPal payment_status sarà Completed. La variabile PayPal payment_status può assumere diversi valori, a seconda del tipo di transazione che state eseguendo, come potete verificare nella pagina PayPal Variabili IPN e PDT. Nei nostri esempi, fino a questo momento, noi stiamo eseguendo transazioni di vendita di un signolo articolo, con il bottone "Paga adesso" ( Buy Now ). Ipotizziamo, ora, che il vostro cliente paghi con un assegno elettronico ( eCheck ), e non con la carta di credito. Un assegno elettronico non vi verrà accreditato immediatamente, visto che richiede alcuni giorni per poter essere accettato. In questo caso, quindi, il vostro programma IPN riceverà una prima comunicazione IPN, dal server PayPal, dove il valore della variabile payment_status sarà Pending ( in sospeso ). Questo significa che, se dovete inviare il bene acquistato al vostro cliente, dovrete attendere fino a quando l'assegno non risulterà incassato. Insieme alla variabile payment_status, con valore Pending, il vostro programma IPN riceverà la variabile contenente l'identificativo della transazione corrente, txn_id, e la variabile Paypal pending_reason, contenente il motivo per cui questa transazione non è stata completata. Nel nostro caso, il valore della variabile pending_reason sarà echeck, che significa che il vostro utente ha pagato con un assegno elettronico. Quando Paypal riceverà la conferma della validità di quell'assegno elettronico ed incasserà la somma relativa, invierà un secondo messaggio IPN al vostro programma IPN, contenente lo stesso txn_id, ma un diverso valore per la variabile payment_status, che, questa volta, conterrà il valore Completed. A questo punto, la transazione IPN, identificata dalla variabile txn_id, verrà chiusa e voi potrete effettuare la spedizione dell'oggetto venduto.

• Il meccanismo IPN viene eseguito dietro le quinte, senza che voi ne abbiate il controllo. Questo significa che non sarete in grado di verificare l'esistenza di eventuali messaggi di errore. E', quindi, molto importante che voi prevediate, all'interno del vostro programma IPN, un sistema di controllo automatico e di invio di eventuali messaggi di errore, per esempio su un file presente sul vostro server.

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.

Come attivare IPN

Entrate nel vostro account PayPal e seguite il percorso:

	Profilo
	Strumenti vendita
	Notifiche immediate di pagamento
		Aggiorna
	Scegli impostazioni IPN

In questa pagina, due sono le opzioni da attivare:

• URL di notifica: è il campo in cui immettere l'indirizzo internet ( URL ) del programma, installato sul vostro server, che PayPal userà come programma IPN, per esempio:

  
  http://www.dominio.com/ipn.php
  http://www.dominio.com/cgi-bin/ipn.pl	
  
  

• Ricevi messaggi IPN (attivata): spuntare su "Attivato". Questo è il bottone che attiva il vero e proprio metodo PayPal IPN o Instant Payment Notification.

Una volta impostate queste opzioni, premete il bottone "Salva".

Creazione del bottone "Paga adesso"

Ora che avete impostato IPN 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. Prima di premere questo nuovo bottone "Paga adesso", dovrete creare il vostro programma IPN.

Il programma IPN

Una volta terminata la transazione finanziaria, PayPal chiama il vostro programma IPN, inviando, via HTTP POST, tutte le variabili relative alla transazione appena terminata. Il server HTTPS di PayPal, però, resta in attesa della risposta del vostro server, che deve inviare un messaggio di avvenuta ricezione dei dati ( notification validation ). Questo messaggio deve essere inviato via POST e deve contenere l'intera stringa appena ricevuta dal server PayPal, più la coppia di variabili:

	cmd=_notify-validate

A questo punto, se il server PayPal si sente soddisfatto della risposta del vostro programma IPN, chiude la corrente transazione IPN, inviando, al vostro programma IPN una risposta, contenente una sola parola:

	VERIFIED

se ritiene la vostra autenticazione corretta, oppure:

	INVALID

se ritiene che ci sia stato un errore, durante le operazioni IPN. All'interno del sito PayPal potete trovare esempi di programma IPN per diversi linguaggi, compresi PHP e Perl. Sono tutti ottimi esempi, ma hanno il limite di prevedere che il server che li ospiterà avrà installato un pieno supporto per i protocolli SSL. Come ho già spiegato nel precedente capitolo, "PayPal Payment Data Transfer ( PDT )", questo non sempre è vero. Nell'esempio Perl, per esempio, viene utilizzata la libreria LWP per connettersi al server PayPal. Ma la libreria LWP di Perl può supportare le transazioni SSL solo con l'ausilio di una libreria esterna, quale Crypt::SSLeay, che difficilmente viene installata, in una configurazione standard. Quindi, è possibile che per qualcuno di voi questi esempi non funzionino. In questo caso, tornano utili i programmi che abbiamo utilizzato nel precedente capitolo, "PayPal Payment Data Transfer ( PDT )", dove ci siamo affidati alla libreria PHP cURL, che, se installata correttamente, supporta internamente le transazioni SSL. Vediamone un esempio:

<?php

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

$stdin=fopen("php://input", "r");
$string=fgets($stdin);
fclose($stdin);

$postString = $string."&cmd=".$cmd;

$file=fopen("./ipn", "a");

if($string)
  {

  $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_POST, 1);
  curl_setopt($conn, CURLOPT_POSTFIELDS, $postString);

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

    fwrite($file, curl_error($conn));
    curl_close($conn);

    }
  else
    {

    $arVar = preg_split("/&/", $string);

    if($page == "INVALID")
    { fwrite($file, "Errore nell'acquisizione dei dati\n"); }
    
    else if ($page == "VERIFIED")
      {

      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")
    { fwrite($file, "Grazie per il tuo acquisto\n"); }
    
    else
    { fwrite($file, "Ci dispiace, transazione interrotta\n"); }

                foreach($posted as $key=>$val)
                        { fwrite($file, "$key $val\n"); }

                fwrite($file, "$page\n\n");

                }

        }

fclose($file);
?>

Con la maggior parte di queste righe dovreste, ormai, aver raggiunto una buona dimestichezza. La novità, in questo programma, sono i filehandle che apriamo. I filehandle rappresentano flussi di dati, canali privilegiati per una determinata operazione di input/output:

• il primo filehandle che apriamo è $stdin, che ci serve per catturare il contenuto di STDIN, cioè dell'area di memoria in cui viene memorizzato l'input. L'input memorizzato, in questo caso, è il contenuto del POST inviato al vostro programma dal server PayPal: la stringa contenente tutte le variabili relative alla transazione appena conclusa. Questa stringa è stata già memorizzata, da PHP, nell'array associativo $_POST, come abbiamo già visto nei precedenti articoli, ma noi dobbiamo reinviare, al server PayPal, l'intera stringa. Inutile, quindi, ricomporla da $_POST: è sufficiente catturare la stringa originale. Per catturare la stringa originale, le operazioni da eseguire sono due:

  
  $stdin=fopen("php://input", "r");
  $string=fgets($stdin);
  
  

  Ora, $string contiene la stringa originale. A questo punto, il filehandle può essere chiuso. Al server HTTPS di PayPal, il vostro programma deve reinviare la stessa stringa, con una coppia di variabili in più:

  
  cmd=_notify-validate
  $postString = $string."&cmd=".$cmd;
  
  

  A questo punto, $postString contiene la stringa completa che il vostro programma IPN deve reinviare al server HTTPS di PayPal.

• il secondo filehandle che apriamo è $file, che è un file, chiamato ipn, che si trova nella stessa cartella in cui si trova il vostro programma IPN ( ./ ), nel quale il vostro programma scriverà gli eventuali messaggi da inviarvi. Se il file non esiste, PHP lo creerà ex novo; se, invece, già esiste, PHP aggiungerà ( "a" significa "append" ) le nuove righe di testo ai messaggi già presenti:

  
  $file=fopen("./ipn", "a");
  
  

  Questo filehandle è necessario perchè IPN lavora in modo asincrono rispetto alla transazione appena avvenuta. Quindi, il vostro programma IPN non può stampare a video le informazioni che desidera comunicarvi, perchè voi non sarete, probabilmente, davanti al video, ogni volta in cui IPN verrà attivato. Una volta aperto il filehandle, ogni volta che desiderate inviare un messaggio al file di errore, scrivete:

  
  fwrite($file, "Il vostro errore\n");
  
  

Per il resto, non dovreste incontrare alcuna difficoltà ad interpretare le righe successive, visto che sono operazioni già utilizzate negli articoli precedenti. La sola cosa da ricordare è che quella variabile $page, che contiene la risposta del server HTTPS di PayPal al vostro messaggio di avvenuta ricezione, contiene una sola parola:

	VERIFIED

se il server HTTPS di PayPal ritiene la vostra autenticazione corretta, oppure:

	INVALID

se il server HTTPS di PayPal ritiene che ci sia stato un errore, durante le operazioni IPN.