E-TRANSACTIONS. Guide du programmeur API Plug-in. Version PDF

Please download to get full document.

View again

of 13
445 views
PDF
All materials on our website are shared by users. If you have any questions about copyright issues, please report us to resolve them. We are always happy to assist you.
Document Description
E-TRANSACTIONS Guide du programmeur API Plug-in Version 1.1 Avertissements : Le fichier Version.txt précise l'environnement dans lequel l API a été compilée et testée. L'installation de l API sur tout
Document Share
Documents Related
Document Transcript
E-TRANSACTIONS Guide du programmeur API Plug-in Version 1.1 Avertissements : Le fichier Version.txt précise l'environnement dans lequel l API a été compilée et testée. L'installation de l API sur tout autre environnement n'est pas garantie. Les chemins et les champs présents dans les différents fichiers de l API ne doivent en aucun cas contenir des espaces. La présence d espaces provoque des messages d erreur difficiles à interpréter car la valeur des champs concernés est tronquée. Les chemins ne doivent pas comporter plus de 80 caractères tél. : fax. : /13 SOMMAIRE Guide du programmeur pour Plug-in : PHP et Perl API v6 1. INTRODUCTION LA REQUÊTE DE PAIEMENT : CALL_REQUEST PARAMETRES DE LA REQUETE LE FICHIER PATHFILE LE MODE DEBUG EXECUTABLE REQUEST PARAMETRE TRANSACTION_ID LA REPONSE A UN PAIEMENT : CALL_RESPONSE CHAMPS DE LA REPONSE EXECUTABLE RESPONSE LA REPONSE AUTOMATIQUE : CALL_AUTORESPONSE POURQUOI DEUX REPONSES PRINCIPE DE FONCTIONNEMENT IMPLEMENTATION DU SCRIPT CALL_AUTORESPONSE PROBLEMES DE FONCTIONNEMENT LORSQUE L ON APPELLE L API LORSQUE L'API APPELLE LE SERVEUR E-TRANSACTIONS LA REPONSE AUTOMATIQUE NE FONCTIONNE PAS CONTACTS EN CAS DE PROBLEME...11 ANNEXE A : MOT-CLES DE LA REQUETE...12 tél. : fax. : /13 1. INTRODUCTION Guide du programmeur pour Plug-in : PHP et Perl API v6 - Ce document vous décrit les différents scripts et exécutables disponibles dans l API Plug-in E- Transactions, quel est leur rôle et comment les utiliser. Pour intégrer l API, vous devrez développer 3 scripts (PHP, PERL ou SHELL) pour traiter les 3 messages échangés entre le serveur de paiement, le site marchand et le navigateur de l internaute. - L API Plug-in E-Transactions présente 2 exécutables principaux : request pour la création de la requête de paiement response pour l interprétation la réponse du serveur Note : ce document ne décrit pas comment vous interfacer avec votre système d information ou votre base de données. Dans les exemples fournis, les variables sont déjà renseignées, vous devrez programmer la lecture et la mise à jour des données de votre système d information. Logiciels pré-requis : - Interpréteur PHP, PERL ou SHELL. - Serveur http pour exécuter vos scripts. Conventions d écriture : - Les renvois à d autres documentations seront notés en majuscules et en italique. ex : DICTIONNAIRE DES DONNEES - Les exécutables et champs de l API seront notés en italique. ex : request, pathfile, transaction_id - Les scripts que vous devez développer seront notés en gras ex : call_request Outre LE GUIDE DU PROGRAMMEUR, le kit de paiement est distribué avec les documentations suivantes : - LA PRESENTATION GENERALE (présentation fonctionnelle de l offre de paiement) - LE GUIDE D INSTALLATION (manuel présentant les différentes étapes de l installation de l API) - LE DICTIONNAIRE DES DONNEES (manuel présentant les différents champs de l API) - LE GUIDE DE PERSONNALISATION DES PAGES (manuel expliquant les différentes possibilités de personnalisation des pages de paiement) - LA DESCRIPTION DES JOURNAUX (manuel décrivant les différents formats des journaux de fonds). tél. : fax. : /13 2. LA REQUÊTE DE PAIEMENT : CALL_REQUEST Guide du programmeur pour Plug-in : PHP et Perl API v6 2.1.PARAMETRES DE LA REQUETE Le DICTIONNAIRE DES DONNEES fournit la liste des champs de la requête, leur description et le caractère obligatoire ou facultatif de leur affectation. Ces champs peuvent être renseignés dans les fichiers parmcom et dans le script call_request. De plus, l exécutable request affectera des valeurs par défaut aux champs block_align, block_order, currency_code et header_flag s ils ne sont renseignés ni dans les fichiers parmcom, ni dans le script call_request. Pour renseigner un champ dans le script call_request, il faut créer une chaîne de caractères de la forme mot-clé=valeur et passer cette chaîne de caractères en paramètre à l exécutable request (rappel : valeur ne doit pas contenir d espace). Le fichier call_request comporte des exemples de chaînes de caractères pour chacun des champs de la requête. Il suffira de transmettre à l exécutable request toutes les chaînes de caractères que vous souhaitez prendre en compte pour la requête. Comment se déroulera la création de la requête? Pour créer une requête de paiement, vous devez appeler le script call_request à l aide d un navigateur. Ce script appelle l exécutable request avec les champs que vous aurez paramétré. L exécutable request prépare la requête de paiement avec les valeurs qu il lit dans le fichier parmcom., dans le fichier parmcom. merchand_id et dans les paramètres fournis par le script call_request. Si un champ est renseigné dans le fichier parmcom., dans le fichier parmcom. merchand_id et dans les paramètres fournis par le script call_request, sa valeur sera écrasée au fur et à mesure des lectures. Dans cet exemple, le paramètre aura finalement la valeur transmise par le script call_request. Ce type d affectation vous permet de renseigner statiquement des valeurs dans les fichiers parmcom et de les modifier dynamiquement dans le script call_request si nécessaire. 2.2.LE FICHIER PATHFILE Le fichier pathfile est le fichier de configuration principal de l API. Il contient les chemins des autres fichiers paramètres de l API et permet donc aux exécutables d accéder aux fichiers parmcom., parmcom et certificat. Le fichier pathfile contient également le chemin Internet des logos des moyens de paiement ainsi que le mot clé d activation du mode DEBUG. Deux possibilités s offrent à vous pour la localisation du fichier pathfile sur votre serveur : Dans le script call_request, vous précisez en paramètre la chaîne de caractères pathfile=chemin_vers_le_pathfile. Alors vous devez positionner le fichier pathfile par rapport au chemin_vers_le_pathfile. Dans le script call_request, vous ne précisez pas le chemin du pathfile en paramètre. Alors vous devez positionner le fichier pathfile dans le même répertoire que le script call_request. Le chemin du fichier pathfile fourni à l exécutable doit être un chemin physique (en aucun cas un chemin Internet). On recommande un chemin absolu, comme c est le cas dans les exemples de scripts livrés. tél. : fax. : /13 La syntaxe des lignes de ce fichier est la suivante : Chaque ligne commençant par # est une ligne de commentaires. Les chemins sont paramétrés par des lignes mot-clé!chemin! Les trois paramètres essentiels sont les trois variables F_CERTIFICATE, F_PARAM, et F_DEFAULT qui doivent contenir respectivement les chemins complets des fichiers certif.fr , parmcom , et parmcom.. Seul le fichier parmcom. doit être paramétré avec son extension.. Les extensions des autres fichiers seront ajoutées par l API d après les paramètres renseignés dans le script call_request. Il est recommandé de placer des chemins complets dans ces variables. De plus, ces chemins doivent être des chemins physiques du serveur, et non pas des chemins internet. Le paramètre D_LOGO sert à l affichage des moyens de paiement. Lui seul doit être renseigné avec une portion de chemin Internet, soit l URL du répertoire des logos de l API sur le site web, amputée du nom de domaine de ce dernier. (cf. GUIDE D INSTALLATION). Le dernier paramètre DEBUG sert à l affichage des moyens de paiement en mode DEBUG. 2.3.LE MODE DEBUG Le mode DEBUG permet d afficher (en format HTML) l environnement complet de l api, ainsi que tous les paramètres de la requête et de la réponse d un paiement. Pour activer ce mode, le paramètre DEBUG du fichier pathfile doit être renseigné à YES. Le mode DEBUG est constitué de différentes rubriques indiquant les ressources utilisées par l api. Il permet ainsi de vérifier, par exemple, le contenu du fichier pathfile, l URL du serveur de paiement ou encore la valorisation des champs de la requête de paiement. En phase de production, ce mode devra être désactivé (renseignement de la valeur du paramètre DEBUG autre que YES). 2.4.EXECUTABLE REQUEST Utilisation : request var 1 var 2 var 3 avec var X une chaîne de caractère du type mot-clé=valeur La liste des différents mot-clés est précisée dans l annexe A. Rappel : valeur ne doit pas contenir d espace. Retour : L exécutable request retourne une chaîne de caractères composée de trois chaînes de caractères séparées par un ! :!code!error!buffer! avec code, le code retour du traitement. Deux valeurs sont possibles : 0 : l exécutable génère un formulaire HTML contenue dans la variable buffer -1 : l exécutable retourne un message d'erreur dans la variable error. (cf. rubrique problèmes de fonctionnement). Le formulaire HTML contenue dans la variable buffer comporte : La liste des logos des moyens de paiement. L URL du serveur E-Transactions. Des données cachées à transmettre au serveur E-Transactions. Cette page doit ensuite être affichée sur le poste de l internaute. Les blocs d icônes de paiement proposés par la boutique incluent chacun un en-tête en option (cf. GUIDE DE PERSONNALISATION). L exécutable request construit un message crypté à partir de toutes les données que vous aurez renseignées dans les fichiers parmcom et le script call_request (l activation du mode DEBUG permet de s assurer de la valeur tél. : fax. : /13 finale des paramètres de la requête de paiement). Il le signe ensuite par un MAC (Message Authentication Code), un scellement calculé avec un algorithme DES. Ce message crypté apparaît (en variable cachée) dans la page HTML retourné par l exécutable. Il sera posté sur l URL du serveur E-Transactions pour permettre l identification du commerçant et par suite, le traitement de sa demande de transaction PARAMETRE TRANSACTION_ID Dans le script call_request, deux possibilités s offrent à vous pour renseigner le champ transaction_id : si vous ne le transmettez pas en paramètre à l exécutable request, une valeur sera générée automatiquement. Cette valeur est basée sur l heure système ( format hhmmss), elle est donc conforme au format du champ transaction_id (6 caractères numériques). Si vous transmettez le transaction_id à l exécutable request, la valeur fournie sera prise en compte pour la transaction. WARNING : Etant donné que la génération automatique du transaction_id s appuie sur l heure système pour générer un numéro de transaction, on notera deux inconvénients : tout d abord on ne couvre que nombres (24h*60mn*60s) et non pas toute la plage possible de numéros de transaction ( à ). Ceci peut être gênant pour de très gros sites, le numéro de transaction devant être unique sur une journée. D autre part, il subsiste un risque de doublons, si deux internautes distincts souhaitant payer au même instant appellent le script call_request dans la même seconde. Une des deux transactions sera alors nécessairement rejetée comme un doublon, pour la même cause d unicité que précédemment. Il sera donc toujours préférable de gérer un numéro de séquence pour le champ transaction_id sur le site web commerçant, plutôt que d utiliser la génération automatique. tél. : fax. : /13 3. LA REPONSE A UN PAIEMENT : CALL_RESPONSE Guide du programmeur pour Plug-in : PHP et Perl API v6 3.1.CHAMPS DE LA REPONSE Dans la réponse du paiement, on retrouve les champs généraux de la transaction tels merchant_id, amount, et currency_code, mais aussi les champs renseignés par le serveur E-Transactions suite à la demande d autorisation : response_code, payment_certificate, etc Le DICTIONNAIRE DES DONNEES fournit la liste des champs de la réponse et leur description. Le serveur E-Transactions renvoie les données de la transaction en méthode POST et de façon cachée. En fait, elle poste une variable DATA cryptée sur les URL normal_return_url et cancel_return_url renseignées dans la requête de paiement. L exécutable response décrypte cette variable et renseigne tous les champs de la réponse. 3.2.EXECUTABLE RESPONSE Après la validation des coordonnées bancaires de l internaute, le serveur E-Transactions affiche en cas d acceptation de la transaction une page de réponse. Cette page résume les données de la transaction, et présente un bouton RETOUR A LA BOUTIQUE qui reconnecte l internaute à l URL normal_return_url. Dans le cas d un refus de l autorisation par les serveurs bancaires, le serveur E-Transactions affiche une page de refus avec un bouton ANNULATION RETOUR A LA BOUTIQUE qui renvoie l internaute vers l URL cancel_return_url. Le bouton ANNULATION RETOUR A LA BOUTIQUE présent sur la page de saisie des coordonnées carte bancaire à le même effet que son homonyme de la page de refus. Dans chacun de ces cas, une variable cachée DATA contenant la chaîne de caractères cryptée des données de la transaction est postée sur l URL normal_return_url ou cancel_return_url. Ce mode permet au commerçant de reconnecter l internaute à son site, puisque le développeur a une totale liberté de paramétrage de ces URL. Il faut malgré tout s assurer que le serveur commerçant autorise la réception de données en méthode POST. Remarque : les URL de retour devront nécessairement pointer vers des CGI. En effet, certains serveurs n acceptent pas que l on poste des données sur des pages HTML statiques et retournent alors le message methode POST not allowed . Rien ne vous empêche par contre d écrire une page statique dans votre script call_response. Le script call_response récupère la variable DATA et la transmet en paramètre à l exécutable response qui va ensuite la décrypter et renseigner les différents champs de la réponse (l activation du mode DEBUG permet d afficher l ensemble des paramètres de la réponse du serveur de paiement). Utilisation : response message avec message une chaîne de caractère du type message=data L exécutable response peut prendre un ou deux paramètres. Le second paramètre qui peut être transmis est une chaîne de caractères du type pathfile=chemin_vers_le_pathfile pour spécifier la localisation du fichier pathfile (cf. paragraphe 2.2). Ainsi, l exécutable response peut prendre un ou deux paramètres en entrée. tél. : fax. : /13 Retour : L exécutable response retourne une chaîne de caractères composée de 32 chaînes de caractères séparées par des ! :!code!error!merchant_id!merchant_country!amount!transaction_id!payment_means!transmission_date!pa yment_time!payment_date!response_code!payment_certificate!authorisation_id!currency_code!card_num ber!cvv_flag!cvv_response_code!bank_response_code!complementary_code!complementary_info!return _context!caddie!receipt_complement!merchant_language!language!customer_id!order_id!customer_emai l!customer_ip_address!capture_day!capture_mode!data! avec code, le code retour du traitement. Deux valeurs sont possibles : 0 : l exécutable renseigne les champs de la réponse -1 : l exécutable retourne un message d'erreur dans la variable error. (cf. rubrique problèmes de fonctionnement). Tous les champs de la réponse sont donc disponibles au niveau du script call_response. 4. LA REPONSE AUTOMATIQUE : CALL_AUTORESPONSE 4.1.POURQUOI DEUX REPONSES Comme expliqué au paragraphe 3.2, l appel de l URL normal_return_url (ou cancel_return_url ) est déclenché par l internaute, lorsqu il clique sur le bouton RETOUR A LA BOUTIQUE du ticket électronique ou ANNULATION RETOUR A LA BOUTIQUE du ticket ou de la page de saisie des coordonnées bancaires. Par conséquent, il se peut qu aucune de ces URL ne soit déclenchée lors d un paiement, pour peu que l internaute perde sa connexion, ou tout simplement ferme son navigateur sans avoir cliqué sur un de ces boutons. Le commerçant risque alors d avoir une commande initialisée dans sa base de données, mais qui ne serait pas confirmée avant la réception de son journal des transactions le lendemain. Pour pallier ce cas, le serveur E-Transactions renvoie une réponse automatique de la transaction en même temps qu il affiche la page de réponse. Ce mode permet au commerçant d être informé systématiquement, et en temps réel, de toutes les transactions qui sont effectuées sur son site. Notre serveur appelle une seule fois par paiement le script de la réponse automatique. Vous devez donc vous assurer que votre serveur soit toujours opérationnel et qu'il n'y ait pas de perte de données bloquantes pour la vente dans le cas contraire. 4.2.PRINCIPE DE FONCTIONNEMENT La réponse automatique ressemble en tous points à la réponse manuelle, c est à dire que le serveur poste la même variable DATA cryptée que celle de la réponse manuelle sur l URL automatic_response_url. La différence majeure est que l envoi de cette réponse automatique est fait par le serveur E-Transactions, et non pas par le navigateur de l internaute. L absence de navigateur implique des différences du point de vue du traitement de cet appel. Le script call_autoresponse ne peut pas faire d affichage, ni de redirection (pas de navigateur à l écoute). On ne peut y effectuer que des traitements automatiques, tels une mise à jour de base de données, un envoi de mail, ou tout simplement une auvegarde des données dans un fichier comme cela est présenté dans l exemple. 4.3.IMPLEMENTATION DU SCRIPT CALL_AUTORESPONSE Le script call_autoresponse est très proche du script call_response. Ce script récupère tout d abord la variable cryptée DATA et la transmet à l exécutable response. Le chemin vers le pathfile peut également être transmis en paramètre à l exécutable response (cf. paragraphe 2.2). L exécutable response renverra un message d erreur ou la liste des champs composant la réponse. A ce stade, vous vous trouvez en possession de toutes les données de la transaction. tél. : fax. : /13 Le traitement qui suit est au libre choix du commerçant, en fonction de son système d information. (mise à jour de base données, envoi de mail, ). Dans le script d exemple call_autoresponse, les messages d erreur et les champs de la réponse sont sauvegardés dans un fichier. Si votre script call_autoresponse ne fonctionne pas, consultez la rubrique problèmes de fonctionnement. tél. : fax. : /13 5. PROBLEMES DE FONCTIONNEMENT Vous trouverez ci-dessous les messages d erreur qui apparaissent le plus souvent durant la phase d installation, et la manière de les résoudre. 5.1.LORSQUE L ON APPELLE L API Le message s affiche sur la page sur laquelle on devrait voir les logos des cartes dans ce cas, les logos ne s affichent pas. Un message d erreur (Ex : Error in call parameters structure (merchant_id not filled) ) est constitué de deux parties : le message d erreur (ex : Error in call parameters structure) le code diagnostic ( ex : merchant_id not filled ) Ci-dessous vous trouverez les principaux messages renvoyés par l API. Message Cause solution erreur appel request Le script call_request ne peut pas Vérifiez le chemin et les droits executable request non trouve lancer l exécutable request d exécution du fichier request. Invalid Keyword in parameter Le paramètre toto n est pas une Les seuls mots clés utilisables sont (toto=12) clé valide de l API ceux décrits dans l annexe A Error parameter Le paramètere passé à l API est Contrôlez la taille du paramètre (transaction_id= ) too long trop long grâce au DICTIONNAIRE DES DONNEES Error reading pathfile (chemin du L API ne peut pas ouvrir le fichier Vérifiez le chemin et les droits de fichier pathfile) «chemin du fichier pathfile» lecture du fichier pathfile. Error reading pathfile (no keyword Le fichier pathfile ne contient pas Vérifier la présence du mot clé F_CERTIFICATE) le mot clé F_CERTIFICATE F_CERTIFICATE dans le fichier pathfile Error reading pathfile (no keyword Le fichier pathfile ne contient pas Vérifier la présence du mot clé F_PARAM) le mot clé F_PARAM F_PARAM dans le fichier
Search Related
We Need Your Support
Thank you for visiting our website and your interest in our free products and services. We are nonprofit website to share and download documents. To the running of this website, we need your help to support us.

Thanks to everyone for your continued support.

No, Thanks
SAVE OUR EARTH

We need your sign to support Project to invent "SMART AND CONTROLLABLE REFLECTIVE BALLOONS" to cover the Sun and Save Our Earth.

More details...

Sign Now!

We are very appreciated for your Prompt Action!

x