Introduction à PayPal et à la fonction IPN pour les développeurs

Ma boîte aux lettres est pleine d'emails non sollicités m’invitant à demander un compte marchand pour que mon site puisse accepter les paiements approvisionnés par carte bancaire. Qui aurait besoin d’un tel compte alors qu’il existe PayPal ?

Si votre site doit accepter les paiements électroniques, PayPal est votre meilleur partenaire. Il est inutile de contacter un commercial PayPal ou d'acheter ou installer le moindre logiciel. Il vous suffit d'un compte PayPal et d'une connaissance rudimentaire du langage HTML et du développement de script Web. Vous pouvez utiliser PayPal comme solution de paiement et leur laisser les opérations de paiement plus complexes.

Chaque site peut commencer à collecter des paiements avec les Solutions e-commerce de PayPal. Complétez simplement un formulaire Web. PayPal vous transmettra un bouton que vous pourrez coller sur votre site pour pouvoir commencer à collecter de l'argent. Aucune opération de développement n'est nécessaire. Ce composant des Solutions e-commerce PayPal est appelé Web Accept.

Assistant Web Accept PayPal

Web Accept fonctionne très bien seul mais s'avère encore plus performant lorsqu'il est combiné à un autre composant des Solutions e-commerce PayPal, la notification instantanée de paiement (IPN). Grâce à la IPN, votre site collecte de l'argent via PayPal. Votre serveur est informé de tous les paiements au moment où ils se produisent. Grâce à une interface CGI simple, PayPal envoie à votre serveur tous les détails de paiement dont vous avez besoin pour enregistrer, traiter et livrer des transactions.

Notification instantanée de paiement (IPN) PayPal

Grâce à la combinaison de la IPN et de Web Accept, PayPal fonctionne véritablement comme un service Web facile à utiliser et d'une grande utilité. Les paiements provenant des utilisateurs sont déposés directement sur votre compte PayPal ; aucun intermédiaire ne détient jamais votre argent. PayPal collecte les informations de livraison à votre place, si nécessaire. Vous pouvez également modifier le niveau d'automatisation des opérations de gestion des paiements de votre société. Vous pouvez commencer par une procédure de paiement simple, puis intégrer et automatiser progressivement d'autres fonctionnalités et services PayPal au fur et à mesure que votre activité se développe.

La manière la plus simple de débuter est d'utiliser l'assistant Web Accept PayPal, et de copier le code HTML généré. Modifiez ensuite le code HTML en fonction des besoins de votre site, soit manuellement, soit par le biais d'un programme. Les exemples suivants illustrent cette procédure. Remarque : cet exemple part du principe que je dispose déjà d’un site en état de fonctionnement et d’un compte PayPal.

Supposons que je créé des gadgets et que je souhaite commencer à les vendre sur mon site personnel avec PayPal. Je décris mon produit dans le formulaire Web Accept PayPal, puis PayPal me transmet le bloc de code HTML suivant pour mon site 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="Effectuez vos paiements via PayPal : une solution rapide, gratuite et sécurisée">
</form>


Notez que la variable business pointe vers mon adresse email, qui correspond également à mon compte PayPal. Je peux modifier le nom et le numéro de l'objet, ainsi que son montant (prix).

Le formulaire contient également deux URL, return et cancel_return. Ces URL servent à renvoyer l'utilisateur à mon site dès qu'il termine ou annule la transaction PayPal. Je viens de créer deux pages Web simples pour cet exemple : thanks.html et canceled.html.

Je pourrais m'arrêter là, placer à la va-vite ce code HTML sur une page Web, et commencer à prendre les commandes de gadgets. Chaque fois que quelqu'un clique sur le bouton PayPal et achète un gadget, PayPal m'envoie par email les détails de la transaction et les coordonnées du client. Mais, supposez que je souhaite saisir automatiquement les informations relatives à ce client et à cette transaction dans ma propre base de données. Je peux facilement étendre le bloc de code HTML ci-dessus pour signaler à mon serveur Web toutes les transactions au fur et à mesure qu'elles se produisent. Il suffit simplement d'ajouter un ou plusieurs champs de saisie cachés dans le formulaire HTML :

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

Maintenant, les serveurs PayPal vont appeler mon script CGI, notify.cgi, avec les détails de chaque commande de gadget. Il s'agit d'une notification instantanée de paiement (IPN). PayPal utilise la méthode HTTP POST pour envoyer les Détails de la transaction au script notify.cgi. Ce script renvoie ensuite un écho des données de la transaction à PayPal pour confirmer la validité du paiement. Dans cet exemple simple, le script notify.cgi enregistre ensuite les détails de paiement dans un fichier journal. PayPal ne requiert aucun code de réponse particulier en provenance de notify.cgi ; il suffit donc d'ajouter le mot "foo" à la fin de la communication HTTP.

Voici le bouton PayPal HTML, modifié de façon à pouvoir utiliser la notification instantanée de paiement, ainsi qu'un certain nombre d'autres améliorations :


<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="Acheter des doodads avec 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)

Bien entendu, vous pouvez étendre ce concept de différentes manières et ne pas le limiter au vidage d'un fichier journal. Vous pouvez ainsi vous en servir de l'écriture dans une base de données jusqu'au traitement automatique de la commande et à la livraison d'un produit ou d'un service. Je vous recommande de ne pas compliquer les routines de l'interface PayPal, et d'autoriser une autre procédure à collecter et exécuter la commande. Si votre script CGI est bogué, vous risquez de perdre une transaction. Toutefois, jusqu'à ce que votre script confirme chaque paiement, PayPal tentera de vous tenir informé. Vous pouvez essayer un exemple simple pour voir comment PayPal utilise vos journaux d'accès. Avec ces mêmes lignes, vous pourrez réparer des erreurs plus facilement si votre script peut différencier les transactions uniques des transactions répétées.

Dès que l'utilisateur termine une transaction, PayPal place les détails de la transaction sur mon URL de renvoi. J'ai ainsi remplacé le script thanks.html par le script thanks.cgi. Dans cet exemple, thanks.cgi renvoie simplement l'utilisateur à thanks.html. Vous pouvez étendre cela pour utiliser les détails de la commande dans la page de remerciements afin de proposer un reçu en ligne ou ce que vous voulez.

Voici un autre exemple de script Python simple, 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()

Je ne m'appesantirai pas sur les détails des données de transaction dans cet article. Pour plus d'informations, veuillez vous reporter au tableau relatif aux variables de notification instantanée de paiement sur le site PayPal.

Lorsque PayPal vous indiquera qu’un paiement a été effectué ou annulé, vous saurez comment le gérer. Il peut arriver que PayPal vous indique que l'état d'un paiement est "en attente". Les paiements en attente sont un peu plus difficiles à gérer et l'aide que peut vous apporter PayPal dans cette situation est limitée. D'après la documentation IPN de PayPal concernant les paiements en attente, votre serveur sera averti deux fois : lors de l'initialisation d'un paiement puis lorsque son état passera de "en attente" à "terminé".

Les développeurs Web ont conscience qu'il peut être difficile de réparer des scripts CGI. Malheureusement, PayPal ne vous autorisera pas à vous envoyer un paiement. Il vous faudra dans ce cas créer des objets test et essayer de réparer le script avec un ami pour tester le flux des produits de bout en bout. Cherchez un autre développeur pour vous aider à tester PayPal.

Mon exemple de gadget fonctionne sur le site http://alanb.com/doodads. Essayez de m'acheter un gadget pour le voir en action sous l'angle de l'acheteur. Bien entendu, je ne vous enverrai rien mais le prix de mes gadgets est raisonnable :-)

LIMITATION DE RESPONSABILITE : Le contenu ci-après provient de l'auteur de chaque article, et non de PayPal, Inc. ni de l'un de ses affiliés ou filiales. Les articles peuvent contenir des erreurs. PayPal ne peut être tenu responsable du contenu de ces articles et ne fournira aucune assistance. Le cas échéant, PayPal vous invite à contacter les auteurs des articles pour toute question ou information sur le support technique ou sur les garanties et/ou les licences. Si vous décidez de faire confiance au contenu de ces articles, vous engagez votre propre responsabilité. PayPal n'engage aucune responsabilité concernant les erreurs ou autres dommages pouvant résulter de l'application du contenu des articles, y compris des dommages accessoires, particuliers, indirects ou immatériels. PayPal SE DECHARGE EXPRESSEMENT DE TOUTE GARANTIE concernant ce contenu et l'utilisation qui en est faite.