Tutoriel : Installation d'une solution de paiement en ligne E-Transactions (SIPS-ATOS) sur un serveur Apache avec PHP
Date de publication : 21 juin 2008
Par
Thierry Godin (Voir les autres articles)
Ce tutoriel a pour but d'expliquer l'installation d'un système de paiement en ligne E-Transactions (SIPS-ATOS) sur un site e-commerce utilisant un serveur Linux avec Apache et PHP.
I. Généralités
I-A. Pré-requis
I-B. Introduction
I-C. Présentation de l'API SIPS-ATOS
I-C-1. Contenu du package
I-C-2. Documentation
I-D. Présentation du processus de paiement en ligne
I-D-1. Principe de fonctionnement d'une transaction en ligne (Schéma)
II. Exemple d'installation pour une boutique en ligne avec un caddie simple (1 article)
II-A. Introduction
II-B. Installation des fichiers binaires
II-C. Installation des fichiers de paramètres et des certificats
II-C-1. Fichier pathfile
II-C-2. Certificats : fichiers certif.fr.xxxxxxxxxxxx
II-C-3. Paramètres du commerçant : Fichier parmcom.xxxxxxxxxxxxx
II-C-4. Paramètres du fournisseur : Fichier parmcom.e-transactions
II-C-4-a. Paramètre : PAYMENT_MEANS
II-C-4-b. Paramètre : BLOCK_ORDER
II-C-4-c. Paramètre : HEADER_FLAG
II-C-4-d. Paramètre : TEMPLATE
II-C-5. Autres fichiers et sous-dossiers
II-D. Installation des fichiers PHP
II-E. Intégration du fichier d'appel (call_request.php)
II-E-1. Introduction
II-E-2. Récupération du contenu du caddie
II-E-3. Mise en place des paramètres de transaction
II-E-4. Affichage des moyens de paiement
II-E-5. Le fichier call_request.php complet avec un minimum de commentaires
II-E-6. A propos des paramètres de transaction
II-F. Intégration du fichier de réponse automatique (call_autoresponse.php)
II-G. Intégration du fichier de réponse manuelle (call_response.php)
II-H. Mise en place sur le serveur de production
II-I. Essais de fonctionnement et de paiement (Phase de tests)
II-I-1. Essais avec l'identifiant de commerçant et le certificat de test
II-I-2. Essais avec l'identifiant de commerçant et le certificat final (Phase de pré-production)
II-J. Passage en production
III. Création d'un modèle personnalisé pour la passerelle de paiement (Template)
III-A. Présentation
III-B. Création du fichier HTML
III-C. Template en plusieurs langues
III-D. Un Template pour chaque page
III-E. Utilisation de l'utilitaire de test de Template pour Windows (test_template.exe)
III-F. Intégration du Template à la passerelle de paiement
IV. Conclusion
V. Remerciements
I. Généralités
I-A. Pré-requis
De bonnes connaissances de l'environnement Linux et de PHP sont nécessaires pour pouvoir installer une solution de monétisation sur un site web e-commerce.
PHP :
- Les sessions
- Les tableaux
- L'envoi d'email
- Lire et écrire dans un fichier
LINUX :
- Les chemins
- Les droits des fichiers
I-B. Introduction
Dernière mise à jour : 27/05/2009
Correction d'un faille de sécurité qui aurait pu permettre la prise de contrôle du serveur par le fichier call_autoresponse.php et call_response.php : utilisation de
escapeshellcmd() sur la variable $_POST['DATA'] renvoyée par le serveur de la banque.
Ce tutoriel devrait pouvoir s'appliquer probablement à toute solution de paiement en ligne qui utilise le système SIPS-ATOS, mais pour que l'exemple reste concret, nous allons nous pencher plus particulièrement sur le système E-Transactions du Crédit Agricole.
Nous allons étudier le cas de l'API pour Linux version 6 sur un serveur Linux OpenSuse (10.2) avec Apache (2.2.3) et PHP (5.2.5).
I-C. Présentation de l'API SIPS-ATOS
Dans ce tutorial, le package SIPS-ATOS nous a été délivré en pièce jointe d'un courrier électronique au format *.zip
Vous devez également avoir reçu votre
certificat électronique de commerçant par email. Le certificat est empaqueté dans un fichier exécutable chiffré (Security Box). Vous recevrez par courrier postal le code qui permettra de déchiffrer votre certificat pour l'enregistrer sur votre disque dur.
Nous passerons ici sur toutes les formalités administratives relatives à la création de votre boutique en ligne auprès de votre établissement bancaire (constitution du dossier, présentation de documents administratifs, contrats et signatures) auxquelles vous devrez vous soumettre.
I-C-1. Contenu du package
Décompressez le fichier ZIP dans le répertoire de votre choix sur votre disque dur, puis ouvrez-le. Il devrait contenir :
- Un dossier bin : Il contient les exécutables request et response
- Un dossier documentation : Il contient toute la documentation nécessaire à l'installation ainsi qu''un guide du programmeur et un dictionnaire des données
- Un dossier logo : Il contient les logos de cartes bancaires
- Un dossier param : Il contient un certificat de test, ainsi qu''un fichier de paramètres du commerçant , un fichier de paramètres du fournisseur et le fichier pathfile
- Un dossier sample : Il contient des exemples de fichiers d'appel de requête de transaction et de réponse pour PHP et Perl
- Un dossier test_template : Il contient un Template d'exemple ainsi qu'un utilitaire de test test_template
- Un fichier de version
Dans ce tutoriel, nous laisserons de côtés tous les fichiers Perl (qui sont livrés avec).
Les principaux fichiers sont expliqués en détail plus loin.
I-C-2. Documentation
Ce tutoriel n'a pas pour but de se substituer à la documentation officielle qui vous a été fournie avec l'
API.
N'hésitez pas à lire les différents guides d'installation.
Lorsque vous serez un peu plus familier du système de paiement, vous vous pencherez sûrement sur le Guide du programmeur ainsi que le Dictionnaire des données. Ces documents vous permettront de passer des paramètres supplémentaires lors de la transaction et d'interpréter tous les messages de retour.
Le Dictionnaire des données vous sera également très utile : Chaque champ, chaque paramètre doit observer des règles de syntaxe très strictes.
I-D. Présentation du processus de paiement en ligne
Comme un schéma vaut mieux qu'un long discours, je vous laisse découvrir toute la chaîne du processus de paiement au travers du schéma ci-dessous.
I-D-1. Principe de fonctionnement d'une transaction en ligne (Schéma)

Shéma du déroulement d'une transaction en ligne
- Le client a rempli le caddie et le valide pour procéder au paiement
- Le fichier call_request.php est exécuté et interroge le binaire request
- Affichage des moyens de paiement
- Le client clique sur la carte bancaire. Les données de la transaction sont envoyées au serveur du fournisseur
- Affichage du formulaire de saisie de carte bancaire
- Le client saisit ses numéros de carte puis valide. (Si le client abandonne, il est redirigé vers la page d'annulation : 6a -> 6b)
- Le serveur du fournisseur demande l'autorisation auprès d'une institution financière (réseau bancaire)
- La réponse est traitée par le fournisseur
- La requête est renvoyée vers le fichier de réponse automatique call_autoresponse.php et le fichier de réponse manuelle call_response.php (9 et 9.a)
- Ces deux fichiers sont exécutés et interrogent le binaire response pour interpréter le résultat (10 et 10.a)
- Le fichier de réponse manuelle call_response.php affiche la page de résultat (Succès ou échec)
II. Exemple d'installation pour une boutique en ligne avec un caddie simple (1 article)
II-A. Introduction
Dans cet exemple, considérons que notre boutique permette la vente de logiciels en ligne.
Le client, après s'être identifié, aura rempli un formulaire avec ses données personnelles nécessaires à la facturation, puis aura sélectionné un logiciel dans le catalogue.
Nous considérons que toutes ces données sont stockées dans une session que nous allons résumer ici comme ci-dessous :
| Définition des variables de session |
<?php
$_SESSION['USER_ID'] = "1";
$_SESSION['USER_NOM'] = "Godin";
$_SESSION['USER_PRENOM'] = "Thierry";
$_SESSION['USER_COMPANY'] = "N1bus-Expériences";
$_SESSION['USER_ADRESSE'] = "1, rue Henri Desgranges";
$_SESSION['USER_VILLE'] = "La Rochelle";
$_SESSION['USER_ZIP'] = "17000";
$_SESSION['USER_PAYS'] = "France";
$_SESSION['USER_TEL'] = "33(0) 123 456 789";
$_SESSION['USER_EMAIL'] = "xxxx@xxxx.com";
$_SESSION['CADDIE_ID'] = "1";
$_SESSION['CADDIE_LOG_NOM'] = "PlanningFacile";
$_SESSION['CADDIE_LOG_VERSION'] = "1.1.0.0";
$_SESSION['CADDIE_AMOUNT'] = "3000";
?>
|
Nous considérons également que notre site web est installé dans le répertoire suivant sur le serveur :
/srv/www/htdocs/monsiteweb/
|
Et enfin, nous créons un répertoire qu'on appellera "xpay" pour y stocker les fichiers de configuration et les certificats :
/srv/www/htdocs/monsiteweb/xpay/
|
 |
Nous n'avons pas besoin de connexion sécurisée pour notre boutique :
Toutes les données de la transaction seront chiffrées par le binaire request puis déchiffrées par le binaire response.
La transaction bancaire sera effectuée sur le serveur sécurisé (SSL 128 bit) de notre fournisseur.
Aucune information concernant la carte de crédit du client ne transite par notre serveur.
Pour une plus grande sécurité, vous pouvez évidemment utiliser le protocole HTTPS sur votre boutique,
mais ceci vous obligera à acquérir et/ou installer un certificat SSL et probablement une adresse IP supplémentaire.
|
Nous utiliserons un serveur Linux en local pour les tests, configuré comme le serveur de production afin d'éviter les surprises.
II-B. Installation des fichiers binaires
 |
Avant toute chose, vérifiez la configuration de PHP sur votre serveur avec la commande phpinfo().
|
safe_mode : On
Si la directive safe_mode est à On, vous devez copier les exécutables request et response dans le répertoire défini par la directive safe_mode_exec_dir
safe_mode : Off
Si la directive safe_mode est à Off, vous pouvez copier les exécutables request et response dans le répertoire de votre choix à l'intérieur de votre site ou dans le répertoire cgi-bin.
Vous utiliserez les binaires correspondants à votre noyau Linux (2.4 ou 2.6)
Dans notre exemple :
- La directive safe_mode est à On
- Le répertoire safe_mode_exec_dir est : /srv/www/htdocs/empty/
- Le noyau : 2.6.18.8-0.9
Nous allons donc copier les fichiers binaires request_2.6.9_3.4.2 et response_2.6.9_3.4.2 dans le répertoire : /srv/www/htdocs/empty/
CHMOD : 0755
II-C. Installation des fichiers de paramètres et des certificats
Afin de pouvoir s'y retrouver facilement, nous allons séparer les fichiers de l'
API de paiement des fichiers du site, sauf en ce qui concerne les fichiers PHP d'appel et de réponse que nous mettrons avec les fichiers du site (à la racine).
 |
Prenez soin de mettre des chemins en minuscule, sans accent et surtout sans espace.
Un espace dans le chemin d'un fichier provoquera une erreur
|
Nous allons copier les fichiers et dossiers suivants dans le répertoire : /srv/www/htdocs/monsiteweb/xpay/
- Fichier pathfile
- Fichier parmcom.e-transactions (Fichier de paramètres du fournisseur)
- Fichier parmcom.013044876511111 (Fichier de paramètres pour les tests)
- Fichier certif.fr.013044876511111 (Certificat pour les tests)
- Fichier certif.fr.xxxxxxxxxxxxxxxxxx (Votre certificat de commerçant - avec votre numéro de commerçant délivré par votre fournisseur)
- Dossier logo (Contient les images des cartes bancaires)
Copiez ensuite le fichier parmcom.013044876511111 dans le même répertoire et renommez-le en parmcom.xxxxxxxxxxxxxxxxxx où xxxxxxxxxxxxxxxxxx sera remplacé par le numéro que vous aura fourni votre fournisseur. (Ce sera probablement votre numéro de SIRET).
Ce nouveau fichier devra être modifié : vous mettrez les mêmes paramètres que dans le fichier parmcom.013044876511111 après avoir effectué tous les tests.
 |
Lorsque vous passerez en pré-production puis en production, il faudra utiliser votre certificat et votre fichier parmcom.....
|
II-C-1. Fichier pathfile
Le fichier pathfile (sans extension) contient les chemins vers les fichiers de paramètres, le certificat et le répertoire qui contient les images des cartes bancaires.
| Contenu du fichier pathfile |
#########################################################################
#
# Pathfile
#
# Liste fichiers parametres utilises par le module de paiement
#
#########################################################################
#
#-------------------------------------------------------------------------
# Activation (YES) / Désactivation (NO) du mode DEBUG
#-------------------------------------------------------------------------
#
DEBUG!YES!
# ------------------------------------------------------------------------
# Chemin vers le répertoire des logos depuis le web alias
# ------------------------------------------------------------------------
#
D_LOGO!xpay/logo/!
#
# --------------------------------------------------------------------------
# Fichiers parametres lies a l'api e-transactions paiement
# --------------------------------------------------------------------------
#
# fichier des parametres e-transactions
#
F_DEFAULT!/srv/www/htdocs/monsiteweb/xpay/parmcom.e-transactions!
#
# fichier parametre commercant
#
F_PARAM!/srv/www/htdocs/monsiteweb/xpay/parmcom!
#
# certificat du commercant
#
F_CERTIFICATE!/srv/www/htdocs/monsiteweb/xpay/certif!
#
# --------------------------------------------------------------------------
# end of file
# --------------------------------------------------------------------------
|
Modifiez les chemins sans oublier le ! final.
Vous devez avoir au moins :
- Un chemin vers le répertoire des logos (chemin relatif)
- Un chemin vers le fichier du fournisseur : parmcom.e-transactions!
- Un chemin vers le fichier du commerçant : parmcom!
- Un chemin vers le fichier de certificat : certif!
 |
Passez le paramètre DEBUG à YES pour les tests. Ceci affichera un message explicite au format HTML en cas d'erreur.
Nous repasserons ce paramètre à NO ensuite lors de la mise en pré-production |
II-C-2. Certificats : fichiers certif.fr.xxxxxxxxxxxx
Rien de particulier à dire sur les
certificats.
Vous ne devez pas éditer ces fichiers.
II-C-3. Paramètres du commerçant : Fichier parmcom.xxxxxxxxxxxxx
Le fichier parmcom.xxxxxxxxxxxxx contient les Url de retour de la transaction.
Nous allons éditer le fichier de test parmcom.013044876511111 puis nous recopierons ultérieurement les mêmes Url dans notre fichier parmcom.xxxxxxxxxxxxx
| Contenu du fichier parmcom du commerçant |
###############################################################################
#
# Fichier des parametres du commercant
#
# Remarque : Ce fichier parametre est sous la responsabilite du
# commercant
#
###############################################################################
# URL de retour automatique de la reponse du paiement
AUTO_RESPONSE_URL!http://www.monsite.com/call_autoresponse.php!
# URL de retour suite a paiement refuse
CANCEL_URL!http://www.monsite.com/call_response.php!
# URL de retour suite a paiement accepte
RETURN_URL!http://www.monsite.com/call_response.php!
# END OF FILE
|
 |
Vous devez mettre des Url complètes
|
Modifiez les Url sans oublier le ! final.
Vous devez avoir au moins :
- Une URL vers le fichier de réponse automatique call_autoresponse.php
- Une URL vers le fichier de réponse manuelle call_response.php
- Une URL vers le fichier en cas d'annulation de la part du client. Nous utiliserons ici le même fichier call_response.php
Note:
Nous verrons plus loin que nous pourrons passer ces Url en paramètres lors de la requête directement dans le fichier call_request.php
Ceci peut être utile dans le cas où vous souhaiteriez passer d'autres paramètres dynamiques dans les Url. Dans ce cas, vous prendrez soin de commenter les lignes des Url dans ce fichier en ajoutant un # devant.
II-C-4. Paramètres du fournisseur : Fichier parmcom.e-transactions
Comme dans le fichier parmcom du commerçant, ces paramètres peuvent être passés lors de la requête directement dans le fichier call_request.php
| Contenu du fichier parmcom du fournisseur |
###############################################################################
#
# Fichier des parametres E-TRANSACTIONS
#
# Remarque : Ce fichier parametre est sous la responsabilite du CA
#
###############################################################################
# Mode d'affichage des blocs de paiment
BLOCK_ALIGN!center!
# Ordre d'affichage des blocs de paiement
BLOCK_ORDER!1,2,3,4,5,6,7,8!
# Mode de securite
CONDITION!SSL!
# Code devise ( 978=EURO )
CURRENCY!978!
# flag d'edition des libelles des blocs de paiement
HEADER_FLAG!yes!
# Code langage de l'acheteur (fr=francais)
LANGUAGE!fr!
# Code pays du commercant
MERCHANT_COUNTRY!fr!
# Code langage du commercant
MERCHANT_LANGUAGE!fr!
# Liste des moyens de paiement acceptes
PAYMENT_MEANS!CB,1,VISA,1,MASTERCARD,1!
# Passage en une seule frame securisee au moment du paiement
TARGET!_top!
# Nom du template de la page de paiement e-transactions
TEMPLATE!template_ca_fr!
# Couleur du text (noir)
TEXTCOLOR!000000!
# END OF FILE
|
Note :
La plupart des commentaires vous indiquent la nature des paramètres à configurer.
Toutefois vous trouverez ci-dessous la description de certains paramètres particuliers.
II-C-4-a. Paramètre : PAYMENT_MEANS
C'est le paramètre qui affichera les images des différentes cartes de crédit avec le commentaire.
Il existe 3 blocs de commentaires :
| N° de Block |
Commentaire |
| 1 |
Choisissez un moyen de paiement ci-dessous |
| 2 |
Vous utilisez le formulaire sécurisé standard SSL, choisissez une carte ci-dessous : |
| 4 |
Autres moyens de paiement : |
Exemples :
Si vous renseignez ce paramètre avec les valeurs suivantes :
| PAYMENT_MEANS |
PAYMENT_MEANS!CB,1,VISA,1,MASTERCARD,1!
|
Les trois cartes de crédits seront affichées dans le bloc 1 sous le commentaire correspondant :
Si vous renseignez ce paramètre avec les valeurs suivantes :
| PAYMENT_MEANS |
PAYMENT_MEANS!MASTERCARD,2,CB,2,VISA,2!
|
Les trois cartes de crédits seront affichées dans le bloc 2 sous le commentaire correspondant :
II-C-4-b. Paramètre : BLOCK_ORDER
C'est le paramètre qui détermine l'ordre d'affichage des blocs.
Normalement la valeur par défaut (1,2,3,4,5,6,7,8,9) convient, mais si vous souhaitez afficher le bloc 2 avant le bloc 1, vous devrez alors renseigner ce champ avec les valeurs suivantes (2,1,3,4,5,6,7,8,9)
II-C-4-c. Paramètre : HEADER_FLAG
C'est le paramètre qui permet d'afficher ou masquer les commentaires
Si vous définissez ce paramètre à no , aucun commentaire ne sera affiché dans les blocs.
II-C-4-d. Paramètre : TEMPLATE
C'est le paramètre qui permet de définir le Template (design) qui sera utilisé pour le paiement sur le serveur du fournisseur.
Note :
Pour des raisons évidentes de sécurité, certaines parties de la page de saisie des codes de carte bancaire ne peuvent être modifiées (formulaire). En revanche, il est possible de modifier d'autres parties de la page, d'afficher votre logo, vos textes, vos couleurs.
Nous verrons plus loin comment créer un Template aux couleurs de votre site.
Pour le moment, nous laisserons le Template du fournisseur.
II-C-5. Autres fichiers et sous-dossiers
Le dossier logo :
Le dossier logo contient par défaut les images des 3 cartes bancaires (CB, VISA, MASTERCARD) et des cadenas SSL. Si vous devez utiliser d'autres cartes bancaires, assurez-vous d'y copier les images correspondantes.
Le fichier de logs :
Ce fichier n'existe pas par défaut, il vous faut donc créer un fichier texte vide que vous renommerez en log.txt (ou un autre nom si vous souhaitez).
Il devra pouvoir être accessible en lecture/écriture par nos scripts PHP de paiement (CHMOD 766). Vous pouvez le mettre dans le répertoire de votre choix.
Nous utiliserons ce fichier pour enregistrer toutes les transactions (succès ou échec), ainsi , si aucun email de confirmation n'était délivré après une transaction (panne serveur, réseau, bug ...) , nous aurions tout de même une trace dans le fichier de logs.
 |
De plus, en production nous y retrouverons les éventuels messages d'erreurs de l'API.
|
II-D. Installation des fichiers PHP
Nous allons copier les 3 fichiers PHP à la racine du site dans : /srv/www/htdocs/monsiteweb/
- call_request.php
- call_autoresponse.php
- call_response.php
 |
Astuce
|
Pour que vous ne soyez pas déroutés par le code de votre site et celui du système de paiement, je vous recommande d'inclure ces fichiers dans vos pages. (include()).
En effet, ceci peut s'avérer utile si , pour une quelconque raison, vous étiez amenés à changer de système de paiement.
De plus, ces fichiers généreront juste les images des cartes bancaires pour le call_request.php et des messages de confirmation (succès ou échec) pour le call_response.php
Cela permettra de ne mettre que le code nécessaire au traitement du paiement sans s'occuper de la mise en forme.
Le code sera plus clair et donc plus facile à debugger ou à maintenir.
Dans ce cas, n'oubliez pas de modifier les Url de retour dans le fichier parmcom du commerçant.
II-E. Intégration du fichier d'appel (call_request.php)
II-E-1. Introduction
Ce fichier permet de préparer une transaction avant d'accéder au paiement proprement dit sur le serveur du fournisseur.
C'est également ce fichier qui affichera les moyens de paiement (Cartes bancaires).
Pour que ce tutoriel soit le plus explicite possible, nous allons découper ce fichier en trois parties distinctes :
- La récupération du caddie
- La mise en place des paramètres de transaction
- L'affichage des moyens de paiement
 |
Vous retrouverez le fichier call_request.php complet dans la dernière section de ce chapitre.
|
II-E-2. Récupération du contenu du caddie
Comme nous l'avions défini au début de cet exemple, toutes les informations du client et le contenu du caddie sont déjà enregistrés dans des variables de session.
Nous allons donc récupérer ces variables pour pouvoir les transmettre lors de la transaction. Ceci nous permettra au retour de la transaction, d'envoyer un reçu de paiement détaillé au client par email et éventuellement de mettre notre base de données à jour (Si votre système de boutique en ligne utilise une base de données).
Une précaution, cependant :
Les paramètres de transaction obéissent à des règles syntaxiques très strictes. Par exemple, pour l'avoir déjà expérimenté à mes dépends, un espace dans la valeur d'un paramètre causera une erreur quasi incompréhensible car les données seront tronquées lors du traitement et l'
API renverra un message d'erreur plus ou moins générique difficile à interpréter.
On retrouvera souvent ce type d'erreur lorsque les paramètres contiendront des caractères interdits ou certains caractères de ponctuation.
On peut résoudre le problème une fois pour toutes en utilisant la fonction base64_encode() sur les paramètres susceptibles de contenir ce type de valeurs. On utilisera base64_decode() ensuite lors du retour de la transaction pour récupérer ces valeurs dans leur intégralité.
Tout le contenu du caddie et les infos du client seront passés dans un seul paramètre lors de la transaction, le paramètre :
caddie.
Nous allons donc mettre tout ça dans un tableau puis nous utiliserons la fonction
base64_encode() pour nous assurer que les données ne causent pas d'erreur lors de l'appel de l'
API.
| Préparation du caddie |
<?php
$TheCaddie = array();
$TheCaddie[] = $_SESSION['USER_ID'];
$TheCaddie[] = $_SESSION['USER_NOM'];
$TheCaddie[] = $_SESSION['USER_PRENOM'];
$TheCaddie[] = $_SESSION['USER_COMPANY'];
$TheCaddie[] = $_SESSION['USER_ADRESSE'];
$TheCaddie[] = $_SESSION['USER_VILLE'];
$TheCaddie[] = $_SESSION['USER_ZIP'];
$TheCaddie[] = $_SESSION['USER_PAYS'];
$TheCaddie[] = $_SESSION['USER_TEL'];
$TheCaddie[] = $_SESSION['USER_EMAIL'];
$TheCaddie[] = $_SESSION['CADDIE_ID'];
$TheCaddie[] = $_SESSION['CADDIE_LOG_NOM'];
$TheCaddie[] = $_SESSION['CADDIE_LOG_VERSION'];
$TheCaddie[] = $_SESSION['CADDIE_AMOUNT'];
$NumCmd = "CMD-" . date("YmdHis");
$TheCaddie[] = $NumCmd ;
$xCaddie = base64_encode(serialize($TheCaddie));
?>
|
II-E-3. Mise en place des paramètres de transaction
Maintenant, nous allons préparer les paramètres de la transaction.
Comme nous l'avions vu plus haut, certains paramètres que nous avions définis dans les fichiers parmcom, pouvaient en réalité être définis directement dans ce fichier.
Il existe une multitude de paramètres . Je vous recommande de consulter le Dictionnaire des données si vous voulez peaufiner votre transaction.
Nous allons parler ici que des principaux paramètres.
Vous devez savoir que ce fichier interrogera le binaire request lorsqu'il sera exécuté. On doit donc préciser ici le chemin du binaire et le chemin du fichier pathfile
C'est souvent ici que le bât blesse :
La plupart des erreurs que vous rencontrerez seront des erreurs de "chemin de fichier" ou de "droits des fichiers"
 |
Les paramètres passés dans la variable $parm sont séparés par un espace :
$parm = "parametre1=valeur1 parametre2=valeur2 parametre3=valeur3" etc.
Vous ne devez donc pas mettre d'espace dans les valeurs des paramètres !
|
| Les paramètres de la transaction |
<?php
$parm = "merchant_id=013044876511111";
$parm .= " pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";
$path_bin = "/srv/www/htdocs/empty/request_2.6.9_3.4.2";
$parm .= " merchant_country=fr";
$parm .= " language=fr";
$parm .= " amount=" .$_SESSION['CADDIE_AMOUNT'];
$parm .= " currency_code=978";
$parm .= " transaction_id=" . date ("His");
$Produit = "<tr><td>CHEZN1BUS : LOGICIEL PLANNINGFACILE</td></tr>";
$parm .= " receipt_complement=" . $Produit;
$parm .= " customer_email=" . $_SESSION['USER_EMAIL'];
$parm .= " customer_ip_address=" . $IP;
$parm .= " caddie=" . $xCaddie ;
$SUPERID = session_id();
$parm .= " cancel_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;
$parm .= " automatic_response_url=http://www.monsite.com/call_autoresponse.php";
$parm .= " normal_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;
$parm .= " templatefile=le_template_de_mon_site";
?>
|
II-E-4. Affichage des moyens de paiement
Ici nous allons interroger le binaire
request avec la fonction PHP
exec() puis analyser la réponse renvoyée par l'
API. Si nous n'avons commis aucune erreur dans les étapes précédentes, les cartes bancaires seront affichées.
| Affichage des moyens de paiement |
<?php
$result = exec("$path_bin $parm");
$tableau = explode ("!", "$result");
$code = $tableau[1];
$error = $tableau[2];
$message = $tableau[3];
if (( $code == "" ) && ( $error == "" ) )
{
print ("<center><h1>Erreur appel request</h1></center>");
print ("<p> </p>");
print ("Executable request non trouve : $path_bin");
}
else if ($code != 0){
print ("<center><h1>Erreur appel API de paiement.</h1></center>");
print ("<p> </p>");
print ("<p>Message erreur : $error </p>");
}
else {
print ("<p> </p>");
print ("$message");
print ("<p> </p>");
print("<p align='center'><strong>Montant à payer : </strong> ".
substr($_SESSION['CADDIE_AMOUNT'],0,-2).",".substr($_SESSION['CADDIE_AMOUNT'] ,-2) . " Euros - ");
print("<strong>Numéro de commande : </strong> " . $NumCmd ."</p>");
print("<p align='center'><a href='javascript:history.go(-1)'>RETOUR</a></p>");
}
?>
|
II-E-5. Le fichier call_request.php complet avec un minimum de commentaires
Voici maintenant le fichier complet. Les commentaires superflus ont été retirés.
| call_request.php |
<?php
$TheCaddie = array();
$TheCaddie[] = $_SESSION['USER_ID'];
$TheCaddie[] = $_SESSION['USER_NOM'];
$TheCaddie[] = $_SESSION['USER_PRENOM'];
$TheCaddie[] = $_SESSION['USER_COMPANY'];
$TheCaddie[] = $_SESSION['USER_ADRESSE'];
$TheCaddie[] = $_SESSION['USER_VILLE'];
$TheCaddie[] = $_SESSION['USER_ZIP'];
$TheCaddie[] = $_SESSION['USER_PAYS'];
$TheCaddie[] = $_SESSION['USER_TEL'];
$TheCaddie[] = $_SESSION['USER_EMAIL'];
$TheCaddie[] = $_SESSION['CADDIE_ID'];
$TheCaddie[] = $_SESSION['CADDIE_LOG_NOM'];
$TheCaddie[] = $_SESSION['CADDIE_LOG_VERSION'];
$TheCaddie[] = $_SESSION['CADDIE_AMOUNT'];
$NumCmd = "CMD-" . date("YmdHis");
$TheCaddie[] = $NumCmd ;
$xCaddie = base64_encode(serialize($TheCaddie));
$parm = "merchant_id=013044876511111";
$parm .= " pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";
$path_bin = "/srv/www/htdocs/empty/request_2.6.9_3.4.2";
$parm .= " merchant_country=fr";
$parm .= " language=fr";
$parm .= " amount=" .$_SESSION['CADDIE_AMOUNT'];
$parm .= " currency_code=978";
$parm .= " transaction_id=" . date ("His");
$Produit = "<tr><td>CHEZN1BUS : LOGICIEL PLANNINGFACILE</td></tr>";
$parm .= " receipt_complement=" . $Produit;
$parm .= " customer_email=" . $_SESSION['USER_EMAIL'];
$parm .= " customer_ip_address=" . $IP;
$parm .= " caddie=" . $xCaddie ;
$SUPERID = session_id();
$parm .= " cancel_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;
$parm .= " automatic_response_url=http://www.monsite.com/call_autoresponse.php";
$parm .= " normal_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;
$parm .= " templatefile=le_template_de_mon_site";
$result = exec("$path_bin $parm");
$tableau = explode ("!", "$result");
$code = $tableau[1];
$error = $tableau[2];
$message = $tableau[3];
if (( $code == "" ) && ( $error == "" ) )
{
print ("<center><h1>Erreur appel request</h1></center>");
print ("<p> </p>");
print ("<p>Executable request non trouve : $path_bin</p>");
}
else if ($code != 0){
print ("<center><h1>Erreur appel API de paiement.</h1></center>");
print ("<p> </p>");
print ("<p>Message erreur : $error </p>");
}
else {
print ("<p> </p>");
print ("$message");
print ("<p> </p>");
print("<p align='center'><strong>Montant à payer : </strong> ".
substr($_SESSION['CADDIE_AMOUNT'],0,-2).",".substr($_SESSION['CADDIE_AMOUNT'] ,-2) . " Euros - ");
print("<strong>Numéro de commande : </strong> " . $NumCmd ."</p>");
print("<p align='center'><a href='javascript:history.go(-1)'>RETOUR</a></p>");
}
?>
|
II-E-6. A propos des paramètres de transaction
 |
Important
|
Il existe une hiérarchie dans les fichiers de paramètrages :
parmcom_fournisseur ‹ parmcom_commerçant ‹ call_request
Par conséquent si une valeur est passée dans un champ du fichier call_request.php, une valeur différente passée dans le même champ du fichier parmcom_commerçant ne sera pas prise en compte.
II-F. Intégration du fichier de réponse automatique (call_autoresponse.php)
Ce fichier ne générera aucune sortie HTML vers le navigateur du client. Il sera appelé directement par le serveur du fournisseur
C'est ici que nous allons enregistrer toutes les transactions ou les erreurs dans le fichier de logs et envoyer les emails de confirmation
C'est également ici, que nous pourrons mettre notre base de données à jour le cas échéant.
 |
Attention a bien orthographier le nom du binaire : c'est response et non pas reponse
|
| Récupération de la transaction et traitement de la réponse |
<?php
$message = "message=" . escapeshellcmd($_POST['DATA']);
$pathfile = "pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";
$path_bin = "/srv/www/htdocs/empty/response_2.6.9_3.4.2";
$result = exec("$path_bin $pathfile $message");
$tableau = explode ("!", $result);
$code = $tableau[1];
$error = $tableau[2];
$merchant_id = $tableau[3];
$merchant_country = $tableau[4];
$amount = $tableau[5];
$transaction_id = $tableau[6];
$payment_means = $tableau[7];
$transmission_date = $tableau[8];
$payment_time = $tableau[9];
$payment_date = $tableau[10];
$response_code = $tableau[11];
$payment_certificate = $tableau[12];
$authorisation_id = $tableau[13];
$currency_code = $tableau[14];
$card_number = $tableau[15];
$cvv_flag = $tableau[16];
$cvv_response_code = $tableau[17];
$bank_response_code = $tableau[18];
$complementary_code = $tableau[19];
$complementary_info = $tableau[20];
$return_context = $tableau[21];
$caddie = $tableau[22];
$receipt_complement = $tableau[23];
$merchant_language = $tableau[24];
$language = $tableau[25];
$customer_id = $tableau[26];
$order_id = $tableau[27];
$customer_email = $tableau[28];
$customer_ip_address = $tableau[29];
$capture_day = $tableau[30];
$capture_mode = $tableau[31];
$data = $tableau[32];
$logfile = "/srv/www/htdocs/monsiteweb/xpay/log.txt";
$fp = fopen($logfile, "a");
if (( $code == "" ) && ( $error == "" ) )
{
fwrite($fp, "#======= Le : " . date("d/m/Y H:i:s") . " ========#\n");
fwrite($fp, "Erreur appel response\n");
fwrite($fp, "Executable response non trouvé : $path_bin \n");
fwrite($fp, "-------------------------------------------\n");
}
else if ( $code != 0 ){
fwrite($fp, "#======= Le : " . date("d/m/Y H:i:s") . " ========#\n");
fwrite($fp, "Erreur appel API de paiement.\n");
fwrite($fp, "Message erreur : $error \n");
fwrite($fp, "-------------------------------------------\n");
}
else {
if($bank_response_code == "00"){
$arrayCaddie = unserialize(base64_decode($caddie));
$DatePay = substr($payment_date, 6, 2) . "/" . substr($payment_date, 4, 2) . "/"
. substr($payment_date, 0, 4) ;
$HeurePay = substr($payment_time, 0, 2) . "h " . substr($payment_time, 2, 2) . ":"
. substr($payment_time, 4, 2) ;
$Sujet = "Confirmation de votre paiement en ligne [MONSITE.COM]";
$Msg.= "### CECI EST UN MESSAGE AUTOMATIQUE . MERCI DE NE PAS Y RÉPONDRE ###\n\n";
$Msg.= "Bonjour,\n";
$Msg.= "Veuillez trouver ci-dessous le reçu de votre paiement en ligne sur MONSITE.COM \n\n";
$Msg.= "Prenez soin d'imprimer ce message et de le joindre à votre facture.\n";
$Msg.= "Ces documents vous seront indispensables en cas de réclamation.\n\n";
$Msg.= "DÉTAIL DE VOTRE COMMANDE \n";
$Msg.= "------------------------------------------------------------\n\n";
$Msg.= "NUMÉRO DE COMMANDE = " . $arrayCaddie[14] . " \n";
$Msg.= "DATE DE LA TRANSACTION = $DatePay à $HeurePay \n";
$Msg.= "ADRESSE WEB DU COMMERCANT = WWW.MONSITE.COM \n";
$Msg.= "IDENTIFIANT COMMERCANT = $merchant_id \n";
$Msg.= "REFERENCE DE LA TRANSACTION = $transaction_id \n";
$Msg.= "MONTANT DE LA TRANSACTION = " . substr($amount,0,-2) . "," . substr($amount ,-2)
. " euros \n";
$Msg.= "NUMERO DE CARTE = $card_number \n";
$Msg.= "AUTORISATION = $authorisation_id \n";
$Msg.= "CERTIFICAT DE LA TRANSACTION = $payment_certificate \n\n";
$Msg.= "NOM = " . $arrayCaddie[1] . " \n";
$Msg.= "PRÉNOM = " . $arrayCaddie[2] . " \n";
$Msg.= "SOCIÉTÉ = " . $arrayCaddie[3] . " \n";
$Msg.= "ADRESSE = " . $arrayCaddie[4] . " \n";
$Msg.= "VILLE = " . $arrayCaddie[5] . " \n";
$Msg.= "CODE POSTAL = " . $arrayCaddie[6] . " \n";
$Msg.= "PAYS = " . $arrayCaddie[7] . " \n";
$Msg.= "TÉLÉPHONE = " . $arrayCaddie[8] . " \n\n";
$Msg.= "LOGICIEL = " . $arrayCaddie[11] . " \n";
$Msg.= "VERSION = " . $arrayCaddie[12] . " \n";
$Msg.= "------------------------------------------------------------\n\n";
$Msg.= "http://www.monsite.com\n\n";
$Msg.= "Merci de votre confiance \n";
mail($customer_email , $Sujet, $Msg, 'From: shop@monsite.com');
mail('xxxxx@xxxxx.fr' , $Sujet, $Msg, 'From: shop@monsite.com');
}
fwrite( $fp, "#======================== Le : " . date("d/m/Y H:i:s") . " ====================#\n");
fwrite( $fp, "merchant_id : $merchant_id\n");
fwrite( $fp, "merchant_country : $merchant_country\n");
fwrite( $fp, "amount : $amount\n");
fwrite( $fp, "transaction_id : $transaction_id\n");
fwrite( $fp, "transmission_date: $transmission_date\n");
fwrite( $fp, "payment_means: $payment_means\n");
fwrite( $fp, "payment_time : $payment_time\n");
fwrite( $fp, "payment_date : $payment_date\n");
fwrite( $fp, "response_code : $response_code\n");
fwrite( $fp, "payment_certificate : $payment_certificate\n");
fwrite( $fp, "authorisation_id : $authorisation_id\n");
fwrite( $fp, "currency_code : $currency_code\n");
fwrite( $fp, "card_number : $card_number\n");
fwrite( $fp, "cvv_flag: $cvv_flag\n");
fwrite( $fp, "cvv_response_code: $cvv_response_code\n");
fwrite( $fp, "bank_response_code: $bank_response_code\n");
fwrite( $fp, "complementary_code: $complementary_code\n");
fwrite( $fp, "complementary_info: $complementary_info\n");
fwrite( $fp, "return_context: $return_context\n");
fwrite( $fp, "caddie : \n");
fwrite( $fp, "----------- \n");
for($i = 0 ; $i < count($arrayCaddie); $i++){
fwrite( $fp, $arrayCaddie[$i] . "\n");
}
fwrite( $fp, "-------------------------------- \n");
fwrite( $fp, "receipt_complement: $receipt_complement\n");
fwrite( $fp, "merchant_language: $merchant_language\n");
fwrite( $fp, "language: $language\n");
fwrite( $fp, "customer_id: $customer_id\n");
fwrite( $fp, "order_id: $order_id\n");
fwrite( $fp, "customer_email: $customer_email\n");
fwrite( $fp, "customer_ip_address: $customer_ip_address\n");
fwrite( $fp, "capture_day: $capture_day\n");
fwrite( $fp, "capture_mode: $capture_mode\n");
fwrite( $fp, "data: $data\n");
fwrite( $fp, "---------------------------------------------------------\n\n");
}
fclose($fp);
?>
|
 |
La réponse automatique est délivrée en phase de test de la même façon qu'en phase de production.
|
II-G. Intégration du fichier de réponse manuelle (call_response.php)
Ce fichier affiche le résultat de la transaction sur l'ordinateur du client.
Vous pouvez agrémenter les messages afin de les rendre plus conviviaux pour vos clients.
| Récupération de la transaction,traitement et affichage de la réponse |
<?php
$message = "message=" . escapeshellcmd($_POST['DATA']);
$pathfile = "pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";
$path_bin = "/srv/www/htdocs/empty/response_2.6.9_3.4.2";
$result = exec("$path_bin $pathfile $message");
$tableau = explode ("!", $result);
$code = $tableau[1];
$error = $tableau[2];
$merchant_id = $tableau[3];
$merchant_country = $tableau[4];
$amount = $tableau[5];
$transaction_id = $tableau[6];
$payment_means = $tableau[7];
$transmission_date = $tableau[8];
$payment_time = $tableau[9];
$payment_date = $tableau[10];
$response_code = $tableau[11];
$payment_certificate = $tableau[12];
$authorisation_id = $tableau[13];
$currency_code = $tableau[14];
$card_number = $tableau[15];
$cvv_flag = $tableau[16];
$cvv_response_code = $tableau[17];
$bank_response_code = $tableau[18];
$complementary_code = $tableau[19];
$complementary_info = $tableau[20];
$return_context = $tableau[21];
$caddie = $tableau[22];
$receipt_complement = $tableau[23];
$merchant_language = $tableau[24];
$language = $tableau[25];
$customer_id = $tableau[26];
$order_id = $tableau[27];
$customer_email = $tableau[28];
$customer_ip_address = $tableau[29];
$capture_day = $tableau[30];
$capture_mode = $tableau[31];
$data = $tableau[32];
if (( $code == "" ) && ( $error == "" ) ){
print ("<center><h1>Erreur appel response</h1></center>");
print ("<p>Executable response non trouve : $path_bin </p>");
}
else if ( $code != 0 ){
print ("<center><h1>Erreur appel API de paiement.</h1></center>");
print ("<p>Message erreur : $error </p>");
}
else {
if($bank_response_code == "00"){
print("<center><h1>Merci</h1></center>");
print("<p>Votre paiement a été accepté par notre établissement bancaire</p>");
print("<p>Un message électronique vous a été envoyé <br />");
print("il contient le reçu de la transaction et le détail de votre commande</p>");
print("<p>Merci de votre confiance</p>");
}
else{
print("<center><h1>Votre paiement a été refusé par notre établissement bancaire</h1></center>");
}
if($response_code == "17"){
print("<center><h1>Transaction annulée par l'utilisateur</h1></center>");
}
}
?>
|
Vous pouvez afficher différents messages d'erreurs en fonction du code de réponse de la banque (bank_response_code) dont voici quelques significations :
| bank_response_code |
Signification |
| 00 |
Transaction approuvée ou traitée avec succès |
| 05 |
Ne pas honorer (paiement refusé) |
| 12 |
Transaction invalide |
| 13 |
Montant invalide |
| 30 |
Erreur de format |
| 33 |
Date de validité de la carte dépassée |
| 43 |
Carte volée |
| 51 |
Provision insuffisante ou crédit dépassé |
| 54 |
Date de validité de la carte dépassée |
| 61 |
Dépasse la limite du montant du retrait |
| 63 |
Règles de sécurité non respectées |
| 90 |
Arrêt momentané du système |
Vous retrouverez le tableau complet des codes de réponses dans le Dictionnaire des données
Vous pourrez donc très facilement traiter la réponse avec un switch() :
| switch($bank_response_code) |
<?php
switch($bank_response_code){
case "00" :
print("<p>Votre paiement a été accepté par votre établissement bancaire</p>");
break;
case "05" :
print("<p>Votre paiement a été refusé par votre établissement bancaire</p>");
break;
case "33" :
print("<p>La date de validité de votre carte bancaire est dépassée</p>");
break;
default : print("<p>La transaction n'a pu aboutir suite à un problème technique</p>");
}
?>
|
II-H. Mise en place sur le serveur de production
Maintenant que tous nos fichiers on été édités, vous pouvez déjà effectuer des tests depuis votre serveur de test. Seules les URL de retour ne fonctionneront pas encore, mais ceci vous permettra déjà d'afficher les cartes bancaires et d'être renvoyé sur la passerelle de paiement du fournisseur.
Comme nous utilisons toujours les fichiers de tests, vous serez redirigés sur une passerelle prévue à cet effet. Aucun débit ne sera effectué et certaines erreurs pourront même apparaitre directement sur la passerelle.
Une fois que ces premiers tests ont été réalisés et que vous avez vu apparaitre les cartes bancaires et que vous avez pu accéder à la passerelle de paiement, nous allons transférer tout ceci par FTP sur le serveur de production.
 |
Rappelez-vous de mettre les fichiers aux bons emplacements sur le serveur et assurez-vous que les binaires aient les droits d'exécution
et que le fichier de log ait les droits en lecture / écriture.
|
II-I. Essais de fonctionnement et de paiement (Phase de tests)
II-I-1. Essais avec l'identifiant de commerçant et le certificat de test
Pour les tests, c'est vous qui jouerez le rôle du client.
Remplissez votre caddie puis vérifiez que les cartes bancaires apparaissent sur le site puis accédez à la passerelle de paiement de test.
C'est Maintenant que vous allez réellement pourvoir vérifier que les réponses automatiques et manuelles fonctionnent correctement.
C'est également maintenant que vous pourrez vérifier que votre fichier de logs enregistre bien les erreurs ou les transactions.
 |
Vous devez utiliser le Template du fournisseur lors des tests. Si vous avez déjà passé votre Template en paramètre dans le fichier call_request.php , passez la ligne en commentaire.
|
Les simulations de paiement :
Pour simuler le paiement, vous pouvez entrer n'importe quel numéro de carte bancaire (Compris entre 10 et 19 chiffres). La réponse du serveur sera simulée en fonction des deux derniers numéros de la carte. Prenez soin tout de même de mettre une date de validité ultérieure à la date du jour pour éviter les erreurs.
Exemples :
| Numéro de carte |
Code réponse |
| 123123123123300 |
00 : paiement accepté |
| 123123123123305 |
05 : paiement refusé |
Vous pouvez simuler d'autres réponses en vous référant au Dictionnaire des données : Voir les codes de réponse bancaire (champ bank_response_code)
Cas des cartes avec cryptogramme visuel :
Certaines cartes comme CB, VISA et MASTERCARD nécessitent la saisie d'un cryptogramme visuel (clé à trois chiffres au dos de la carte).
Ceci correspond au champ cvv_response_code
Effectuez des tests en modifiant les 2 derniers chiffres comme ci-dessous :
| Cryptogramme |
cvv_response_code |
Signification |
| 100 |
4D |
Numéro de contrôle correct |
| 140 |
4D |
Numéro de contrôle correct |
| 150 |
50 |
Numéro de contrôle non traité |
| 153 |
53 |
Numéro de contrôle absent de la demande d'autorisation |
| 155 |
55 |
La banque du client n'est pas certifiée, le contrôle n'a pu être effectué |
Tout cryptogramme dont les deux derniers chiffres diffèrent de 00, 40, 50, 53 et 55 amène à un cvv_response_code égal à 4E : Numéro de contrôle incorrect.
II-I-2. Essais avec l'identifiant de commerçant et le certificat final (Phase de pré-production)
Si tous les tests précédents ont réussi, il est temps maintenant de faire les tests avec votre propre identifiant commerçant :
C'est la phase de pré-production.
Pour cela, vous devez donc modifier le fichier call_request.php . Il ne sera d'ailleurs pas nécessaire de modifier les fichiers de réponse (call_autoresponse.php et call_response.php) puisque votre identifiant commerçant (merchant_id) est déjà intégré dans la réponse du serveur (variable DATA chiffrée)
 |
Je vous recommande de laisser le paramètre du commerçant de test et de le passer en commentaire puis d'ajouter
votre paramètre de commerçant comme le montre le code ci-dessous. En cas de problème vous aurez juste à
commenter/dé commenter le commerçant voulu afin d'effectuer des corrections et de nouveaux tests.
|
| Modifier le paramètre du commerçant (call_request.php) |
<?php
$parm = "merchant_id=xxxxxxxxxxxxxxxx";
?>
|
 |
A partir de ce moment, vous êtes sur la passerelle de paiement réelle !
|
Pour effectuer vos tests, je vous recommande de définir le montant du caddie à 1,00 euro dans le call_request.php comme dans l'exemple ci-dessous :
| Définir le montant de la transaction pour les tests (call_request.php) |
<?php
$parm .= " amount=100";
?>
|
(Vérifiez le montant minimum pour les tests dans la documentation fournie par votre fournisseur)
Vous devez effectuer vos tests de paiement avec une carte bancaire réelle
Rassurez-vous : votre compte bancaire ne sera pas débité
II-J. Passage en production
 |
Pour pouvoir passer en phase de Production réelle (avec débit de carte bancaire),
vous devez avoir effectué au moins un test et que le paiement ait réussi pendant la phase de pré-production.
|
Vous devrez également envoyer par fax un document (PV de recette) en précisant la date à laquelle vous souhaitez que votre système passe en mode de production.
Votre fournisseur, après avoir fait les vérifications nécessaires vous confirmera la date d'ouverture de votre boutique en ligne.
 |
N'oubliez pas :
|
- De repasser le paramètre DEBUG à NO dans le fichier pathfile
- De redéfinir le paramètre amount dans le fichier call_request.php
 |
A partir de la date de passage en production confirmée par votre fournisseur, les transactions deviennent réelles : les cartes bancaires sont débitées.
|
III. Création d'un modèle personnalisé pour la passerelle de paiement (Template)
Si vous souhaitez que vos clients retrouvent l'interface graphique de votre site, vous avez la possibilité de créer un modèle (Template) au format HTML avec vos images, couleurs et logos.
III-A. Présentation
Dans le package initial que nous avait envoyé notre fournisseur, vous trouverez le dossier test_template .
(Il se peut que ce dossier vous soit livré séparément dans un autre package). Ouvrez ce dossier, vous trouverez à nouveau 2 dossiers, test_template_java et test_template_windows.
Ouvrez le dossier test_template_windows, il devrait contenir :
- Les images des cartes bancaires et des clefs/cadenas
- Un fichier HTML cryptogramme.fr.html (C'est le popup qui apparait lorsqu'on clique sur le ? à coté du champ de saisie du cryptogramme)
- Un Template d'exemple : merchant_template (sans extension)
- L'exécutable test_template.exe qui nous permettra de vérifier que notre Template est conforme.
Nous n'allons étudier ici que la version pour Windows. Les utilisateurs de Java devront utiliser le fichier test_template.class.
Les normes à respecter pour le Template en HTML seront de toutes façons les mêmes, que vous utilisiez Windows ou Java.
En réalité, vous pouvez créer un Template pour chaque page de la passerelle de paiement :
- Page de saisie des codes de carte bancaire
- Page de résultat dans le cas d'un paiement accepté
- Page de résultat dans le cas d'un paiement refusé
 |
Pour ceux qui ont déjà vu les pages des passerelles de paiement par défaut, je vous recommande de créer au moins un
Template commun. Ceci ne vous prendra pas énormément de temps et permettra au client de voir une page moins austère que l'originale.
|
Dans cet exemple, nous créerons un seul Template qui sera commun à toutes les pages.
III-B. Création du fichier HTML
Ce qu'il faut savoir :
- Le logo du fournisseur (ici E-Transactions) doit être intégré obligatoirement au Template
- Vous pouvez joindre des images mais celles-ci ne doivent en aucun cas être placées dans un sous-répertoire différent.
- Le nom du Template ne doit pas contenir d'extension : nom en minuscule, sans accent, sans espace
- Vous pouvez utiliser des styles CSS mais ceux-ci doivent être précisés directement dans le Template (pas de feuille de style)
- Vous ne devez pas mettre les balises : <html>, <head>, <form>, </form>, </head>, </body> et </html>. Ces balises seront ajoutées automatiquement par le serveur
- Pour en avoir fait l'expérience : n'utilisez pas de balises XHTML . Utilisez les balises HTML standard. Certaines balises comme les balises de fermeture : /> provoquent une erreur au moment du test.
Comment procéder :
Le plus simple est d'utiliser votre éditeur Web habituel pour céer votre page.
Vous devez sauvegarder la page Html dans le répertoire test_template . Vous devez également ajouter toutes les images directement dans ce dossier. Pour qu'il n'y ait pas de confusion possible, nommez vos images en y ajoutant un préfixe significatif.
Par exemple:
Nous supposons que votre boutique en ligne s'appelle monsiteweb.com , mettez un préfixe du style : tplmonsiteweb_image.jpg
Une fois que votre page est terminée, il vous suffira de retirer les balises Html interdites puis de renommer votre fichier html en tplmonsiteweb sans extension.
Globalement :
Vous pouvez créer n'importe quelle page Html tant qu'elle respecte les conditions ci-dessus.
Il faut juste que dans une cellule (si vous utilisez les tableaux) ou un DIV , apparaisse la balise [SIPS] . C'est cette balise qui affiche le code du fournisseur (Formulaires, résultat et autres).
Voici un exemple de Template basique :
| Contenu du fichier Template tplmonsiteweb (sans extension) |
<style type="text/css">
<!--
.all {
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 10px;
font-style: normal;
line-height: normal;
font-weight: normal;
color: #000000;
text-decoration: none;
width: 900px;
text-align:left;
border: 1px solid #cccccc;
}
.header {
background-image: url(tplmonsiteweb_header.jpg);
background-repeat: no-repeat;
height:121px;
background-position: center;
}
.atos{
height: 300px;
padding-left: 10%;
padding-right: 10%;
}
.footer{
background-image:url(logo-etransactions.gif);
height: 100px;
text-align: center;
background-position: center;
background-repeat: no-repeat;
}
-->
</style>
<body>
<div align="center">
<div class="all">
<div class="header"></div>
<div class="atos">[SIPS]</div>
<div class="footer"></div>
</div>
</div>
|
Et voici un aperçu de la page lorsqu'elle est testée au moyen de l'utilitaire test_template.exe (que nous verrons dans le chapitre suivant) :
III-C. Template en plusieurs langues
Si votre boutique en ligne comporte plusieurs langages, vous pouvez également créer différents Template pour ces langages.
Par exemple, si vous utilisez le français et l'anglais dans votre boutique, vous pouvez créer un Template tplmonsiteweb.fr et tplmonsiteweb.en
Il faudra renseigner le champ TEMPLATE dans le fichier parmcom.e-transactions avec le Template correspondant . Le plus facile étant de le faire dynamiquement dans le fichier call_request.php selon la langue utilisée par le client via le paramètre templatefile
III-D. Un Template pour chaque page
Si vous ne souhaitez pas utiliser un Template commun à toutes les pages, vous devrez alors confectionner 3 Template :
- Un pour la page de saisie des codes bancaires
- Un pour la réponse en cas de succès
- Un pour la réponse en cas d'échec
Chaque Template devra porter le même nom mais avec un extension différente en fonction de la page à laquelle il sera appliqué :
Extension en MAJUSCULE obligatoire !
- tplmonsiteweb.CAPTURE
- tplmonsiteweb.ACCEPTED
- tplmonsiteweb.REFUSED
III-E. Utilisation de l'utilitaire de test de Template pour Windows (test_template.exe)
Cet utilitaire simule l'affichage du serveur du fournisseur.
L'affichage peut être légèrement différent par rapport au serveur de la passerelle de paiement , c'est pourquoi vous devrez également vérifier l'aspect de vos Template sur le serveur lors de la phase de pré-production, une fois que votre Template aura été installé par votre fournisseur.
 |
Vous ne pouvez pas effectuer de tests avec vos Template sur le serveur du fournisseur pendant la phase de test. Vous devez être en phase de pré-production
|
Tester le Template :
Supposons que vous ayez copié le dossier test_template à la racine de votre disque C:\ . Vous avez donc mis votre Template et vos images dans ce même dossier.
Sous Windows XP :
- Cliquez sur le bouton Démarrer dans la barre des tâches
- Cliquez sur Exécuter
- Entrez la commande cmd puis cliquez sur le bouton OK
- Une fenêtre d'invite de commande apparait.
- Saisissez le texte cd c:\ puis frappez la touche Entrée de votre clavier
- Saisissez ensuite le texte cd c:\test_template puis frappez la touche Entrée de votre clavier
- A ce moment nous sommes positionnés dans le répertoire qui nous intérresse.
La syntaxe de base :
test_template nom_du_template OPTION > fichier_sortie.html
Le test génère un fichier Html de la page du fournisseur avec le Template incorporé.
Vous pouvez maintenant tester l'affichage de votre Template avec les commandes ci-dessous en validant à chaque fois avec la touche Entrée de votre clavier :
| Tester la page de saisie des codes de carte bancaire |
test_template tplmonsiteweb CARD > tpl_card.html
|
| Tester la page de réponse en cas de succès de la transaction |
test_template tplmonsiteweb ACCEPTED > tpl_accepted.html
|
| Tester la page de réponse en cas d'échec de la transaction |
test_template tplmonsiteweb REFUSED > tpl_refused.html
|
A chaque fois , vous devez ouvrir le fichier html correspondant dans votre navigateur pour le visualiser.
 |
D'autres tests et options sont disponibles.
Consultez le Guide de personnalisation des pages pour des informations détaillées.
|
III-F. Intégration du Template à la passerelle de paiement
Avant de pouvoir intégrer le Template à la passerelle de paiement, vous devez l'envoyer par email à votre fournisseur.
Envoyez juste votre fichier Template et n'oubliez pas d'envoyer vos images.
Précisez dans le message votre identifiant (merchant_id) ainsi que le nom de domaine de votre boutique en ligne.
Certains fournisseurs vous enverront un email de confirmation pour vous préciser la date à laquelle le Template sera installé, d'autres fournisseurs vous contacteront seulement en cas d'échec de l'installation du Template.
Une fois que le Template est installé sur le serveur du fournisseur :
Vous pouvez préciser le Template à utiliser pour votre passerelle de paiement de l'une ou l'autre des méthodes ci-dessous :
Dans le fichier parmcom.e-transactions :
| Template dans le fichier parmcom du fournisseur |
# Nom du template de la page de paiement e-transactions
#TEMPLATE!template_ca_fr!
TEMPLATE!tplmonsiteweb!
|
Dans le fichier call_request.php :
| Template dans le fichier call_request.php |
<?php
$parm .= " templatefile=tplmonsiteweb";
?>
|
N'hésitez pas à faire des tests pendant que vous êtes en pré-production pour affiner vos Template si besoin.
IV. Conclusion
Pour une plus grande sécurité de vos scripts , ne conservez pas les noms des fichiers PHP (call_request.php, call_autoresponse.php, call_response.php) tels quels. Renommez-les. Vérifiez bien votre code qui doit être suffisamment clair et commenté pour vous permettre une maintenance plus aisée.
Lisez-bien toutes les documentations qui sont fournies avec l'
API. Toutes les caractéristiques et options du système de paiement en ligne SIPS-ATOS n'ont pas été traitées dans ce tutoriel qui a simplement pour but que de vous faciliter la compréhension du processus et la mise en place d'une boutique e-commerce avec un caddie simple.
Et enfin , je vous souhaite de bonnes affaires et beaucoup de succès avec votre boutique en ligne !
V. Remerciements
Remerciements à :
- Le Centre d'Assistance Technique SIPS, Atos Worldline
- Nicolas Brand, Marketing Opérationnel Atos Worldline
-
SIPS-ATOS (Atos Origin) pour avoir permis la publication de cet article


Copyright © 2008 Thierry Godin. Aucune reproduction, même partielle, ne peut être faite
de ce site et de l'ensemble de son contenu : textes, documents, images, etc.
sans l'autorisation expresse de l'auteur.
Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 €
de dommages et intérêts.
Cette page est déposée.