Tutoriel : Installation d'une solution de paiement en ligne E-Transactions (SIPS-ATOS) sur un serveur Apache avec PHP

Thierry Godin

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.

- Titre : Tutoriel : Installation d'une solution de paiement en ligne E-Transactions (SIPS-ATOS) sur un serveur Apache avec PHP

- Auteur : Thierry Godin

- Parution : 21 juin 2008

- Licence : 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.

Sommaire

- 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

1. Le client a rempli le caddie et le valide pour procéder au paiement

2. Le fichier call_request.php est exécuté et interroge le binaire request

3. Affichage des moyens de paiement

4. Le client clique sur la carte bancaire. Les données de la transaction sont envoyées au serveur du fournisseur

5. Affichage du formulaire de saisie de carte bancaire

6. Le client saisit ses numéros de carte puis valide. (Si le client abandonne, il est redirigé vers la page d'annulation : 6a -> 6b)

7. Le serveur du fournisseur demande l'autorisation auprès d'une institution financière (réseau bancaire)

8. La réponse est traitée par le fournisseur

9. 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)

10. Ces deux fichiers sont exécutés et interrogent le binaire response pour interpréter le résultat (10 et 10.a)

11. 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.

Si vous n'en êtes pas encore au stade du caddie, je vous recommande alors vivement le tutoriel de Joris Crozier
sur la création d'un panier en PHP

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

/* Informations du client */
$_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";

/* Caddie */
$_SESSION['CADDIE_ID']          = "1";
$_SESSION['CADDIE_LOG_NOM']     = "PlanningFacile";
$_SESSION['CADDIE_LOG_VERSION'] = "1.1.0.0";
$_SESSION['CADDIE_AMOUNT']      = "3000"; //montant en euro sans séparateur = 30,00 euros (C'est pas cher !)

?>

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 :

1. La récupération du caddie

2. La mise en place des paramètres de transaction

3. 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
// on construit le tableau du caddie en récupérant les variables de la session
$TheCaddie = array();

// les infos du client
$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'];

//le contenu du caddie
$TheCaddie[] =  $_SESSION['CADDIE_ID'];
$TheCaddie[] =  $_SESSION['CADDIE_LOG_NOM'];
$TheCaddie[] =  $_SESSION['CADDIE_LOG_VERSION'];
$TheCaddie[] =  $_SESSION['CADDIE_AMOUNT'];

//on crée un numéro de commande pour le fun
$NumCmd      = "CMD-" . date("YmdHis");
$TheCaddie[] =  $NumCmd ;

//pour envoyer le caddie à e-transaction sans probleme
//on serialize le tableau pour en faire 1 string et on le base64_encode()
//car certains caractères sont interdits dans la valeur du parm caddie

$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

//Identifiant commerçant
//Nous en sommes pour l'instant à la phase d'installation,
//Nous utiliserons donc l'identifiant commerçant de test.
//Lorsque nous passerons en pré-production, il faudra alors mettre ici
//l'identifiant commerçant que votre fournisseur vous aura délivré
$parm = "merchant_id=013044876511111";

//Chemin du fichier pathfile + executable request
$parm .= " pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";
$path_bin = "/srv/www/htdocs/empty/request_2.6.9_3.4.2";

//Pays du commerçant
$parm .= " merchant_country=fr";

//Langage de l'interface de paiement
//Si votre site comporte plusieurs langages, vous pouvez préciser dynamiquement ici
//le langage utilisé par le client
//cf : Dictionnaire des données
$parm .= " language=fr";

//Le montant de la transaction
//Cette valeur ne doit pas comporter de ponctuation. Chiffres uniquement !
//Par exemple, le montant du caddie est de 30,00 euros, vous devez mettre 3000
$parm .= " amount=" .$_SESSION['CADDIE_AMOUNT'];

//Monnaie
//Ici c'est l'euro
//Si vous proposez le paiement en plusieurs monnaies,
//vous pouvez changer dynamiquement cette valeur selon la monnaie
//choisie par le client
//cf : Dictionnaire des données
$parm .= " currency_code=978";

//Id de la transaction (6chiffres)
//Vous pouvez ne pas utiliser ce paramètre, auquel cas, le serveur du fournisseur
//créera un id de transaction automatiquement.
//Pour ma part, je pense qu'il peut être utile de le définir ici, notamment
//si on souhaite mettre à jour notre base de données en ajoutant l'id de transaction au caddie enregistré
//avant de procéder à la transaction.
$parm .= " transaction_id=" . date ("His");

//Label sur le reçu de paiement
//Lorsque le paiement a été accepté par le fournisseur, un ticket est affiché à l'écran.
//Vous pouvez ici rajouter un commentaire pour que le ticket affiche au moins le nom de
//votre boutique et le produit acheté.
//Ce paramètre est limité à 3072 caractères et ne doit pas contenir d'espace
//( vous les remplacez par leur équivalent html : &nbsp;)
$Produit = "<tr><td>CHEZN1BUS&nbsp;:&nbsp;&nbsp;LOGICIEL&nbsp;PLANNINGFACILE</td></tr>";
$parm .= " receipt_complement=" . $Produit;

//Email client (no comment)
$parm .= " customer_email=" . $_SESSION['USER_EMAIL'];

//IP client
//Je ne vous mets pas le code pour récupérer l'ip du client
//mais vous saurez trouver ce qu'il vous faut sur developpez.com
$parm .= " customer_ip_address=" . $IP;

//caddie
//On retrouve ici notre fameux caddie que nous avons préparé dans la section précédente.
//Ce champ est limité à 2048 caractères
$parm .= " caddie=" . $xCaddie ;

//Nous pouvons utiliser les paramètres ci-dessous si nous avons besoin de passer des paramètres dans l'url.
//Ici par exemple, nous transmettons l'id de session pour que le client puisse retourner sur son compte au
//retour de la transaction.
//Si vous définissez ces paramètres ici, il est préférable de passer les url en commentaire
//dans le fichier parmcom du commerçant en ajoutant un dièse devant (#)

//url en cas d'annulation
$SUPERID = session_id();
$parm .= " cancel_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;

// url réponse automatique
$parm .= " automatic_response_url=http://www.monsite.com/call_autoresponse.php";

//url de retour du client après le paiement
$parm .= " normal_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;

//et enfin, vous pouvez préciser ici le template que vous souhaitez utiliser
//Voir la section plus bas pour la création du Template
$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

//Appel du binaire request
$result = exec("$path_bin $parm");

//On separe les differents champs et on les met dans un  tableau
$tableau = explode ("!", "$result");

//Récupération des paramètres
$code    = $tableau[1];
$error   = $tableau[2];
$message = $tableau[3];

//Analyse du code retour

if (( $code == "" ) && ( $error == "" ) )
{
//Si nous n'obtenons aucun retour de l'API c'est qu'il n'a pas été exécuté (CQFD)
//Il s'agit la plupart du temps d'un problème dans le chemin vers le binaire request
//Il peut s'agir d'un problème de droits : vérifiez qu'il ait bien les droits d'exécution

print ("<center><h1>Erreur appel request</h1></center>");
print ("<p>&nbsp;</p>");
print ("Executable request non trouve : $path_bin");
}

else if ($code != 0){

//Erreur, affiche le message d'erreur
//Ici le binaire request a bien été exécuté mais un ou plusieurs paramètres ne sont pas valides
//En cas de doute, n'hésitez pas à consulter le Dictionnaire des données

print ("<center><h1>Erreur appel API de paiement.</h1></center>");
print ("<p>&nbsp;</p>");
print ("<p>Message erreur : $error </p>");
}

else {

//Ici, tout est OK, on affiche les cartes bancaires
//Comme on est des programmeurs consciencieux, on va également afficher
//quelques infos supplémentaire pour que le client se sente en confiance
//en lui rappellant le montant de la transaction et le numéro de commande
//ainsi qu'un lien de retour au cas où celui-ci changerait d'avis

print ("<p>&nbsp;</p>");
print ("$message");
print ("<p>&nbsp;</p>");
print("<p align='center'><strong>Montant à payer : </strong> ".
substr($_SESSION['CADDIE_AMOUNT'],0,-2).",".substr($_SESSION['CADDIE_AMOUNT'] ,-2) . " Euros  - ");
print("<strong>Num&eacute;ro de commande : </strong> " . $NumCmd  ."</p>");
print("<p align='center'><a href='javascript:history.go(-1)'>RETOUR</a></p>");

//Ici on peut vérifier le contenu du parm caddie que l'on va envoyer
//pour nous assurer que nous envoyons bien tout ce dont nous aurons besoin au retour
//de la transaction (pour les tests ONLY !!!)
//Décommentez les lignes ci-dessous pendant les tests
//n'oubliez pas de les repasser en commentaire ou de les effacer ensuite

/*
$arrayCaddie = unserialize(base64_decode($xCaddie));
for($i = 0 ; $i < count($arrayCaddie); $i++){
echo $arrayCaddie[$i] . "<br />";
}
*/

}
?>

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

//Récupération du caddie
$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'];

//Numéro de commande
$NumCmd      = "CMD-" . date("YmdHis");
$TheCaddie[] =  $NumCmd ;

$xCaddie = base64_encode(serialize($TheCaddie));

//Identifiant du commerçant (TEST)
$parm = "merchant_id=013044876511111";

//Chemins binaire + pathfile
$parm .= " pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";
$path_bin = "/srv/www/htdocs/empty/request_2.6.9_3.4.2";

//Langages
$parm .= " merchant_country=fr";
$parm .= " language=fr";

//Montant du caddie
$parm .= " amount=" .$_SESSION['CADDIE_AMOUNT'];

//Euro
$parm .= " currency_code=978";

//Numéro de transaction
$parm .= " transaction_id=" . date ("His");

//Complément du reçu
$Produit = "<tr><td>CHEZN1BUS&nbsp;:&nbsp;&nbsp;LOGICIEL&nbsp;PLANNINGFACILE</td></tr>";
$parm .= " receipt_complement=" . $Produit;

//Email du client
$parm .= " customer_email=" . $_SESSION['USER_EMAIL'];

//IP client
$parm .= " customer_ip_address=" . $IP;

//caddie
$parm .= " caddie=" . $xCaddie ;

//url en cas d'annulation
$SUPERID = session_id();
$parm .= " cancel_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;

// url réponse automatique
$parm .= " automatic_response_url=http://www.monsite.com/call_autoresponse.php";

//url de retour du client après le paiement
$parm .= " normal_return_url=http://www.monsite.com/response.php?SUPERID=" . $SUPERID;

//Template
$parm .= " templatefile=le_template_de_mon_site";

//Appel du binaire request
$result  = exec("$path_bin $parm");
$tableau = explode ("!", "$result");

//Récupération des paramètres
$code    = $tableau[1];
$error   = $tableau[2];
$message = $tableau[3];

//Analyse du code retour

if (( $code == "" ) && ( $error == "" ) )
{
//Erreur chemin ou droits
print ("<center><h1>Erreur appel request</h1></center>");
print ("<p>&nbsp;</p>");
print ("<p>Executable request non trouve : $path_bin</p>");
}

else if ($code != 0){

//Erreur paramètres
print ("<center><h1>Erreur appel API de paiement.</h1></center>");
print ("<p>&nbsp;</p>");
print ("<p>Message erreur : $error </p>");
}

else {

//OK, on affiche les cartes bancaires
print ("<p>&nbsp;</p>");
print ("$message");
print ("<p>&nbsp;</p>");
print("<p align='center'><strong>Montant à payer : </strong> ".
substr($_SESSION['CADDIE_AMOUNT'],0,-2).",".substr($_SESSION['CADDIE_AMOUNT'] ,-2) . " Euros  - ");
print("<strong>Num&eacute;ro de commande : </strong> " . $NumCmd  ."</p>");
print("<p align='center'><a href='javascript:history.go(-1)'>RETOUR</a></p>");

//Vérifier le contenu du parm caddie que l'on va envoyer (Test ONLY !!!)

/*
$arrayCaddie = unserialize(base64_decode($xCaddie));
for($i = 0 ; $i < count($arrayCaddie); $i++){
echo $arrayCaddie[$i] . "<br />";
}
*/

}
?>

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

//Récupération de la variable DATA en provenance du serveur du fournisseur.
//La réponse de la transaction est contenue dans cette variable dans son intégralité
//Evidemment toutes ces données sont chiffrées : c'est le binaire response qui fera tout le travail.
$message = "message=" . escapeshellcmd($_POST['DATA']);

// Initialisation du chemin du fichier pathfile
$pathfile = "pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";

//Initialisation du chemin de l'executable response
$path_bin = "/srv/www/htdocs/empty/response_2.6.9_3.4.2";

//Appel du binaire response
$result = exec("$path_bin $pathfile $message");

//On separe les differents champs et on les met dans une variable tableau
//Puis on récupère toutes les valeurs.

$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];

//Initialisation du chemin du fichier de log que nous avions mis dans le même
//répertoire que les fichiers du système de paiement
$logfile = "/srv/www/htdocs/monsiteweb/xpay/log.txt";

//Ouverture du fichier de log en append
$fp = fopen($logfile, "a");

//Analyse du code retour

if (( $code == "" ) && ( $error == "" ) )
{
//Si nous n'obtenons aucun retour de l'API c'est qu'il n'a pas été exécuté (CQFD)
//Il s'agit la plupart du temps d'un problème dans le chemin vers le binaire response
//Il peut s'agir d'un problème de droits : vérifiez qu'il ait bien les droits d'exécution
//Rappellez-vous que ce fichier ne génére aucune sortie HTML
//Vous ne verrez donc pas de message d'erreur à l'écran

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 ){

//Erreur,
//Ici le binaire response a bien été exécuté mais un ou plusieurs paramètres ne sont pas valides
//En cas de doute, n'hésitez pas à consulter le Dictionnaire des données

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 {

//OK
//Ici, la transaction s'est bien déroulée, mais cela ne veut pas dire pour autant que
//le paiement a été accepté !

//Paiement accepté = '00'
//Référez-vous au Dictionnaire des données pour les numéros de réponse
if($bank_response_code == "00"){

//Caddie
//Ici nous retrouvons tout notre caddie que nous remmettons dans un tableau
$arrayCaddie = unserialize(base64_decode($caddie));

//Date (ymd) / Heure (His) de paiement en français
$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) ;

//Le reçu de la transaction que nous allons envoyer pour confirmation
$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";

//Envoi du message au client
mail($customer_email , $Sujet, $Msg, 'From: shop@monsite.com');

//On en profite pour s'envoyer également le reçu
mail('xxxxx@xxxxx.fr' , $Sujet, $Msg, 'From: shop@monsite.com');

//Mise à jour de la base de données (si vous en utilisez)
//Ici nous pouvons mettre à jour la base de données
//puisque la transaction a réussie et le paiement a été accepté
//Vous connaissez la méthode .. UPDATE... etc. etc.

}

//--------------------------------------------------------------------------------

//La transaction a réussi.
//Quelque soit le résultat (paiement accepté ou refusé) , nous enregistrerons toutes les données
//Ceci nous fait une sécurité de plus en cas de panne ou de litige avec le client
//ou si aucun email n'a été reçu ( ou message envoyé dans le dossier SPAM du logiciel de messagerie)
//Si votre boutique débite pas mal, ce que je vous souhaite, vous penserez à vider
//régulièrement votre fichier de logs pour ne pas encombrer votre espace disque.
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");

//ici on dépiote le caddie
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

//Récupération de la variable DATA en provenance du serveur du fournisseur.
//La réponse de la transaction est contenue dans cette variable dans son intégralité
//Evidemment toutes ces données sont chiffrées : c'est le binaire response qui fera tout le travail.
$message = "message=" . escapeshellcmd($_POST['DATA']);

// Initialisation du chemin du fichier pathfile
$pathfile = "pathfile=/srv/www/htdocs/monsiteweb/xpay/pathfile";

//Initialisation du chemin de l'executable response
$path_bin = "/srv/www/htdocs/empty/response_2.6.9_3.4.2";

//Appel du binaire response
$result = exec("$path_bin $pathfile $message");

//On separe les differents champs et on les met dans une variable tableau
//Puis on récupère toutes les valeurs.
//En vérité nous n'avons besoin ici que de quelques variables
//mais ceci vous permet d'identifier les différentes valeurs du tableau

$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];

//Analyse du code retour

if (( $code == "" ) && ( $error == "" ) ){

//Si nous n'obtenons aucun retour de l'API c'est qu'il n'a pas été exécuté (CQFD)
//Il s'agit la plupart du temps d'un problème dans le chemin vers le binaire response
//Il peut s'agir d'un problème de droits : vérifiez qu'il ait bien les droits d'exécution

print ("<center><h1>Erreur appel response</h1></center>");
print ("<p>Executable response non trouve : $path_bin </p>");
}

else if ( $code != 0 ){

//Erreur,
//Ici le binaire response a bien été exécuté mais un ou plusieurs paramètres ne sont pas valides
//En cas de doute, n'hésitez pas à consulter le Dictionnaire des données

print ("<center><h1>Erreur appel API de paiement.</h1></center>");
print ("<p>Message erreur : $error </p>");

}

else {

//OK
//Ici, la transaction s'est bien déroulée, mais cela ne veut pas dire pour autant que
//le paiement a été accepté !

//Paiement accepté = '00'
//Référez-vous au Dictionnaire des données pour les numéros de réponse
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>");
}

//Paiement refusé
else{

print("<center><h1>Votre paiement a été refusé par notre établissement bancaire</h1></center>");

}

//Ici nous affichons un message dans le cas où l'internaute aurait cliqué
//sur le bouton ANNULATION
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

//Identifiant commerçant de test à passer en commentaire lors du passage en pré-prod
//$parm = "merchant_id=013044876511111";

//Votre identifiant commerçant
$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

//Montant du caddie à décommenter lors du passage en production
//$parm .= " amount=" .$_SESSION['CADDIE_AMOUNT'];

//Montant du caddie pour les tests de pré-prod à supprimer ou commenter
//lors du passage en production
$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 :

1. De repasser le paramètre DEBUG à NO dans le fichier pathfile

2. 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

//Template personnalisé seulement à partir de la phase de pré-production
$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 à Guillaume Rossolini pour ses conseils et corrections.

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