Introduzione a PayPal e IPN per sviluppatori

La mia posta in arrivo è piena di spamming che mi invita a richiedere un account commerciante, in modo che il mio sito web possa accettare pagamenti con carta di credito. Chi ne ha bisogno, quando c'è PayPal?

Se il tuo sito web richiede i pagamenti elettronici, PayPal è la scelta migliore. Non dovrai contattare il personale di vendita presso PayPal, né dovrai acquistare o installare alcun tipo di software. Ti serviranno soltanto un conto PayPal e alcune conoscenze di base sul linguaggio HTML e sugli script Web. Potrai utilizzare PayPal come soluzione di pagamento preferita e lasciare a loro tutte le complesse procedure di gestione dei pagamenti.

Qualsiasi sito web può iniziare a riscuotere i pagamenti grazie agli strumenti per commercianti PayPal. È sufficiente compilare un modulo online e PayPal ti invierà un pulsante che potrai inserire nel tuo sito web per iniziare subito a riscuotere denaro. Spedizione non necessaria Questo componente degli strumenti per commercianti PayPal è chiamato Web Accept.

Procedura guidata per Web Accept di PayPal

Web Accept funziona benissimo da solo ed è ancora più potente quando è combinato con un altro componente degli strumenti per commercianti PayPal, come la funzione Notifica immediata di pagamento (IPN). Grazie questa funzionalità, il tuo sito web riscuote il denaro tramite PayPal e il tuo server riceve la notifica di tutti i pagamenti man mano che vengono effettuati. Utilizzando una semplice interfaccia CGI, PayPal invia al tuo server tutti i dettagli sul pagamento necessari per registrare, elaborare e completare le transazioni.

Notifica immediata di pagamento di PayPal

Grazie alla combinazione delle funzioni Web Accept e Notifica immediata di pagamento, PayPal offre un servizio online estremamente utile e di facile utilizzo. I pagamenti inviati dagli utenti vengono versati direttamente sul tuo conto PayPal, senza l'intervento di alcun intermediario. Se necessario, PayPal raccoglie per te i dati di spedizione. Inoltre, potrai variare il livello di automazione della tua azienda per quanto riguarda la gestione dei pagamenti. Potrai iniziare con una semplice procedura di pagamento e integrare gradualmente ulteriori funzioni e strumenti PayPal automatizzati nel tempo di pari passo con la crescita della tua azienda.

Il modo più semplice per iniziare consiste nell'eseguire la procedura guidata per Web Accept di PayPal e copiare il codice HTML generato dalla stessa. Quindi, potrai modificare il codice HTML, sia manualmente che tramite programma, per adeguarlo alle caratteristiche del tuo sito. L'esempio riportato di seguito illustra le varie fasi della procedura. Nota: questo esempio presuppone la disponibilità di un sito web già operativo e di un conto PayPal.

Mettiamo il caso che io produca gadget e desideri iniziare a venderli dal mio sito web personale tramite PayPal. Inizierò utilizzando il modulo Web Accept di PayPal per immettere i dettagli relativi al prodotto in vendita e PayPal mi fornirà il seguente codice HTML per il mio sito web:


<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="alanb@alanb.com">
<input type="hidden" name="undefined_quantity" value="1">
<input type="hidden" name="item_name" value="doodad from alanb.com">
<input type="hidden" name="item_number" value="dd01">
<input type="hidden" name="amount" value="4.99">
<input type="hidden" name="return" value="http://alanb.com/doodads/thanks.html">
<input type="hidden" name="cancel_return" value="http://alanb.com/doodads/canceled.html">
<input type="image" border="0" name="submit" src="http://images.paypal.com/images/x-click-but5.gif" alt="Invia i tuoi pagamenti con PayPal. È un sistema rapido, gratuito e sicuro.">
</form>


Tieni presente che la variabile "business" si riferisce al mio indirizzo email, che rappresenta anche il mio conto PayPal. Posso quindi modificare il nome e il numero dell'oggetto e l'importo (il prezzo) secondo le esigenze.

Il modulo include inoltre due URL, denominati return e cancel_return. Questi consentono di reindirizzare l'acquirente al mio sito web per completare o annullare la transazione PayPal. A titolo esemplificativo, ho creato due semplici pagine web: thanks.html e canceled.html.

A questo punto potrei fermarmi, inserire direttamente questo codice HTML in una pagina web e iniziare ad accettare ordini per i gadget. Ogni volta che un cliente clicca il pulsante PayPal e acquista un gadget, PayPal mi invierà i dettagli della transazione e le informazioni di contatto del cliente tramite email. Ipotizzando che io desideri inserire i dati relativi al cliente e alla transazione nel mio database, potrò ampliare facilmente il precedente blocco di codice HTML per inviare una notifica al mio server Web su tutte le transazioni man mano che vengono effettuate. potrò ampliare facilmente il precedente blocco di codice HTML per inviare una notifica al mio server web su tutte le transazioni man mano che vengono effettuate. Basta aggiungere un ulteriore campo di immissione al modulo HTML:

<input type="hidden" name="notify_url" value="http://alanb.com/doodads/notify.cgi">

Da questo momento i server di PayPal richiameranno il mio script CGI, notify.cgi, con i dettagli di ciascun ordine di gadget. Questa procedura è definita Notifica immediata di pagamento. PayPal utilizza il metodo POST HTTP per inviare dettagli della transazione a notify.cgi. Quindi, notify.cgi reinvia i dati della transazione a PayPal per confermare la validità del pagamento. In questo semplice esempio, notify.cgi registra quindi i dettagli del pagamento in un file di cronologia. PayPal non richiede uno speciale codice di risposta da notify.cgi, perciò potrò inserire il termine "foo" al termine della comunicazione HTTP.

Ecco il mio pulsante PayPal HTML, modificato per utilizzare la Notifica immediata di pagamento, assieme a un paio di ulteriori ritocchi:


<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="alanb@alanb.com">
<input type="hidden" name="undefined_quantity" value="1">
<input type="hidden" name="item_name" value="doodad from alanb.com">
<input type="hidden" name="item_number" value="dd01">
<input type="hidden" name="amount" value="1.99">
<input type="hidden" name="return">
value="http://alanb.com/doodads/thanks.cgi">
<input type="hidden" name="cancel_return">
value="http://alanb.com/doodads/canceled.html">
<input type="hidden" name="notify_url" value="http://alanb.com/doodads/notify.cgi">
<input type="image" border="0" name="submit" src="http://images.paypal.com/images/x-click-but5.gif" alt="Acquista gadget con PayPal">
</form>


And here is a simple Python script, notify.cgi:

#!/usr/local/bin/python

# notify.cgi -- CGI script that receives PayPal instant payment notifications
# Alan Braverman
# 27/11/2001

import sys, time, urllib

def confirmPayment():
"Ask PayPal to confirm this payment, return status and detail strings"
paymentDetails = sys.stdin.read() # formatted as a CGI query
confirmPostData = paymentDetails + '&cmd=_notify-validate'
confirmPostRequest = urllib.urlopen(
'http://www.paypal.com/cgi-bin/webscr', confirmPostData)
paymentStatus = confirmPostRequest.read() # either VERIFIED or INVALID
return paymentStatus, paymentDetails

def logPayment(paymentStatus, paymentDetails):
"Write payment status and details to a log file"
logFile = open('payments.log', 'a')
logFile.write('%s %s %s\n' % (
time.ctime(time.time()), paymentStatus, paymentDetails))
logFile.close()

def sendResponse():
"Send a simple HTTP response back to PayPal"
print 'Content-type: text/plain\n\nfoo'

def main(argc, argv):
"Process PayPal Instant Payment Notification CGI call"
paymentStatus, paymentDetails = confirmPayment()
logPayment(paymentStatus, paymentDetails)
sendResponse()

if __name__ == "__main__":
main(len(sys.argv), sys.argv)

Naturalmente, è possibile ampliare questo concetto in diversi modi, oltre a scaricare un file di cronologia: dalla scrittura in un database all'elaborazione automatica dell'ordine e alla consegna di un prodotto o servizio. Io consiglio di mantenere le routine di interfaccia PayPal semplici, per consentire a un altro processo di accettare e completare l'ordine. Se lo script CGI contiene dei bug, si potrebbe perdere una transazione. Tuttavia, fino a quando lo script non avrà confermato ogni pagamento, PayPal continuerà a inviare delle notifiche. Con un semplice esempio sarà possibile verificare gli accessi di PayPal ai relativi registri. In maniera analoga sarà possibile correggere gli errori in modo semplice se lo script è in grado di distinguere le transazioni univoche da quelle ripetute.

Quando l'utente avrà eseguito una transazione, PayPal registrerà i dettagli della transazione nel mio URL di ritorno. Pertanto ho sostituito thanks.html con uno script thanks.cgi. In questo esempio, thanks.cgi reindirizza semplicemente l'utente a thanks.html. È possibile includere inoltre i dettagli dell'ordine nella pagina di ringraziamento per creare una ricevuta online o qualsiasi altra opzione.

Di seguito viene riportato un altro semplice script Python, thanks.cgi:

#!/usr/local/bin/python

def main():
print 'Content-type: text/plain'
print 'Status: 302'
print 'Location: http://alanb.com/doodads/thanks.html'
print

if __name__ == "__main__":
main()

Non scenderò in dettagli riguardo la transazione in questo articolo. Per maggiori informazioni consulta la tabella Variabili di Notifica immediata di pagamento sul sito web PayPal.

Quando PayPal informa che un pagamento è stato eseguito o annullato, l'utente sarà in grado di gestirlo. Ma talvolta PayPal invierà un messaggio relativo a un pagamento "In sospeso". La gestione dei pagamenti in sospeso è leggermente più complicata e l'assistenza di PayPal, in questo caso, è limitata. In base alla documentazione sulla notifica immediata di pagamento di PayPal sui pagamenti in sospeso, il server riceverà una prima notifica quando viene avviato un pagamento e una seconda quando lo stato del pagamento sarà passato da "in sospeso" a "eseguito".

I programmatori Web più esperti sanno già che può risultare complicato eseguire il debug degli script CGI. Purtroppo, PayPal non consentirà di inviare un pagamento a se stessi. Potrebbe essere necessario creare oggetti di prova ed eseguire il debug assieme a un amico per poter verificare il flusso dei prodotti end-to-end. Sarà quindi necessario richiedere l'aiuto di un altro sviluppatore per la verifica di PayPal.

Il mio esempio dei gadget è operativo all'indirizzo http://alanb.com/doodads: pertanto acquistate pure un gadget dal mio sito se desiderate vederlo in azione dal punto di vista di un acquirente. Naturalmente non vi invierò nulla, ma i miei gadget hanno un prezzo ragionevole :-)

LIMITAZIONE DI RESPONSABILITÀ. I seguenti contenuti sono forniti dagli autori degli articoli e non da PayPal, Inc. o dalle sue affiliate o consociate. Gli articoli possono presentare errori e PayPal non garantisce in alcun modo il loro contenuto. PayPal consiglia di contattare direttamente gli autori degli articoli per eventuali domande, per richiedere informazioni sull'assistenza tecnica, sulle garanzie e/o licenze. L'utente accetta di utilizzare il contenuto degli articoli a proprio rischio e pericolo. PayPal non sarà responsabile di eventuali errori o danni causati da tali contenuti, ivi compresi danni accidentali, speciali, indiretti o conseguenti. PayPal DICHIARA ESPRESSAMENTE DI NON OFFRIRE NESSUNA GARANZIA in relazione ai contenuti e all'utilizzo degli stessi.