Mise en place d'une plateforme d'e-commerce avec Ogone

Il faut ensuite introduire les paramètres techniques qui vont permettre au serveur d'Ogone de dialoguer avec le site marchand, via le menu « Configuration --> Informations techniques ». Je joins les impressions d'écran auxquelles vous pouvez vous référer : la configuration est divisée en neuf points.

Voyez les écrans de configuration en détail : écran 1 - écran 2 - écran 3 - écran 4.

1. Choix de la méthode GET ou POST pour le dialogue entre Ogone et le serveur du commerçant (donc, nous) : j'ai choisi POST. Il faut aussi définir les différentes adresses e-mail pour les communications de type administratif et technique.
2. Contrôle de l'origine des demandes de paiement : pour éviter le piratage, Ogone vérifiera que l'adresse IP appelante correspond à une de celles que vous avez indiquées (IP fixe(s) du serveur marchand), et que la page web est bien celle correspondant à l'URL que vous indiquez. Ceci évite que des petits malins téléchargent le formulaire HTML en local et le modifient pour mettre le montant à payer à zéro par exemple…
3. Contrôle des données avant paiement : vous indiquez soit une page web qui contiendra des éléments de contrôle en pseudoXML (format défini par Ogone), soit une chaîne de caractères qui servira à confectionner la signature SHA-1 du formulaire de paiement. Ces points sont expliqués en détail plus bas dans cet article.
4. Ce point définit comment le serveur Ogone retourne le résultat de la transaction financière au marchand : il faudra définir l'URL de la page web « postsale » sur le site marchand, qui sera appelée automatiquement par le serveur d'Ogone (en GET ou POST suivant la config. du point 1), et aussi une adresse e-mail qui servira à recevoir un rapport détaillé sur chaque transaction. Les deux sont vivement conseillés. La création de la page « postsale » est abordée en détail plus loin dans cet article. Ogone demande également à quel moment la page « postsale » doit être appelée : nous choisissons de l'exécuter immédiatement après le paiement du client, afin de prendre en compte le résultat immédiatement pour pouvoir afficher le statut de la vente sur notre site.
5. On paramètre ici les messages affichés au client sur le serveur d'Ogone.
6. Le système demande si on autorise un traitement « offline » de la transaction si le serveur de paiement de la banque n'est pas disponible, je choisis de ne pas le faire.
7. Configuration des requêtes offline, c'est-à-dire survenant après le paiement par le client. C'est une étape importante, car ces informations envoyées par le serveur Ogone contiennent des mises à jour de statut, il faut donc les traiter en utilisant à la fois une requête HTTP vers une page spécifique à créer sur le site marchand, et l'e-mail de confirmation. La page HTML est semblable à la postsale, c'est pourquoi dans notre cas nous emploierons la même page dynamique en PHP.
8. Traitement des paiements par carte de crédit : deux choix possibles, immédiat ou différé. Nous choisissons un traitement « online », pour obtenir le résultat immédiatement.
9. Procédure de paiement : ce point est très important, mais ne concerne que les paiements par carte de crédit. Je vais détailler les trois choix proposés. La « vente directe » revient à valider le paiement immédiatement. Inconvénient : si le client se rétracte par la suite, ou en cas de fraude, il n'est plus possible d'annuler la commande ni surtout d'annuler les frais de commission prélevés par Ogone… C'est pourquoi il est nettement plus intéressant de choisir une des deux autres formules : paiement à la demande ou paiement automatique après un nombre de jours à définir. Dans le premier cas, chaque paiement reste en attente indéfiniment, et doit être validé à la main au cas par cas par le commerçant ; c'est une solution certes très sûre, mais qui demande une intervention manuelle pour chaque transaction. La dernière option consiste à laisser un délai de X jours (au choix, en général on choisit 3, 5 ou 7 jours) et Ogone valide ensuite automatiquement le paiement. Ceci permet, pendant ce délai d'attente, d'intervenir manuellement en forçant une validation immédiate, ou au contraire en annulant la transaction, sans aucuns frais de commission. C'est donc la configuration idéale à mes yeux, que nous avons choisie pour notre site.

Cela se fait via le menu « Configurations --> Moyens de paiement ». La liste des moyens de paiement disponibles apparaît en dessous, il faut les activer puis les configurer un à un. La configuration est généralement assez simple, il suffit la plupart du temps de rentrer un numéro de compte bancaire sur lequel verser l'argent des ventes, ou un numéro de client auprès de l'institution financière. Pour un compte de production réel, Ogone vous met automatiquement en relation par e-mail avec les personnes adéquates dans chaque institution, et vous explique les démarches administratives à effectuer. Il faut en général signer un contrat pour chaque moyen de paiement…

Une fois que l'acheteur a sélectionné et mis dans son panier tous les articles qu'il souhaite et que les frais de port sont connus et calculés (tout cela se fait en général sur une page récapitulative, dernière étape avant paiement effectif chez Ogone), on peut coder le formulaire HTML avec le lien vers Ogone de la manière suivante :

<? // ces constantes sont traditionnellement définies dans un fichier annexe

define("URL", "http://mon.magasin.com/");

define("URLOGONE", "https://secure.ogone.com/ncol/test/orderstandard.asp");

define("PSPID", "masociete");     // identifiant du marchand = login du compte Ogone

define("SHASIG", "masignature");    // chaine de car. pour construire la sig. SHA-1

?>



<form method="post" action="<?=URLOGONE?>">

        <!-- mandatory fields -->            

        <input type="hidden" name="orderID" value="<?=$id_vente?>">

        <input type="hidden" name="pspid" value="<?=PSPID?>">

        <input type="hidden" name="RL" value="ncol_2.0">

        <input type="hidden" name="currency" value="EUR">

        <input type="hidden" name="language" value="fr_FR">

        <? /* il FAUT arrondir à 2 décimales car ogone veut un chiffre rond */ ?>

        <input type="hidden" name="amount" value="<? echo round($prixtot, 2)*100 ?>">



        <!-- optional fields -->

        <? /* page de statut à afficher en cas de réussite ou d'échec : ici tout sur la même page */ ?>

        <input type="hidden" name="accepturl" value="<?=URL?>statut.php">

        <input type="hidden" name="declineurl" value="<?=URL?>statut.php">

        <input type="hidden" name="exceptionurl" value="<?=URL?>statut.php">

        <input type="hidden" name="cancelurl" value="<?=URL?>statut.php">

        



        <? $shastring = $id_vente.(round($prixtot, 2)*100)."EUR".PSPID.SHASIG; ?>

        <input type="hidden" name="SHASign" value="<?=sha1($shastring)?>">

        

        <? /* paramètres supplémentaires facultatifs pour fonctionnement interne */ ?>

        <input type="hidden" name="paramplus" value="toto=blabla&titi=blublu">

        

        <!-- param. de mise en page Ogone -->

        <input type="hidden" name="title" value="Mon magasin virtuel, mon joli titre">

        

        <input type="submit" value="Payer">

</form>

Quelques explications sur les variables PHP présentes dans le code :

• $id_vente est un numéro unique (clé primaire) représentant la commande. Ogone ne peut jamais voir deux commandes différentes avec le même numéro, sinon il refuse en affichant un message d'erreur tout sauf clair… Même une commande annulée par l'acheteur doit donc être enregistrée dans votre base de données, pour ne pas réutiliser le même numéro pour une prochaine commande. Faites également très attention au problème de concurrence, en termes de base de données : si vous générez le numéro vous-mêmes, prenez garde à ce qu'aucun client ne puisse obtenir le même numéro en faisant une transaction avec quelques secondes de décalage sur votre site… La meilleure solution consiste à laisser faire votre SGBD : insérez directement une ligne concernant votre commande dans votre DB avant même de lancer la procédure Ogone ; votre identifiant sera ainsi fixé et ne pourra pas être « volé ». Ensuite quand Ogone vous communique le résultat, faites un update SQL de cette ligne avec le statut du paiement.
• $prixtot : montant total de la vente. S'il y a des frais de transport, pensez à les inclure, idem pour toutes les taxes dues par le client (TVA principalement). Ogone veut voir le prix multiplié par 100 pour supprimer les décimales. Exemple : montant = 125,47 EUR, le nombre à indiquer à Ogone sera 12547. Pour éviter toute surprise lors de la multiplication par 100 (montant affiché par Ogone légèrement différent de celui que vous avez affiché à votre client, dû à un problème d'arrondi), il est primordial de penser à arrondir d'abord le montant à deux décimales avant d'effectuer la multiplication. C'est la raison d'être de la fonction round() dans le code ci-dessus.

L'URL de la page action n'est pas la même en test et en production ! Il suffit de remplacer le mot « test » par « prod ». La page de statut sera abordée en détail plus loin, de même que la signature de contrôle SHA-1. Vous constatez également la présence de deux paramètres supplémentaires : paramplus et title. Paramplus permet de renseigner des champs pour l'usage interne du site marchand. Ces champs ne seront pas touchés par Ogone, qui se contentera de les retransmettre tels quels à la page postsale (appelée automatiquement par Ogone après la transaction), qui pourra donc les traiter comme bon lui semble. L'intérêt pour le marchand est de pouvoir communiquer n'importe quel type d'informations qui lui seraient utiles à sa page postsale (attention : ne pas oublier d'encoder les valeurs de ces champs avec la fonction PHP urlencode()). Enfin le paramètre « title » permet de personnaliser le titre affiché sur les pages du serveur Ogone vues par le client. Il y a bien d'autres paramètres facultatifs disponibles, qui permettent de personnaliser encore plus le traitement, tout est détaillé dans la documentation d'Ogone.

Les champs accepturl, declineurl, etc. sont les pages du site marchand qui vont afficher le statut de la transaction, c'est le point de retour depuis Ogone. À ne pas confondre avec la page postsale qui n'est qu'un traitement batch, sans aucun affichage, destiné uniquement à mettre à jour la base de données du marchand en fonction des résultats envoyés par le serveur de paiement.

Par sécurité, Ogone veut s'assurer que les données transmises par le formulaire vu ci-dessus n'ont pas été trafiquées (ce qui est possible par exemple en copiant la page sur son ordinateur local et en modifiant les champs). Pour cela, il propose deux types de vérification que nous allons aborder. Mais en préambule je vais vous montrer une fonction de contrôle personnalisée, à implémenter sur le serveur du vendeur, et qui sera utilisée plusieurs fois.

III-B-1. Fonction de contrôle de l'IP d'Ogone▲

// ensemble d'IP possibles des serveurs Ogone (normalement dans config.inc.php)

$ipogone = array("212.23.45.96/28", "213.254.248.96/28", "212.35.124.160/28");



function checkIPOgone($ip) {

        global $ipogone;

        

        $result = false;        

        // boucle sur tous les réseaux à vérifier:

        for ($i=0; $i < sizeof($ipogone); $i++) {

                // découpe l'adresse IP source ($ip) et l'adresse du réseau à vérifier ($ipogone[$i])

                // dans leurs 4 composantes :

                if (ereg("^([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)$", $ip, $ipregs) && 

                        ereg("^([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)\/([0-9]+)$", $ipogone[$i], $ogoneRegs)

                        ) {

                        

                        $mask = $ogoneRegs[5];

                        $num = pow(2,32-$mask)-1;   // nombre d'IP possibles

                        if ($ipregs[4] >= $ogoneRegs[4] && $ipregs[4] <= $ogoneRegs[4]+$num &&

                                $ipregs[1] == $ogoneRegs[1] && $ipregs[2] == $ogoneRegs[2] &&

                                $ipregs[3] == $ogoneRegs[3]

                                ) { $result = true; break; }

                }

        }

        return $result;

}

III-B-2. Signature SHA-1▲

<? $shastring = $id_vente.(round($prixtot, 2)*100)."EUR".PSPID.SHASIG; ?>
<input type="hidden" name="SHASign" value="<?=sha1($shastring)?>">

III-B-3. Page de pseudoXML▲

<orderID="12345"
amount="12547"
currency="EUR">

<uncorrect orderid 12345>

<?php

// Vérifie provenance IP = serveur OGONE
if (!checkIPOgone($_SERVER["REMOTE_ADDR"])) die("Remote server not recognized. Access denied.");

// ici : récupération des données de la vente
&#8230;
// $montant correspondra au montant total

if (!$montant) {
?>

<uncorrect orderid : "<?=$_REQUEST["orderID"]?>">

<?
}
else {
?>

<orderID="<?=$_REQUEST["orderID"]?>" 
amount="<?=round($montant, 2)*100?>" 
currency="EUR">

<?
}
?>

Si les contrôles vus au point précédent se sont bien déroulés, le client peut poursuivre son paiement sur le site d'Ogone. Une fois l'opération terminée, Ogone renvoie le résultat ainsi qu'une série d'informations au site marchand sur sa page postsale, telle que définie dans la configuration du compte (point 4). Classiquement la page postsale se contente de stocker toutes ces variables dans sa base de données, comme le montre l'exemple suivant :

<?php

// Vérifie provenance IP = serveur OGONE
if (!checkIPOgone($_SERVER["REMOTE_ADDR"])) die("Remote server not recognized. Access denied.");

require("&#8230;");   // fichier d'inclusion nécessaire
$vente = new Vente();
$zevente = $vente->getVente($_POST["orderID"]);

if ($zevente["statut"] > 0 && ereg("^[0-9]+$", $_POST["STATUS"])) {
        // mise à jour du statut en différé (paiement auto après 3 jours cf config Ogone ou chang. statut manuel sur extranet ogone)
        $oldstatut = $zevente["statut"];
        $vente->changeStatut($_POST["orderID"], $_POST["STATUS"]);
        sendmailStatut($_POST["orderID"], $_POST["STATUS"], $oldstatut);
}
else {
        // mise à jour du statut ogone dans le cas normal (en direct)
        if (eregi("CreditCard", $_POST["PM"])) $pm = $_POST["BRAND"]; else $pm = $_POST["PM"];
        $vente->valideVente($_POST["orderID"], $_POST["amount"], $_POST["STATUS"], $_POST["PAYID"], $pm,
        $_POST["toto"], $_POST["titi"]);
        
        // envoie un mail au client si paiement OK
        if ($vente->statutOK($_POST["STATUS"])) {
                //$zevente = $vente->getVente($_POST["orderID"]);
                $idclient = $zevente["id_client"];
                sendmailok($idclient, $_POST["orderID"]);
        }
}

À noter que les variables envoyées par Ogone le sont en POST, comme on l'a défini dans le premier paramètre de configuration du compte. Ici j'ai illustré le stockage en base de données via un simple appel de classe, qui se charge d'envoyer les requêtes nécessaires au SGBD. À nouveau, je vérifie si l'adresse IP appelante correspond bien au serveur Ogone avant de faire quoi que ce soit. L'appel de cette page est totalement invisible pour le client, qui est pour l'instant toujours sur le site d'Ogone.

Voici la signification des différents paramètres envoyés par Ogone :

• orderID : référence de la commande ;
• amount : montant de la commande, au format décimal normal, non multiplié par 100 ;
• STATUS : valeur numérique qui correspond à l'état du paiement. Voici les principaux codes et leur signification  :
  • 0 ou 1 signifie que l'encodage du paiement n'est pas arrivé à son terme, soit parce qu'il est toujours en cours, soit parce que l'encodeur a abandonné, soit parce qu'une erreur de validation du format des données a empêché de confirmer celui-ci. S'il s'agit d'une erreur de validation, un code d'erreur complémentaire (*) (NCERROR) donne le type d'erreur de validation,
  • 2 : l'acquéreur a refusé l'autorisation,
  • 5 : le paiement est autorisé (uniquement pour les cartes de crédit, dans le cas où on a configuré un mode de paiement avec délai de X jours avant validation),
  • 9 : le paiement est exécuté et validé.
  
  La liste complète de tous les statuts est donnée sur le site d'Ogone ;
• PAYID : référence interne du paiement Ogone. Valeur importante, car elle se retrouvera sur les relevés de compte bancaire du marchand ;
• PM : pour « payment method », c'est une valeur alphanumérique indiquant la méthode de paiement utilisée par le client : « CreditCard » pour tout type de carte de crédit, « DEXIA » pour un paiement par netbanking de la banque Dexia, etc. Dans le cas du paiement par carte de crédit, le champ BRAND contient le nom de l'organisme de crédit (VISA, MasterCard, etc.)
• toto et titi : ce sont les champs supplémentaires du « paramplus », à l'usage exclusif du vendeur. Ils peuvent contenir n'importe quelle information, cela reste toujours la liberté du vendeur.

Rappelons qu'Ogone communique avec le serveur du vendeur dans deux cas :

• directement après paiement du client : c'est le fameux « postsale » donc à ce moment on inscrit le statut dans la base de données ;
• lors d'une validation différée (cas des cartes de crédit si on a configuré un paiement automatique après X jours, ou qu'on valide ou annule le paiement manuellement) : j'ai spécifié que c'est la même page qui devait être appelée, puisque le code est très semblable et les paramètres envoyés par Ogone identiques. Ici le statut existe déjà en base de données, et sera donc mis à jour (ceci permet de différencier le traitement de notre côté). Un paiement par carte de crédit passera donc d'un statut 5 en postsale à un statut 9 après X jours.

Note : il est important d'utiliser les majuscules pour les noms des champs tels qu'envoyés par Ogone, car PHP fait la différence, comme pour les noms de variables.

Nous en arrivons à la fin du processus : le paiement est effectué et le serveur du marchand a été informé du résultat. La dernière étape pour Ogone consiste donc à rediriger le client sur le site du marchand. Il sélectionne une des URL renseignées dans le formulaire de paiement initial (accepturl, declinenurl… ) selon le résultat de la transaction. Dans mon cas toutes ces URL sont identiques, car la page sera toujours grosso modo la même, le code PHP étant à même de différencier l'affichage selon le statut du paiement Ogone qu'il va récupérer dans la base de données (mise à jour précédemment par l'appel à la page postsale). Cette page n'a donc plus aucun lien « technique » avec Ogone, aucun paramètre n'est échangé (puisque tout a déjà été fait), il s'agit juste d'afficher au client la page finale de la vente en rappelant les références qui lui seront utiles. À ce stade, il est aussi classique de lui envoyer un e-mail de confirmation ou lui permettre de sauvegarder et/ou imprimer son bon de commande ou sa facture. Je n'illustre cet aspect d'aucun code étant donné qu'il n'y a rien de particulier à Ogone ici ;-) Je donnerai cependant deux liens qui peuvent être utiles : la classe phpmailer pour l'envoi d'e-mail en PHP, bien plus souple et puissante que la fonction mail() intégrée ; et la classe FPDF pour la conception de documents PDF plus aisée qu'avec les fonctions de bas niveau.