HOWTO : Paiement sécurisé sur internet CM-CIC Paiement

30/12/2009 13:44

32.728 lectures

Cette article a pour but d'expliquer le fonctionnement de la solution de paiement CM-CIC Paiement après que j'ai pu lire les difficultés rencontrées par de nombreux internautes pour l'implémenter et surtout comprendre son fonctionnement.
Je m'attarderai surtout sur la clé à employer et son implémentation.

Principe général

La solution de paiement du groupe CM-CIC est fondée sur la technique du secret partagé : l'opérateur bancaire et le commerçant utilise une clé secrète qu'ils sont normalement les seuls à connaître. Cette clé leur permet de signer les échanges entre leurs serveurs respectifs afin de garantir l'authenticité de l'émetteur d'un message et la non altération du message par un tiers non autorisé.

Les messages échangés sont donc toujours accompagnés d'une signature (aussi appelé sceau) générée à partir de la clé secrète et des informations à échanger : le HMAC.
CM-CIC Paiement propose deux type de HMAC (et donc deux types de clé associées) : HMAC-MD5 et HMAC-SHA1.
Notons que par défaut pour les développeurs en language ASP, c'est du HMAC-MD5 qui est proposé. L'exemple d'implémentation fourni par le CM-CIC utilise d'ailleurs ce HMAC, mais une implémentation de l'algorithme HMAC-SHA1 en JS est disponible ici (EN) et offre donc le choix.

La cinématique d'une transaction de paiement est la suivante :
1. Génération sur le site commerçant du message contenant les informations sur le paiement à effectuer (montant, date, référence...) et appel du serveur bancaire
2. Contrôle de l'identité de l'appelant, de l'intégrité (format) des données et de leur authenticité (HMAC)
3. Affichage de la page de saisie des informations bancaires (serveur de la banque)
4 Contrôle des informations saisies, authentification 3D Secure éventuelle, demande d'autorisation de paiement à la banque de l'internaute
5. Affichage du résultat de la transaction à l'internaute et appel asynchrone d'une url de callback (souvent dénommée "url CGI2" dans le jargon de cette solution de paiement) sur le site du commerçant pour l'informer du résultat de paiement.

Les échanges commerçant/banque (donc soumis à signature) ont lieu aux étapes 1 et 5, respectivement appelée "phase aller" et "phase retour" dans le jargon de cette solution de paiement.

La clé

Avant toute chose, il vous faudra télécharger le fichier contenant clé afin de l'en extraire et de l'intégrer à votre système d'information.

Télécharger la clé

Il faut différencier la clé qui sera utilisée pour le calcul du sceau du fichier qui la contient.
Le fichier contenant la clé est téléchargeable via une pièce jointe contenue dans un email envoyé par la banque (downloadkey[TPE].html).
Vous êtes alors redirigé vers le serveur bancaire où à l'aide de votre identifiant/mot de passe (envoyés en deux emails séparés par la banque) vous avez le choix de télécharger le fichier contenant la clé selon la version de la solution de paiement que vous souhaitez utiliser :
- version 3.0 : c'est la dernière version de la solution de paiement
- version antérieure à la 3.0 (appelée aussi 1.2open).
Nous allons par la suite traiter que de la version 3.0, mais il faut savoir que le principe de calcul du sceau est exactement le même pour les deux versions au delta des messages à signer et d'une particularité dans la représentation de la clé.

Extraire la clé

Le fichier contenant la clé est un fichier texte contenant les information suivantes :
VERSION 1 [CLE]
[TYPE_DE_CLE]
#
[HASH_DU_FICHIER]

Exemple fichier clé version 3.0 :



VERSION 1 325A16A325127FD42B700D4810E83F6312877B92

HMAC-SHA1

#

e63b33e42b62f19fb5e6bbfa0c08429ab04239ba

Exemple fichier clé version 1.2open :



VERSION 1 325A16A325127FD42B700D4810E83F6312877BP2

HMAC-SHA1

#

e63b33e42b62f19fb5e6bbfa0c08429ab04239ba

La clé est donc la suite de 40 caractères située en première ligne du fichier, soit 405A16A325127FD42B700D4810E83F6312877B92.
Je reviendrais sur le caractère non-hexadécimal en avant-derniere position du fichier clé version 1.2open dans le paragraphe suivant.

Implémenter la clé

La clé que vous avez extraite du fichier est la représentation au format externe de la clé à utiliser pour le calcul du sceau HMAC.
Vous devez donc convertir cette clé en sa représentation opérationnelle, soit une chaine de 20 octets (20 caractères si vous préférez).
Ce qui apparaît ici un peu barbare est en fait relativement simple : il faut convertir chaque couple de caractères hexadécimaux par le caractère ASCII correspondant.

Exemple :



Soit une clé de 40 caractères 4142434445464748494A4142434445464748494A

Elle est composée de 20 couples de caractères hexadécimaux : 41 42 43 44 45 46 47 48 49 4A 41 42 43 44 45 46 47 48 49 4A

Ce qui donne la représentation opérationnelle suivante : ABCDEFGHIJABCDEFGHIJ

Evidemment, l'exemple précédent offre une représentation opérationnelle composé uniquement de caractères affichables, ce qui n'est pas forcément le cas dans la réalité. Ne vous étonnez pas si en voulant afficher votre clé au format opérationnel des hieroglyphes apparaissent.

Petite disgression vers la clé au format 1.2open. Si la version 3.0 est composée uniquement de caractères hexadécimaux, la version 1.2open possède un avant dernier caractère non hexadécimal.
Il s'agit donc de le convertir pour le rendre hexadécimal et là ça ne s'invente pas, mais la méthode à employer est la suivante (déduite des exemples d'implémentation fournis par la banque) : soustraire 23 (en décimal) au code ASCII du caractère non hexadécimal.

Exemple :



Soit la clé 325A16A325127FD42B700D4810E83F6312877BP2

L'avant-dernier caractère de la clé : P

Code ASCII en décimal : 80

Ce qui donne 80 - 23 = 57 soit le caractère 9 (qui lui est entre dans le cadre de la représentation hexadécimale).

donc la représentation externe de la clé est 325A16A325127FD42B700D4810E83F6312877B92

La transformation en représentation opérationnelle pour les clés de version 1.2open suit le schéma décrit précédemment.

Vous avez moyen de vérifier auprès de la hotline de la banque si vous utilisez la bonne clé, non pas en leur envoyant la clé que vous utilisez (à ne JAMAIS faire !), mais en envoyant un HMAC sur une chaine précise : le HMAC de contrôle.
Je détaille ce HMAC de contrôle dans la section glossaire.

Les messages

Maintenant que vous avez votre clé dans sa représentation opérationnelle, il ne vous reste plus qu'à calculer les sceaux pour les messages à envoyer et à réceptionner.

Message Phase Aller (version 3.0) :
Il s'agit d'une chaine formée de la concaténation des données relatives au paiement à effectuer :
<TPE>*<date>*<montant>*<reference>*<texte-libre>*<version>*<lgue>*<societe>*<mail>*<nbrech>*<dateech1>*<montantech1>*<dateech2>*<montantech2>*<dateech3>*<montantech3>*<dateech4>*<montantech4>*

Il est très important de respecter scrupuleusement le format de cette chaine, ainsi que le format de chacune des variables la composant.
Si certaines des variables vous sont inutiles (par exemple celles du paiement fractionné), il faut tout de même les mettre dans cette chaine avec une valeur vide et sans occulter le caractère '*' qui les sépare.
Vous pouvez utiliser un outil de calcul de hash pour vérifiez que votre sceau est correct. (voir la section Références utiles).

Message Phase Retour (version 3.0) :
Il s'agit d'une chaine formée de la concaténation des données relatives au résultat du paiement effectuée. Ca vous permet de vous assurer que c'est bien la banque qui vous envoie ce message.
<TPE>*<date>*<montant>*<reference>*<texte-libre>*3.0*<coderetour>*<cvx>*<vld>*<brand>*<status3ds>*<numauto>*<motifrefus>*<originecb>*<bincb>*<hpancb>*<ipclient>*<originetr>*<veres>*<pares>*

Je ne peux que vous renvoyer vers la documentation et vers les exemples d'implémentation pour que vous vous fassiez une idée du fonctionnement de ces échanges. Le but de cet article étant surtout d'expliquer le fonctionnement de la clé.

Glossaire

TPE : Terminal de paiement électronique. C'est un code composé de 7 caractères (Exemple : 1234567) qui sert à l'identification du commerçant en phase aller.
Clé : suite de 40 caractères (tous hexadécimaux en version 3.0) utilisé pour le calcul du sceau
Contrôle HMAC : il s'agit d'un HMAC calculé sur une chaine fixe CtlHmac[version][TPE] (Exemple : CtlHmac3.01234567) et qui vous permet de déterminer avec la hotline de la banque si vous utilisez la bonne clé. A noter qu'il apparait nativement dans les exemples d'implémentation fournis par la banque.

Références utiles

N'hésitez pas à consulter les liens ci-dessous afin d'obtenir des informations complémentaires :
Le site de la solution de paiement :
http://www.cmcicpaiement.fr/fr/index.html

La page de téléchargement (documentations, logos, exemples d'implémentation) :
http://www.cmcicpaiement.fr/fr/installation/telechargements/index.html

Un utilitaire gratuit de calcul de hash (dont HMAC-MD5 et HMAC-SHA1) :
HashCalc de SlavaSoft

Hotline de la banque
centrecom@e-i.com

Commentaires (24)

Flux RSS 24 messages · Premier message par Nico hier 14:41 · Dernier message par Lau 21/04/2024 17:47

Nico

Bonjour,
Je souhaiterais avoir des renseignements sur le module de paiement CM-CIC Paiement. (Prix, comment l'obtenir, qui contacter, délai d'obtention...)
J'ai remplis le formulaire de contact sur le site du crédit mutuel, toujours sans réponse. Mon conseiller crédit mutuel ne m'aide pas plus.
J'ai vraiment besoin de ce module de paiement au plus vite pour le mettre en place sur mon site perso.

Merci d'avance pour renseignements qui me seront précieux !

Nico

teuh

salut,
voici quelques informations :
- le prix : il dépend du pack que tu vas prendre (les différents packs sont visibles sur http://www.cmcicpaiement.fr) mais il se compose de plusieurs éléments : des frais fixes d'installation et un loyer mensuel... il me semble que c'est tout.
- pour l'obtenir tu dois prendre rendez-vous avec ton conseiller du crédit mutuel, qui peux se mettre en relation avec son correspondant e-commerce régional s'il na pas la compétence suffisante.
- le délai d'obtention est quand même relativement long (quasiment un mois il me semble). La procédure est lente car il va y avoir de nombreux services qui vont vérifier si ton site est compatible avec l'image du cm-cic, les risques liés à ton activité, etc etc...
Comme dis le plus simple : ton conseiller directement (avec l'appui de son correspondant régional spécialement formé pour) et le site http://www.cmcicpaiement.fr pour les détails un peu plus techniques.

Maxsyme

Merci pour ces explications. Parmi les variables du formulaire ALLER, la variable texte-libre me pose problème. CM insiste sur le fait qu'elle doit être écrite avec un tiret et non un souligné, mais alors, comme le tiret est banni des intitulés de variables, cela provoque un code d'erreur PHP. Que cette variable soit laissée vide ou remplie d'ailleurs.
Que puis-je faire ?
Pouvez-vous m'aider ?
Par avance merci.

teuh

Effectivement c'est l'un des points "problématique" du message aller...
Pour des raisons historiques cette variable est écrite comme cela et généralement pour les développeurs soit on oublie ce tiret soit on le remplace par un underscore (le souligné sous le 8). :-)
Cependant je pense que tu confonds 2 choses : le nom de la variable à envoyer en http et la variable Php qui va contenir sa valeur.
En effet, rien ne t'empêche de stocker la valeur de ce champ dans une variable php appelée $texteLibre (et même $tutrlutuchapopointu si tu le souhaitais) et d'avoir ta variable http nommée texte-libre (là par contre tu n'es pas libre de son nommage) comme demandée par la spécification du CM.
Tu auras donc une chaine envoyée au CM du type :
(tes autres variables) . "&texte-libre=" . $texteLibre
Je te conseille de télécharger les exemples d'implémentation qui sont disponibles sur le site du CM. Ils sont très bien fait et simple à comprendre...

juventissei

Encore au top sur le sujet en Avril 2012. On voit bien que tout ca te manque ...

teuh

Ahhhh le paiement, une équipe au top :-)
Que des pros aux services de leurs clients ;-)

Sylvain

Merci pour cet article très instructif. Ça fait des heures que je bute sur l'implémentation de la solution de paiement CMCIC sur notre site e-commerce. Ton article m'a fait comprendre que dans le fichier .key envoyé par la banque, j'utilisais le hash du fichier comme clé de chiffrement au lieu de la clé elle-même. Le CMCIC aurait pu décrire la structure du fichier comme tu l'as fait, ça m'aurait évité des ennuis.

teuh

J'admets que c'est peut être un manque dans leur documentation.

Saches que tu peux leur faire part de cette remarque et que contrairement à ce que beaucoup de gens pensent ils sont très ouverts pour intégrer les bonnes idées de leur client pour améliorer tout ce qui touche à leurs produits (ça peut par contre prendre un peu de temps à être mis en place).

En tout cas, je suis content que, quasiment 3 ans après l'écriture de ce billet, il permet encore d'aider ceux qui souhaite implémenter la solution de paiement du CMCIC.

andre

Hello,
Merci pour ces explications sur comment utiliser la clé. Cependant je n'arrive pas à convertir la clé en représentation opérationnelle ou plutôt comment faire avec des caractères rares que même Notepad ne comprend pas (par ex le #173)?

teuh

Tu ne devrais pas chercher à afficher la chaine de la représentation opérationnelle de ta clé.
Ça n'a aucun intérêt.

De plus, comme tu l'as remarqué, tu te retrouves avec des caractères non-imprimables. C'est absolument normal.
Tu as assez peut de chance de te retrouver avec une représentation fonctionnelle composée uniquement de caractères lisibles. Dans le billet ci-dessus, ce n'était que pour l'exemple que je me retrouvais avec une clé opérationnelle de type: ABCDEFGHIJABCDEFGHIJ. ;-)

Je te conseille donc d'utiliser simplement la représentation opérationnelle, en la stockant dans une variable pour calculer le sceau du message que tu vas envoyer à la banque.
Inspire-toi des exemples fournies par la banque et tu verras tout se passera bien.

Philippe Bedel

L'installation version 3 s'est bien déroulée, j'utilise l'exemple que l'on peux télécharger sur le serveur cicpaiement. En phase test tout fonctionne parfaitement, en phase de production cela fonctionne mais je perds des données. Le support est sympathique mais peu professionnel. Et, logiquement, le code en phase test est le même que celui en production, n'est-ce pas ? Qui a réussi à faire fonctionner ce pack en production ? Merci pour votre aide et vos réponses !!!!

teuh

Petite remarque sur le support de CMCIC paiement: ils ne sont en aucun cas là pour aider au développement informatique des pages, modules, ou fonctions que vous souhaitez utiliser dans votre site internet pour intégrer la fonctionnalité de paiement en ligne. C'est d'ailleurs inscrit dans la documentation de CMCIC Paiement.
Ça peut vous paraître incroyable mais en y réfléchissant bien c'est normal: le nombre de langages informatiques, de façon d'implémenter le module de paiement dans un site internet, les spécificité liées à chaque configuration des serveurs, sont tels que cela demanderait un investissement important en temps et donc en argent.
Les gens du support de niveau 1 (ceux qui vous répondent sur la hotline) ne sont pas des informaticiens. Ils reçoivent une formation afin de pouvoir répondre aux questions basiques sur tout ce qui est lié à la clé (son téléchargement, vérification que le client utilise la bonne, etc...), aux modes de paiements, aux configurations des comptes commerçants mais ne sont en aucun cas aptes et surtout destinés à vérifier une implémentation informatique.

Concernant votre problème, dire "cela fonctionne mais je perds des données" c'est un peu vague :-). Le code est effectivement le même pour faire marcher le module de paiement en test ou en production à la nuance près que le message renvoyé par la banque a un code-retour différent (paiement ou annulation au lieu de payetest). Et je vous rassure des centaines de commerçants ont réussi à faire marcher ce module :-).

Axoo

Bonjour,

Je ne comprends pas vraiment ce que je dois faire avec ma clé de 40 caractères. J'ai une boutique sous Prestashop et le module officiel dans lequel je dois entrer la clé de cryptage, le TPE et le code société. Si je comprends bien, je dois entrer une clé qui n'est pas ce que je peux voir dans mon fichier .key?

Où puis-je "transformer" cette clé et générer une clé de cryptage avec mon fichier?

Désolé si ces questions vous semblent niaises mais c'est la première fois que je suis confrontée à ce genre de module.

Merci pour votre aide.

Lau

teuh

Je ne connais pas bien Prestashop mais je pense que comme pour toute solution prête à l'emploi de boutique en ligne, il te suffit d'entrer directement la clé qui est dans ton fichier .key (les 40 caractères hexadécimaux après la chaine VERSION 1).
La procédure que je décris dans le billet ci-dessus ne concerne que ceux qui veulent écrire tout le programme permettant de calculer la chaine de contrôle du message à envoyer à la banque.

Pour ton TPE, il correspond aux 6 caractères alphanumériques du nom de ton fichier .key (ex: ton TPE est 123456 si ton fichier s'appelle 123456.key).
Ton code-société est une donnée que tu obtiendras facilement auprès de la hot-line du CMCIC si tu ne le connais pas déjà.

Petite disgression: 200 € H.T. pour le module CM-CIC Paiement sur Prestashop ? Y'en a qui ne s'embarasse pas pour gagner de l'argent facilement ! C'est limite honteux !

steved

Bonjour et merci pour ce guide bien pratique même quelques années après sa publication

J ai intégré ce système de paiement en 2009 sur mon site sans soucis. Aujourd'hui je m arrache les cheveux sur mon nouveau site. Dans la phase retour la banque renvoie le MAC avec 20 autres champs sur mon url_retour. Mon paiement test fonctionne mais retourne "erreur" pour la banque. Ils attendent que mon code retourne "version=2" et une autre valeur qui m échappe à cette heure :)
Un conseiller me dit "c est pas grave on peut basculer en production" et un autre me dit "tant que c est erreur on peut rien faire".
- qui croire ?
- est ce que tu peux m expliquer ce retour attendu ?

Encore merci pour ton guide et pour ton aide précieuse

Steve

teuh

Oups j'avais loupé ton com... D'où la réponse tardive...
Je pense que ce que la banque attend c'est que ton url de callback (ou url CGI2, ou url appelée par la banque pour te signifier qu'un paiement a eu lieu) produise le message suivant:
version=2
cdr=0 (ou cdr=1 en cas de non validation du sceau)
Je te conseille de regarder la documentation technique (page 17) disponible ici pour plus de détails:
https://www.cmcicpaiement.fr/fr/info/documentations/CM-CIC_paiement_documentation_technique_v3_0.pdf
Normalement tu n'es pas censé basculer en production tant que ton site ne renvoie pas la valeur attendue au moins 3 fois de suite...

Oflas

Bonjour,

Mon site tournant sur prestashop, Le CIC va t-il nous fournir un module "tout-prêt" ou dois-je passer par le module de prestashop à 200e ?

Merci..

georzndg

HOWTO : Paiement sécurisé sur internet CM-CIC Paiement | Ouh c'est papa qu'il est malin comme un singe | racingstub.com
ugeorzndg
georzndg http://www.g7npa567mq97zuz19942tli73sq711dys.org/
<a href="http://www.g7npa567mq97zuz19942tli73sq711dys.org/">ageorzndg</a>

Pleuh

Juste un grand merci pour cet article ;
je trouve la documentation de la banque vraiment ridicule et je n'aurais jamais pu implémenter ça sans ce billet.

Graphiste

Merci pour ces explication, mais pour un graphiste comme moi l'installation de CMCIC qui maintenant est Monetico est d'un compliqué sans nom alors que des modules tout fait pour Woocommerce ou Prestashop coûtent de 55 à 89 euros !!
Pourquoi ces banques n'ont pas investies dans un module installable, c'est quand même la banque qui rentre du % de commission et qui gagne de l'argent sur les trasaction Mince.

on est en 2017 les systèmes US marchent en 2 clics PayPAl, PayGreen et là il faut deux jours de dévelloppement pourinstaller un TPE Je rêve la France numérique ne s'est toujours pas réveiilée………… en tout ca s je galère à essayer d'installer ça ;-)

Renand

Hello, excellent ce topic, merci.... Reste que je bute sur un point.
Mes appels ne sont pas signés correctement.
J'ai une clé v3, je cherche à récupérer la chaîne de 20 caractères dite 'opérationnelle', et franchement, là plus que des doutes.

Si je m'en tient la la conversion hexa vers string j'ai un retour de 17 caractères. En utilisant cette chaîne comme clé ma signature n'est pas valide, J'ai essayé de remplacé les espaces normalement retournés par la conversion de ma clé principale en concaténant les valeurs retournés pour chaque groupe de 2 caractères de la ,clé principale, je passe de 17 à 20 caractères mais la signature est la même. ... j'en déduit que la clé peux probablement contenir des caractères vides.

Franchement je tourne en rond. J'utilise Coldfusion 9 sur ce projet, oui c'est pas frais, mais bon..

L'idée est bien de prendre les valeurs de la clé fournit en convertissant les valeurs hexa par groupe de deux vers une représentation Asccii ?. Pourrait-il y avoir un problème de charset ?

J'ai du raté une marche...

Une idée ?
Merci

Arnaud

J'ai cherché partout comment intégrer le paiement. Impossible d'obtenir le bon codage.
Et là, enfin, quelqu'un qui donne la réponse!!!
La chaine de 40 caractères doit être séparée en 20 blocs de 2 caractères qui correspondent au 20 codes ascii en hexas de la chaine de cryptage!!!
La documentation aurait ajouté ces 2 lignes j'aurai économisé des jours de recherche.

Donc MERCI teuh !!! :)

teuh

Arnaud a écrit, le 16/01/2021 22:06 :
J'ai cherché partout comment intégrer le paiement. Impossible d'obtenir le bon codage.
Et là, enfin, quelqu'un qui donne la réponse!!!
La chaine de 40 caractères doit être séparée en 20 blocs de 2 caractères qui correspondent au 20 codes ascii en hexas de la chaine de cryptage!!!
La documentation aurait ajouté ces 2 lignes j'aurai économisé des jours de recherche.

Donc MERCI teuh !!! :)

12 ans après, cet article aide encore ? Je suis épaté et content.

Lau

Même en 2024 ton explication viens de nous débloquer donc vraiment merci à toi