How to easily integrate a PayPal Checkout with PHP

Implémentation

Par où commencer?

Afin de recevoir des payements PayPal, la première chose à faire est de créer un compte. Si vous n'en avez pas, vous pouvez facilement en créer un ici.

Ensuite, commençons par préparer un ensemble de variables qui vont nous permettre de configurer notre classe comme nous le désirons. Nous allons par exemple spécifier l'email du compte PayPal utilisé pour recevoir des payements, la devise à utiliser, et la location du payment. Nous allons faire cela en modifiant le constructeur de la classe, et en remplaçant les variables présentes par celles que nous voulons:

//======================================================================//
//==> Class constructor, with default settings that can be overriden <==//
//======================================================================//
public function __construct($config=""){
 
  //default settings
  $settings = array(
  'business' => 'jeremy@jdmweb.com',         //paypal email address
  'currency' => 'GBP',                       //paypal currency
  'cursymbol'=> '&pound;',                   //currency symbol
  'location' => 'GB',                        //location code  (ex GB)
  'returnurl'=> 'http://mysite/myreturnpage',//where to go back when the transaction is done.
  'returntxt'=> 'Return to My Site',         //What is written on the return button in paypal
  'cancelurl'=> 'http://mysite/mycancelpage',//Where to go if the user cancels.
  'shipping' => 0,                           //Shipping Cost
  'custom'   => ''                           //Custom attribute
  );
 
  //overrride default settings
  if(!empty($config)){foreach($config as $key=>$val){
    if(!empty($val)){ $settings[$key] = $val; }
  }}
 
  //Set the class attributes
  $this->business  = $settings['business'];
  $this->currency  = $settings['currency'];
  $this->cursymbol = $settings['cursymbol'];
  $this->location  = $settings['location'];
  $this->returnurl = $settings['returnurl'];
  $this->returntxt = $settings['returntxt'];
  $this->cancelurl = $settings['cancelurl'];
  $this->shipping  = $settings['shipping'];
  $this->custom    = $settings['custom'];
  $this->items = array();
 
}
 

Ligne 8, changez l'adresse email par la vôtre. Ligne 9, spécifiez le code de la devise à utiliser, (ici GBP). Ligne 10, écrivez le code html du symbole de la devise, (ce paramètre n'est pas absolument nécessaire, mais il est vraiment utile comme nous allons le voir par la suite). Enfin ligne 11, écrivez le code ISO de votre pays.

Les 3 lignes suivantes sont ici pour spécifier comment l'interface PayPal va se comporter une fois que l'utilisateur sera entré afin d'effectuer son payment. Par exemple , PayPal montre un bouton à l'utilisateur une fois la transaction terminée afin de lui permettre de retourner sur votre site. Ligne 12, vous pouvez donc spécifier où ce bouton doit-il renvoyer l'utilisateur, (à quelle adresse de votre site). Ligne 13, vous pouvez définir ce qu'il doit être écrit sur ce bouton, et ligne 14, où l'utilisateur doit être redirigé s'il décide d'annuler la transaction avant de payer.

Lignes 15 et 16, vous trouverez des paramètres avancés comme les frais de ports, si jamais vous devez envoyer des produits à un client, ou le paramètre custom, qui est en fait un champ libre vous permettant de communiquer des informations que vous jugez nécessaires à PayPal. Généralement c'est utilisé pour identifier une commande particulière donc on fait passer un numéro de commande ou de facture.

Voila pour vos informations de base. Nous allons maintenant voir comment à partir de cela, il est possible de créer un panier et comment travailler avec.

Le Panier PayPal

Un panier PayPal est composé de différents éléments. Pour être payé vous devrez entre autres fournir à PayPal un email de compte et une devise (que nous avons déjà configuré), et une liste de produits. Vous pouvez aussi ajouter un frais de port et/ou faire passer un champ libre si vous le désirez.

Dans PayPal, les produits sont quant à eux composé d'au moins 3 éléments: Un nom, qui décrit le produit dans le panier, un prix unitaire, et une quantité. Le prix total pour ce produit sera calculé par PayPal en multipliant le prix unitaire par la quantité, pas besoin de le spécifier.

Pour le besoin de cet exemple, imaginons que nous essayions de vendre des tickets pour un concert. Nous avons 3 classes de tickets différentes, des tickets bronze à £15, silver à £20 et gold à £30. C'est juste pour avoir un exemple, je n'essaye pas de vendre des tickets à qui que ce soit.

Maintenant que nous avons un problème typique, voyons comment il nous est possible de le résoudre en utilisant le manager. Comme vous pouvez le voir dans la démonstration, vous pouvez choisir le nombre de tickets que vous désirez choisir pour chaque catégorie. Une fois le formulaire envoyé, le but est de retrouvé le nombre de tickets désiré depuis les valeurs postées et de créer le panier correspondant. Pour cela, on créée un tableau de tickets suivant les valeurs postée, et suivant la structure des éléments PayPal:

$items = array(
      1=>array(
        "name" => "Gold Tickets",
        "price" => 30,
        "quantity" => (int)htmlentities($_POST["gtkt"],ENT_QUOTES),
        "shipping" => 0
      ),
      2=>array(
        "name" => "Silver Tickets",
        "price" => 20,
        "quantity" => (int)htmlentities($_POST["stkt"],ENT_QUOTES),
        "shipping" => 0
      ),
      3=>array(
        "name" => "Bronze Tickets",
        "price" => 15,
        "quantity" => (int)htmlentities($_POST["btkt"],ENT_QUOTES),
        "shipping" => 0
      )	
);

A partir de ce tableau, on peut clairement voir la structure des éléments, avec pour chaque, un nom, un prix unitaire, et une quantité (égale à la valeur postée), et son prix de livraison (0 étant équivalent à une livraison gratuite). Il est maintenant temps de passer ces valeurs à notre manager afin qu'il construise le formulaire à envoyer à PayPal pour nous. Pour cela, il nous faut tout d'abord créer une instance de la classe, ensuite, on ajout les éléments en appelant la méthode addMultipleItems:

include("lib/paypal_checkout/paypal.php");  //Include the class
$pp = new paypalcheckout();  //Create an instance of the class
$pp->addMultipleItems($items);  //Add all the items to the cart in one go

Si vous êtes intéressé par ce que fait la méthode addMultipleItems, vous pouvez continuer de lire, sinon vous pouvez directement passer à l'étape suivante. Quand on appelle cette méthode, on lui passe un tableau d'éléments. La méthode ensuite parcours ces éléments et les ajoutes à la carte un par un en appelant la méthode addSimpleItem. addSimpleItem vérifie que les noms et quantité de chaque élément sont correctes avant de les ajouter à la carte.

    //=========================================//
    //==> Add an array of items to the cart <==//
    //=========================================//
    public function addMultipleItems($items){
        if(!empty($items)){foreach($items as $item){ //lopp through the items
            $this->addSimpleItem($item);  //And add them 1 by 1
        }}
    }
 
    //=====================================//
    //==> Add a simple item to the cart <==//
    //=====================================//
    public function addSimpleItem($item){		
      if( //Check the quantity and the name
        !empty($item['quantity']) 
        && is_numeric($item['quantity']) 
        && $item['quantity']>0 
        && !empty($item['name'])
      ){ //And add the item to the cart if it is correct
        $items = $this->items;
        $items[] = $item;
        $this->items = $items;
      }
    }
 

Vérifier le contenu de la carte.

Maintenant que les éléments ont été ajouté, vous pouvez vérifier le contenu de la carte à tout moment. Il y a deux façons de faire cela. La première consiste à appeler la méthode getCartContentAsHtml, qui retourne une liste vous montrant les éléments qui seront pris en compte par PayPal. C'est par exemple un excellent moyen de faire un résumé à l'utilisateur avant de finaliser la transaction afin de lui montrer ce pour quoi il va être facturé. Dans notre cas, si l'on achète 4 tickets gold, 2 silver et 2 bronze, la méthode getCartContentAsHtml va retourner ceci:

<ul id="cartcontent">
    <li class="cartitem">4 x "Gold Tickets" at &pound;30 for &pound;120</li>
    <li class="cartitem">2 x "Silver Tickets" at &pound;20 for &pound;40</li>
    <li class="cartitem">2 x "Bronze Tickets" at &pound;15 for &pound;30</li>
    <li class="carttotal">Total: 8 Items for &pound;190</li>
</ul>

Comme vous pouvez le voir dans le code généré, on retrouve pour chaque élément son nom, son prix unitaire, sa quantité, et son prix total. On obtient aussi le montant total de toute la carte.

Si vous souhaitez juste vérifier les éléments qui se trouvent dans la carte, (juste pour tester par exemple), et que vous n'avez pas besoin de tout le formatage html, vous pouvez obtenir le tableau brut d'éléments comme ceci: $items = $pp->items. Le tableau $items contient donc maintenant les éléments de votre carte.

Générer le formulaire PayPal

Comme nous l'avons dis dans l'introduction, PayPal marche avec des formulaires. Il faut construire un formulaire correspondant au service que vous souhaitez obtenir, et vous l'envoyez à PayPal. Quand PayPal reçoit un formulaire, il prépare la transaction demandée, et accompagne l'utilisateur étape par étape.

Le problème de ces formulaires, c'est qu'il ne sont pas très conviénient à construire ni à utiliser, tandis qu'avec le PayPal manager, vous n'avez pas à vous préoccuper des différents type de formulaire, de champs ou de valeurs, le manager va s'occuper de tout le travail à votre place. La seule chose que vous aurez à faire, c'est d'appeler la méthode getCheckoutForm. En se basant sur les éléments présents dans votre carte, la méthode va construire et retourner le formulaire correct.

Dans notre exemple, la méthode getCheckoutForm retournera:

<form id="paypal_checkout" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  <input name="cmd" value="_cart" type="hidden">
  <input name="upload" value="1" type="hidden">
  <input name="no_note" value="0" type="hidden">
  <input name="bn" value="PP-BuyNowBF" type="hidden">
  <input name="tax" value="0" type="hidden">
  <input name="rm" value="2" type="hidden">
 
  <input name="business" value="jeremy@jdmweb.com" type="hidden">
  <input name="handling_cart" value="0" type="hidden">
  <input name="currency_code" value="GBP" type="hidden">
  <input name="lc" value="GB" type="hidden">
  <input name="return" value="http://mysite/myreturnpage" type="hidden">
  <input name="cbt" value="Return to My Site" type="hidden">
  <input name="cancel_return" value="http://mysite/mycancelpage" type="hidden">
  <input name="custom" value="" type="hidden">
 
  <div id="item_1" class="itemwrap">
    <input name="item_name_1" value="Gold Tickets" type="hidden">
    <input name="quantity_1" value="4" type="hidden">
    <input name="amount_1" value="30" type="hidden">
    <input name="shipping_1" value="0" type="hidden">
  </div>
  <div id="item_2" class="itemwrap">
    <input name="item_name_2" value="Silver Tickets" type="hidden">
    <input name="quantity_2" value="2" type="hidden">
    <input name="amount_2" value="20" type="hidden">
    <input name="shipping_2" value="0" type="hidden">
  </div>
  <div id="item_3" class="itemwrap">
    <input name="item_name_3" value="Bronze Tickets" type="hidden">
    <input name="quantity_3" value="2" type="hidden">
    <input name="amount_3" value="15" type="hidden">
    <input name="shipping_3" value="0" type="hidden">
  </div>
 
  <input id="ppcheckoutbtn" value="Checkout" class="button" type="submit">
</form>

Comme vous pouvez le voir, cette méthode retourne pas mal de choses. Voyons donc tout ce que cela veut dire. Lignes 2 à 7, on retrouve des champs et variables spécifiques aux cartes PayPal. Personnellement, je ne les change jamais. Ce sont des constantes spécifiques.

Lignes 9 à 16, on retrouve en fait les variables que l'on a définies au début de ce tutoriel. Par exemple, ligne 9 on a l'email du compte, ligne 11 la devise, 12 la location, et 13,14,15 le comportement du bouton de retour. Si vous souhaitez changer ces valeurs, il vous suffit de changer les attributs de l'instance comme ceci $pp->location="FR" et $pp->currency="EUR" par exemple, si vous souhaitez obtenir des euros depuis la France par exemple, avant d'appeler la méthode getCheckoutForm. Vous pouvez aussi changer les variables définies par défaut bien sur, comme nous l'avons fait au début. Personnellement, je spécifie par défaut les valeurs que j'utilise la plupart du temps, et je change les attributs des instances de classe au cas par cas.

Ensuite, entre les lignes 18 et 35, vous avez les éléments de la carte, avec comme attendu, leur nom, prix unitaire, et quantité, (et la livraison gratuite).

Finalement, ligne 37, on a le bouton d'envoie du formulaire. Si vous souhaitez changer le look de ce bouton, vous pouvez le faire dans la méthode getCheckoutForm ligne 153.

Votre formulaire est maintenant prêt à être envoyé à PayPal. Quand l'utilisateur va presser le bouton d'envoie, il sera redirigé vers PayPal, qui affichera l'écran suivant:

Comme vous pouvez le voir, PayPal a interprété notre requête. Sur cet écran on voit bien que le compte qui recevra les fonds est bien jeremy.@jdmweb.com. Nous avons aussi un détail complet des différents éléments pris en compte, et le prix total qui va être facturé.

Conclusion

Travailler avec des formulaires prends du temps, et ce n'est pas très intuitif. Cette classe PHP vous aidera à gagner du temps et à travailler bien plus facilement avec PayPal grâce à un ensemble de petites méthodes bien pratiques. Vous êtes libre de modifier et étendre le code suivant vos besoins. J'espère que cela vous aidera dans vos futures intégrations PayPal.

Partager:

Vous seriez peut être aussi intéressé par::

Poster un Commentaire

Commentaires récents

But what about crediting the user with the purchase? I have a membership oriented site, so there's nothing to ship. I collect money and need to credit the sale to the user so that I know he has paid. This would be a great guide if you would add that kind of information.

De hey à 02:47 18/08/10 { Répondre }