Olivier CLEMENCEWebmaster freelance passionné

Voici la première étape d’un tutoriel qui en compte deux et qui va vous permettre d’installer un paiement sécurisé basé sur la solution ATOS SIPS (le leader sur le marché Français).

Avant toutes choses sachez que votre banque vous demandera pas mal d’informations et montera tout un dossier avant de vous autoriser (ou pas) à utiliser leur serveur pour vos paiements sécurisés. Cela prend du temps et je vous conseille de ne pas trop attendre avant de vous lancer dans ces démarches.

Les éléments nécessaires

Une fois le coté administratif réglé, vous devriez recevoir par mail:

• La documentation qui comporte notamment le dictionnaire des données et le guide d’installation.
• L’API (que nous détaillerons plus loin).
• Le certificat crypté (un fichiez .zip contenant un .exe qui porte le nom de certif.fr.xxxx)

Vous allez recevoir également par courrier la clé de décryptage du certificat crypté.

Description du contenu de l’API

L’API comprend les fichiers et dossiers suivants:

Le dossier Bin qui comprend:

• request_2.4.18_2.96
• response_2.4.18_2.96
• request_2.6.9_3.4.2
• response_2.6.9_3.4.2
• request
• response

Normalement vous ne devriez avoir besoin que des fichiers request et response (nous allons expliquer plus loin comment s’en servir).

Le dossier logo comprend les différents logos de cartes bleues et clés.

Le dossier param comprend:

• certif.fr.xxxxxxxx
• pathfile
• parmcom.sherlocks (ici sherlocks correspond au système du LCL cela peut changer selon la banque choisie)
• parcom.xxxxxxxx

Certif.fr.xxxxxx est un certificat de test qui va vous permettre d’effectuer vos tests avant la mise en production.
Pathfile est un fichier de configuration où il faudra indiquer les différents chemin des dossiers et fichiers utiles.
parmcom.sherlocks est un fichier de configuration de la banque déjà configuré, vous n’aurez pas à le modifier.
parmcom.xxxxxx est un fichier de configuration de test (les xxx sont remplacés par des numéros identiques pour certif.fr et parmcom).

Le dossier sample comprend des fichiers d’exemples:

• call_autoresponse.php
• call_request.php
• call_response.php
• et les mêmes fichiers en .pl (inutile pour une implantation en php)

Nous verrons plus loin comment se servir de ces fichiers.

Principe de fonctionnement

Là je ne me suis pas fatigué, j’ai repris le schéma de Thierry Godin qui a fait un excellent tuto sur le sujet également (même si dans mon cas certains points n’étaient pas tout à fait justes).

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

Envoi des fichiers request et response sur le serveur

A cette étape il y a deux possibilités, soit la variable safe_mode de votre serveur est placée sur ON soit sur OFF.
Dans le premier cas vous devrez alors envoyer vos fichiers request et response dans le répertoire indiqué par la variable safe_mode_exec_dir.
Dans le second vous  pourrez envoyer vos deux fichiers où bon vous semble.

Pour connaître le statut du safe_mode et le répertoire du safe_mode_exec_dir sur votre serveur il suffit d’utiliser la commande phpinfo();

Le fichier pathfile

C’est le fichier qui va contenir les chemins d’accès aux fichiers de configuration, vous allez y indiquer:

- Le chemin vers le dossier logo. Ce chemin devra être relatif.

- Le chemin vers le fichier de configuration de la banque parmcom.sherlocks.

- Le chemin vers le fichier de configuration du commerçant parmcom.xxxxxxx.

- Le chemin vers le certificat du commerçant certif.fr.xxxxx.

- La mention YES ou NO pour le DEBUG.

Ce qui va vous donner au final:

#########################################################################
#
#	Pathfile
#
#	Liste des 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
# Exemple pour le répertoire www.merchant.com/sherlocks/payment/logo/
# indiquer:
# ------------------------------------------------------------------------
#
D_LOGO!/cbatos/logo/!
#
# --------------------------------------------------------------------------
#  Fichiers paramètres liés a l'api sherlocks paiement
# --------------------------------------------------------------------------
#
# fichier des  paramètres sherlocks
#
F_DEFAULT!/homez.316/monsite/www/cbatos/parmcom.sherlocks!
#
# fichier paramètre commercant
#
F_PARAM!/homez.316/monsite/www/cbatos/parmcom!
#
# certificat du commercant
#
F_CERTIFICATE!/homez.316/monsite/www/cbatos/certif!
#
# --------------------------------------------------------------------------
# 	end of file
# --------------------------------------------------------------------------

Le fichier parmcom.xxxx

Ce fichier permet d’indiquer les urls de réponse automatiques et manuelles. Mais, vous le verrez après, il est possible de spécifier ces urls (et bien d’autres choses) directement dans le fichier call_request.php et c’est ce que nous allons faire. Donc pour le fichier parmcom.xxx nous allons simplement mettre en commentaire certaines lignes.

###############################################################################
#
#	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.fr/cbatos/call_autoresponse.php!

# URL de retour suite a paiement refuse

#CANCEL_URL!http://http://www.monsite.fr/cbatos/call_autoresponse.php!

# URL de retour suite a paiement accepte

#RETURN_URL!http://!

# Code devise  ( 978=EURO )

CURRENCY!978!

# Logo du commercant

#LOGO2!commercant.gif!

# flag d'edition des libelles des blocs de paiement

HEADER_FLAG!no!

# Liste des moyens de paiement acceptes

PAYMENT_MEANS!CB,2,VISA,2,MASTERCARD,2!

# END OF FILE

Ici je n’ai pas commenté les lignes:
- CURRENCY!978! qui indique la monnaie utilisée (ici l’euro).
- HEADER_FLAG!no! qui précise si on veut voir afficher le logo « clé » (ici on n’en veut pas).
- PAYMENT_MEANS!CB,2,VISA,2,MASTERCARD,2! qui indique les moyens de paiement proposés (ici CB,visa et mastercard).

J’aurai pu les commenter et spécifier ces éléments dans mon fichier call_request.php, à vous de juger ce qui sera le mieux dans votre cas.

Le fichier recap.php

Je vous entends déjà raler.. « oh ! c’est quoi ce fichier on n’en a pas parlé plus tôt ».

En fait ce fichier est celui qui va afficher un récapitulatif du panier du client (ou de sa future commande) ainsi que les moyens de paiement. Vous pouvez le nommer comme vous voulez ça n’a pas d’importance.

Pour le récapitulatif je ne peux pas vous aider c’est à vous  de récupérer le contenu du panier et les informations de facturation saisies par le client. Vous devez également obtenir un montant total à facturer ainsi qu’un numéro de commande unique.

Une fois que vous avez tout cela vous allez pouvoir inclure (avec la commande include() ) dans recap.php le fichier call_request.php, c’est lui qui saura s’il est possible ou pas d’afficher les moyens de paiement.

Le fichier call_request.php

Le fichier call_request.php va récupérer tous les paramètres nécessaires à la transaction et générer une requête. Cette requête sera ensuite envoyée au fichier request puis il analysera la réponse obtenue.

Voila à quoi ressemble le fichier call_request.php

	//Affectation des parametres obligatoires

	$parm="merchant_id=014295303911111"; //merchant_id de test
	$parm="$parm merchant_country=fr";//pays
	$parm="$parm amount=".$totalCommande;

	// Initialisation du chemin du fichier pathfile
	$parm="$parm pathfile=/homez.316/monsite/www/cbatos/pathfile";

	//l'email de l'acheteur
	$parm .= " customer_email=" . $emailCommande;

	$parm.=" order_id=".$idCommande;//numero unique de la commande

	//url en cas d'annulation
	$parm .= " cancel_return_url=http://www.monsite.fr/annulation.php";

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

	//url de retour du client après le paiement
	$parm .= " normal_return_url=http://www.monsite.fr/merci.php";

	$path_bin = "/homez.316/monsite/cgi-bin/request";//ici j'avais choisi de placer mon fichier request dans le dossier cgi-bin

	//	Appel du binaire request

	$result=exec("$path_bin $parm");

	//	sortie de la fonction : $result=!code!error!buffer!
	//	    - code=0	: la fonction genere une page html contenue dans la variable buffer
	//	    - code=-1 	: La fonction retourne un message d'erreur dans la variable error

	//On separe les differents champs et on les met dans une variable tableau

	$tableau = explode ("!", "$result");

	//	recuperation des parametres

	$code = $tableau[1];
	$error = $tableau[2];
	$message = $tableau[3];

	//  analyse du code retour

  if (( $code == "" ) && ( $error == "" ) )	{
	$txtReponse="executable request non trouve ".$path_bin;
 	}

	//	Erreur, affiche le message d'erreur

	else if ($code != 0){
		$txtReponse="<center><b><h2>Erreur appel API de paiement.</h2></center></b><br><br><br> message erreur : ".$error." <br>";
	}

	//	OK, affiche le formulaire HTML
	else {
		$txtReponse=($error!="")?"<br><br>".$error."<br />":"";
		$txtReponse.=$message;
	}

Merchant_id correspond au numero qui se trouve derrière le fichier certif.fr.xxxxx (celui de test pour commencer on remplacera par le numéro du certificat officiel une fois tout configuré)

$parm amount cette variable prend le montant total de votre commande mais sans virgule. C’est à dire que pour 27.90 € vous devez indiquer 2790.

$parm pathfil le chemin vers le fichier pathfile

$order_id je vous ai précisé plus haut qu’il fallait prévoir un numéro de commande unique. Ce n’est en fait pas obligatoire mais conseillé. En effet, afin de retrouver dans votre base de données la commande qui vient d’être payée il est utile d’avoir un identifiant unique pour la repérer. C’est pourquoi nous renseignons $order_id avec cet identifiant. Vous pouvez aussi utiliser le même identifiant pour transaction_id ce qui vous permettra de faire le rapprochement entre une commande dans votre base de données et une transaction dans les logs de la banque.

cancel_return_url il faut indiquer ici l’url de la page qui sera appelée lorsque l’utilisateur cliquera sur le bouton annulé (une fois sur le serveur de la banque)

automatic_response_url c’est l’url du script qui sera appelé lorsque l’utilisateur effectuera son paiement (réussi ou non). Cette page ne peut afficher quoi que ce soit. Elle ne peut servir qu’à mettre à jour votre base de données.

normal_return_url c’est l’url de la page qui sera appelé lorsque le client aura payé et reviendra sur le site. Cette page reçoit les même informations que automatic_response_url la seule différence c’est qu’elle est appelé par le navigateur du visiteur et peut donc afficher du texte.

$path_bin le chemin vers le fichier exécutable request

Tel quel le fichier n’affichera rien, car le résultat est enregistré dans la variable $txtReponse. C’est votre fichier recap.php qui devra faire un echo sur cette variable pour afficher le résultat.

Rien ne vous oblige à inclure le fichier call_request.php dans le fichier recap.php, vous pourriez l’appeler directement. Mais en pratiquant ainsi vous séparez le code qui traite avec le serveur de la banque du code propre à votre site. C’est plus clair et plus réutilisable.

Vous n’avez plus qu’à envoyer votre fichier recap.php et call_request.php sur votre serveur.

Cette première partie est terminée et je pense qu’elle vous aura occupé déjà quelques minutes (heures). La prochaine étape sera plus simple et consistera à récupérer les informations renvoyées par la banque, mettre à jour la base de données en conséquence et enfin passer en pré-production puis en production.

N’hésitez pas à utiliser les commentaires pour poser des questions j’essaierai de vous répondre du mieux possible.

Installation d’un paiement ATOS SIPS – deuxième partie

Vous pouvez également lire « les erreurs fréquentes lors de l’installation d’un paiement Atos »

Tags : atos, paiement sécurisé, sips