Paiement sécurisé sur Internet. Documentation Technique

Transcription

1 Paiement sécurisé sur Internet Documentation Technique

2 SOMMAIRE Documentation Technique 1 1 Mise en place de l interface de paiement Introduction Clé de sécurité commerçant Spécifications des messages échangés 4 2 Demander la mise en recouvrement d une demande de paiement Présentation Appel au service de demande de capture Réponse de la demande de capture 23 3 Demander une annulation de paiement ou une annulation de récurrence Annulation de paiement Annulation de récurrence 27 4 Le service de remboursement (recrédit) Présentation Appel au service de recrédit Réponse de la demande de recrédit 32 5 Aides à l installation Passer un TPE en production Foire aux questions Les problèmes les plus fréquents 38 6 Le fichier récapitulatif 43 7 Assistance technique 45 8 Annexes Contraintes générales de codage HTML des champs Contraintes particulières selon le champ URLs des services 47 Services Page de paiement / Capture / Recrédit - Page 2 / 48

3 1 Mise en place de l interface de paiement 1.1 Introduction L intégration de la plate-forme de paiement CM-CIC p@iement dans la cinématique de paiement par carte bancaire sur votre site consiste à mettre en œuvre deux interfaces dans votre système d information : Interface «Aller» : génération d un formulaire de demande de paiement, sécurisé par un sceau, qui accompagnera votre client lorsque vous le redirigez sur notre plate-forme de paiement Interface «Retour» : réception de la confirmation du paiement que nous envoyons après chaque demande de paiement Le travail à réaliser nécessite des compétences avancées en programmation : recevoir et contrôler des paramètres en méthode POST manipuler des chaînes de caractères utiliser une fonction ou une classe conforme à la RFC2104 implémentant le HMAC SHA1 ou MD5 sauvegarder le contexte de paiement en fichier ou base de données suivre le déroulement pas à pas d un programme dans un outil de débogage ou en programmant des traces. A titre d information, des exemples de ces deux interfaces vous sont fournis avec la documentation, dans les langages de programmation les plus courants (PHP, VB.NET, C#.NET, ASP, Python, Ruby, Java et C++). Vous pourrez utiliser ces exemples comme point de départ, mais vous devrez les modifier selon les spécificités de votre environnement et de votre application. En particulier, le stockage des clés devra être revu pour exploiter les meilleurs outils de confidentialité disponibles dans votre environnement. 1.2 Clé de sécurité commerçant Une clé de sécurité, propre à chaque TPE, destinée à certifier les données échangées entre le serveur du commerçant et le serveur de paiement sécurisé de la banque, est indispensable pour utiliser le service de paiement par carte bancaire. Un lien, permettant de télécharger cette clé de sécurité, est envoyé par notre centre de support au commerçant. Le commerçant peut demander la régénération d une nouvelle clé, périodiquement ou à l occasion d évènements tels qu une mise en production, un changement d hébergeur, un changement de prestataire, etc. Il est de la responsabilité du commerçant de conserver cette clé de façon sûre et confidentielle en exploitant les meilleurs outils disponibles dans son environnement. Services Page de paiement / Capture / Recrédit - Page 3 / 48

4 La clé de sécurité est représentée de façon externe par 40 caractères hexadécimaux (par exemple : ABCDEF ABCDEF ). Cette représentation externe doit être convertie en une chaîne de 20 octets (représentation opérationnelle) avant utilisation. L ancienne clé reste reconnue par le système lors de la génération d une nouvelle clé. C est une utilisation avec succès de la nouvelle clé (en environnement de test, en environnement de production) qui viendra définitivement invalider l ancienne (pour l environnement respectif). 1.3 Spécifications des messages échangés Rappel de la cinématique Action Le serveur commerçant obtient l accord de l internaute sur la chose et le prix Le serveur du commerçant rassemble les données du paiement à effectuer puis créé le formulaire de paiement scellé puis met en page ce formulaire de paiement à destination de l internaute L internaute clique sur le bouton correspondant au formulaire de paiement et accède au serveur de paiement Le serveur bancaire vérifie la validité du sceau et entame le dialogue de paiement avec l internaute L internaute dialogue avec le serveur bancaire et paye (ou ne paye pas) par carte bancaire Le serveur bancaire renvoie un résultat de paiement scellé au serveur du commerçant sur son interface «Retour» Le serveur du commerçant vérifie la validité du sceau puis prend en compte le résultat de paiement puis renvoie un accusé de réception au serveur bancaire Le serveur affiche à l internaute le résultat du paiement 1 L internaute peut imprimer (ou sauvegarder) cette page 1 Le serveur propose à l internaute de revenir sur le site du commerçant via un lien hypertexte 1 S il suit ce lien, l internaute quitte le serveur de paiement et revient sur le site du commerçant 1 Le serveur du commerçant adapte son dialogue en fonction du résultat de paiement reçu Intervenant Site web du commerçant Interface «Aller» sur le serveur du commerçant Serveur de paiement de la banque Interface «Retour» sur le serveur du commerçant Serveur de paiement de la banque Site web du commerçant 1 Le retour automatisé vers le site marchand sans action complémentaire de l utilisateur est disponible en option. Dans ce cas : le serveur de paiement de la banque va produire une page redirigeant le porteur sur l URL appropriée au résultat de la demande d autorisation. Le ticket de paiement est envoyé par mail. Services Page de paiement / Capture / Recrédit - Page 4 / 48

5 1.3.2 Interface «Aller» Création du formulaire Les paramètres du terminal et les données de la commande sont regroupées en un formulaire HTML scellé afin de transmettre la demande de paiement au serveur de la banque via le navigateur du client. Utilisez uniquement les champs cités dans le paragraphe lors de vos appels à la page de paiement. L emploi de champs non référencés pourrait amener un blocage lors de l accès à la page de paiement, cet accès étant considéré comme non légitime. Les champs à fournir dans le formulaire sont fournis dans le tableau ci-dessous : Champs Description Remarque version Version du système de paiement utilisée Version actuelle 3.0 TPE Numéro de TPE Virtuel du commerçant. Exemple : Taille : 7 caractères date Date de la commande au format JJ/MM/AAAA:HH:MM:SS montant Montant TTC de la commande formaté de Exemples : la manière suivante : Un nombre entier Un point décimal (optionnel) Un nombre entier de n chiffres : n étant le nombre maximal de décimales de la devise (optionnel) reference texte-libre mail lgue societe url_retour Une devise sur 3 caractères alphabétiques ISO4217 (EUR, USD, GBP, CHF, etc.) Référence unique de la commande. Taille : 12 caractères alphanumériques maximum Zone de texte libre. Taille : 3200 caractères maximum Adresse de l internaute Code langue Taille : 2 caractères Code alphanumérique permettant au commerçant d utiliser le même TPE Virtuel pour des sites différents (paramétrages distincts) se rapportant à la même activité URL par laquelle l acheteur revient sur la page d accueil de la boutique Exemple : 05/12/2006:11:55: EUR 10GBP 1024USD Exemple : ABERTYP00145 Valeurs possibles : DE EN ES FR IT JA NL PT SV Ce code est fourni par nos services. Exemple : monsite1 Services Page de paiement / Capture / Recrédit - Page 5 / 48

6 url_retour_ok URL par laquelle l acheteur revient sur le site du commerçant suite à un paiement accepté url_retour_err URL par laquelle l acheteur revient sur le site du commerçant suite à un paiement refusé MAC Sceau issu de la certification des données Taille : 40 caractères hexadécimaux options Liste des options utilisées (peut être vide). Chaque option est séparée des autres par un caractère &. Si l option a une valeur, le nom est séparé de la valeur par le caractère =. bouton Le bouton de paiement qui est automatiquement soumis par le navigateur. Le nom doit être exclusivement composé de caractères alpha numériques. Attention : à ne pas confondre avec l URL de l interface «Retour», aussi appelée URL de confirmation des paiements Exemple : opttest=abc&optbis=1 23 Exemples de noms : bouton bouton_paiement Page_de_Paiement1 Exemple de valeur : Payer Liste des options possibles : Options Description Remarque aliascb Alias de la carte bancaire d un client en cas de souscription de l option «paiement express» Format : [a-za-z0-9]{1,64} forcesaisiecb 3dsdebrayable Permet de forcer la saisie d une carte bancaire en cas de souscription de l option «paiement express» Permet de forcer le débrayage de 3DSecure Exemple : aliascb=client1 Exemple : forcesaisiecb=1 Exemple : 3dsdebrayable=1 Remarque : Lorsque le nom ou la valeur de l option est incorrect, la demande de paiement est interrompue et un message d erreur, indiquant que le formulaire est erroné, est affiché sur la page Liste des champs propres au paiement fractionné Les champs suivants sont spécifiques au mode de paiement fractionné : Champs Description Remarque nbrech Nombre d échéances pour cette Exemple : 4 commande (entre 2 et 4 maximum) dateech1 Date de la première échéance au format JJ/MM/AAAA Exemple : 25/04/2008 Services Page de paiement / Capture / Recrédit - Page 6 / 48

7 montantech1 dateech[n] (N entre 2 et 4) montantech[n] (N entre 2 et 4) Remarque : La première échéance correspond à la date de la commande. Montant TTC de l échéance formaté de la manière suivante : Un nombre entier Un point décimal (optionnel) Un nombre entier de n chiffres : n étant le nombre maximal de décimales de la devise (optionnel) Une devise sur 3 caractères alphabétiques ISO4217 (EUR, USD, GBP, CHF, etc.) Date de la Nième échéance au format JJ/MM/AAAA Montant TTC de la Nième échéance formaté de la manière suivante : Un nombre entier Un point décimal (optionnel) Un nombre entier de n chiffres : n étant le nombre maximal de décimales de la devise (optionnel) Une devise sur 3 caractères alphabétiques ISO4217 (EUR, USD, GBP, CHF, etc.) Exemples : 62.73EUR 10GBP 1024USD Exemple : 05/06/2008 Exemples : 62.73EUR 10GBP 1024USD - Pour pouvoir utiliser ces champs, votre TPE doit être configuré pour accepter les paiements en N fois ; - Tous ces champs sont optionnels : si vous ne les fournissez pas, les paramètres mis en place à la création de votre TPE seront pris en compte ; - La somme des montants de chaque échéance doit être égale au montant de la commande ; - Les montants doivent être dans la même devise ; - Les échéances doivent être mensuelles. - En cas d expiration de CB avant la dernière échéance : o la commande peut être refusée ou : o les échéances suivant la date d expiration peuvent être reportées sur la première échéance. Services Page de paiement / Capture / Recrédit - Page 7 / 48

8 Exemple de formulaire de paiement en HTML <form method="post" name="cmcicformulaire" target="_top" action=" <input type="hidden" name="version" value="3.0"> <input type="hidden" name="tpe" value=" "> <input type="hidden" name="date" value="05/12/2006:11:55:23"> <input type="hidden" name="montant" value="62.73eur"> <input type="hidden" name="reference" value="abertpy00145"> <input type="hidden" name="mac" value="78bc376c5b192f1c cbdb0050f156b9a2"> <input type="hidden" name="url_retour" value=" <input type="hidden" name="url_retour_ok" value=" <input type="hidden" name="url_retour_err" value=" <input type="hidden" name="lgue" value="fr"> <input type="hidden" name="societe" value="monsite1"> <input type="hidden" name="texte-libre" value="exempletextelibre"> <input type="hidden" name="mail" <input type="submit" name="bouton" value="paiement CB"> </form> Exemple de formulaire de paiement fractionné en HTML <form method="post" name="cmcicformulaire" target="_top" action=" <input type="hidden" name="version" value="3.0"> <input type="hidden" name="tpe" value=" "> <input type="hidden" name="date" value="05/12/2006:11:55:23"> <input type="hidden" name="montant" value="100eur"> <input type="hidden" name="reference" value="abertpy00145"> <input type="hidden" name="mac" value="78bc376c5b192f1c cbdb0050f156b9a2"> <input type="hidden" name="url_retour" value=" <input type="hidden" name="url_retour_ok" value=" <input type="hidden" name="url_retour_err" value=" <input type="hidden" name="lgue" value="fr"> <input type="hidden" name="societe" value="monsite1"> <input type="hidden" name="texte-libre" value="exempletextelibre"> <input type="hidden" name="mail" <input type="hidden" name="nbrech" value="3"> <input type="hidden" name="dateech1" value="05/12/2006"> <input type="hidden" name="montantech1" value="50eur"> <input type="hidden" name="dateech2" value="25/01/2007"> <input type="hidden" name="montantech2" value="25eur"> <input type="hidden" name="dateech3" value="25/02/2007"> <input type="hidden" name="montantech3" value="25eur"> <input type="submit" name="bouton" value="paiement CB"> </form> Services Page de paiement / Capture / Recrédit - Page 8 / 48

9 Calcul du sceau du formulaire Le sceau (à mettre dans le champ MAC) est calculé à l aide d une fonction de hachage cryptographique en combinaison avec une clé secrète respectant les spécifications de la RFC Cette fonction générera le sceau à partir de données à certifier et de la clé de sécurité commerçant sous sa forme opérationnelle. Les données à certifier seront présentées sous la forme d une concaténation dans un ordre précis des informations du formulaire : <TPE>*<date>*<montant>*<reference>*<texte-libre>* <version>*<lgue>*<societe>*<mail>*<nbrech>*<dateech1>*<monta ntech1>*<dateech2>*<montantech2>*<dateech3>*<montantech3>*<d ateech4>*<montantech4>*<options> Exemple pour un paiement «classique» : *05/12/2006:11:55:23*62.73EUR*ABERTYP00145*Exemple TexteLibre*3.0*FR*monSite1*internaute@son .fr********* * Exemple pour un paiement fractionné : *05/12/2006:11:55:23*62.73EUR*ABERTYP00145*Exemple TexteLibre*3.0*FR*monSite1*internaute@son .fr*4*05/12/ 2006*16.23EUR*05/01/2007*15.5EUR*05/02/2007*15.5EUR*05/03/ 2007*15.5EUR* Services Page de paiement / Capture / Recrédit - Page 9 / 48

10 1.3.3 Interface «Retour» Après avoir traité la demande de paiement, le serveur de la banque informe directement le serveur du commerçant du résultat de la demande de paiement en émettant une requête HTTP on-line, contenant le résultat de la demande de paiement, sur l URL de confirmation des paiements (interface «Retour»). Cette URL doit nous être indiquée au moment de la mise en place du système. Remarque : L interface retour est appelée après chaque tentative de paiement d une même commande, pour en indiquer le résultat. Il est donc possible que l interface retour reçoive plusieurs notifications de paiements refusés puis une notification de paiement accepté pour une même référence. L interface de retour dispose de 30 secondes pour répondre comme décrit au chapitre , page 18. Le cas du dépassement de délai est interprété comme une erreur dans l interface de retour marchand. Lorsque qu une réponse erronée est fournie et que le paiement est accepté : un second appel est réalisé (sauf cas réalisant une redirection immédiate sur le site marchand) Paramètres renvoyés par la banque L interface «Retour» sera appelée par le serveur de la banque avec la méthode POST. Les données envoyées par le serveur de la banque sont décrites ci-dessous : Champs Description Remarque MAC Sceau résultant de la certification des données Date Date de la demande d autorisation de la commande au format JJ/MM/AAAA_a_HH:MM:SS TPE Numéro de TPE Virtuel du commerçant montant Montant TTC de la commande formaté de la manière suivante : Un nombre entier Un point décimal (optionnel) Un nombre entier (optionnel) Une devise sur 3 caractères alphabétiques ISO4217 (EUR, USD, GBP, CHF, etc.) reference texte-libre Référence unique de la commande Zone de texte libre Le serveur de la banque renvoie ici les données telles qu elles ont été reçues lors de la phase «Aller» du paiement Services Page de paiement / Capture / Recrédit - Page 10 / 48

11 code-retour Le résultat du paiement, parmi : payetest paiement accepté (en TEST uniquement) paiement paiement accepté (en Production uniquement) Annulation paiement refusé En paiement fractionné, pour les mises en recouvrement automatique des échéances de rang > 1 : paiement_pf[n] paiement accepté de l échéance N (N entre 2 et 4) Annulation_pf[N] paiement refusé définitivement de l échéance N (N entre 2 et 4) cvx oui si le cryptogramme visuel (obligatoire pour les cartes Visa et MasterCard) a été saisi non sinon vld Date de validité de la carte de crédit utilisée pour effectuer le paiement brand Code réseau de la carte sur 2 positions alphabétiques parmi. AM American Express CB GIE CB MC VI na Mastercard Visa Non disponible status3ds Indicateur d échange 3DSecure : -1 : la transaction ne s est pas faite selon le protocole 3DSecure, le risque d impayé est élevé 1 : la transaction s est faite selon le protocole 3DSecure et le risque d impayé est faible 4 : la transaction s est faite selon le protocole 3DSecure et le risque d impayé est élevé numauto Numéro d autorisation tel que fourni par la banque émetteur En cas de paiement refusé, une autorisation ultérieure pourra encore être délivrée pour la même référence. Le code «payetest» n est envoyé que pour des paiements effectués dans l environnement de validation. Si ce code est présent lors d un paiement en production, il s agit d une anomalie. Uniquement dans le cas où l autorisation a été accordée Services Page de paiement / Capture / Recrédit - Page 11 / 48

12 motifrefus Motif du refus de la demande de paiement : Appel Phonie : la banque du client demande des informations complémentaires Refus : la banque du client refuse d accorder l autorisation Interdit : la banque du client refuse d accorder l autorisation filtrage : la demande de paiement a été bloquée par le paramétrage de filtrage que le commerçant a mis en place dans son Module Prévention Fraude scoring : la demande de paiement a été bloquée par le paramétrage de scoring que le commerçant a mis en place dans son Module Prévention Fraude 3DSecure : si le refus est lié à une authentification 3DSecure négative reçue de la banque du porteur originecb Code pays de la banque émettrice de la carte bancaire (norme ISO ) bincb Code BIN de la banque du porteur de la carte de crédit hpancb Hachage irréversible (HMAC-SHA1) du numéro de la carte de crédit utilisée pour effectuer le paiement (identifiant de manière unique une carte de crédit pour un commerçant donné) ipclient Adresse IP du client ayant fait la transaction originetr Code pays de l origine de la transaction (norme ISO ) veres Etat 3DSecure du VERes En cas de souscription pares Etat 3DSecure du PARes Uniquement dans le cas où la demande de paiement a été refusée. Uniquement en cas de souscription du module prévention fraude du module prévention fraude et de l option 3Dsecure montantech Montant de l échéance en cours Uniquement dans le cas du paiement fractionné Services Page de paiement / Capture / Recrédit - Page 12 / 48

13 filtragecause filtragevaleur cbenregistree cbmasquee Numéros des types de filtres bloquant le paiement (cf. tableau «Retours Module Prévention Fraude détails» ci-dessous) 1 : Adresse IP 2 : Numéro de carte 3 : BIN de carte 4 : Pays de la carte 5 : Pays de l IP 6 : Cohérence pays de la carte / pays de l IP 7 : jetable 8 : Limitation en montant pour une CB sur une période donnée 9 : Limitation en nombre de transactions pour une CB sur une période donnée 11 : Limitation en nombre de transactions par alias sur une période donnée 12 : Limitation en montant par alias sur une période donnée 13 : Limitation en montant par IP sur une période donnée 14 : Limitation en nombre de transactions par IP sur une période donnée 15 : Testeurs de cartes 16 : Limitation en nombre d alias par CB Données ayant engendrées le blocage Booléen indiquant si la carte a été enregistrée sous un aliascb donné : 1 : Le client a saisi une carte bancaire et elle a été enregistré sous l aliascb envoyé 0 : Tous les autres cas 6 premiers et 4 derniers chiffres de la carte bancaire du client, séparés par des étoiles, uniquement lors de l enregistrement de la carte bancaire motifdebrayage Motif pour lequel 3DSecure a été débrayé commercant : Lors de la phase aller, l option 3dsdebrayable=1 a été utilisée. seuilnonatteint : Le montant de la transaction est inférieure au seuil paramétré modepaiement Moyen de paiement utilisé CB paypal 1euro 3xcb audiotel Uniquement dans le cas d un filtrage du paiement. Si plusieurs filtres bloquent le paiement, ceux-ci sont séparés par des tirets. Les causes et les valeurs correspondantes étant dans le même ordre. Uniquement en cas de souscription de l option paiement express Uniquement en cas de souscription de l option paiement express. Exemple : ******7890 Uniquement en cas de souscription de l option 3DSecure debrayable Services Page de paiement / Capture / Recrédit - Page 13 / 48

14 Retours Module Prévention Fraude Détails La fonctionnalité de filtrage des paiements s appuie sur un ensemble de neuf filtres, librement paramétrable sur le tableau de bord (nouvelle version). Chacun de ces filtres agit sur un critère spécifique, comme l adresse IP du client, son adresse , le pays de sa carte bancaire Numéro du type de filtre Critère d analyse Valeur retournée comme raison du blocage 1 Adresse IP Adresse IP du client 2 Numéro de carte Hash de la carte du client 3 BIN de carte Bin de la carte du client 4 Pays de la carte Pays de la carte du client 5 Pays de l IP Pays de l IP du client 6 Cohérence pays de la carte / pays de l IP Pays de la carte # Pays de l adresse IP du client 7 jetable Nom de domaine de l adresse du client 8 Limitation en montant pour une CB sur une période donnée 9 Limitation en nombre de transactions pour une CB sur une période donnée 11 Limitation en nombre de transactions par alias sur une période donnée 12 Limitation en montant par alias sur une période donnée 13 Limitation en montant par IP sur une période donnée 14 Limitation en nombre de transactions par IP sur une période donnée Montant cumulé en euros ( ) sur la période donnée associé à la carte du client Nombre de transactions cumulées sur la période donnée associée à la carte du client Nombre de transactions cumulées sur la période donnée associée à l alias du client Montant cumulé en euros ( ) sur la période donnée associé à l alias du client Montant cumulé en euros ( ) sur la période donnée associé à l adresse IP du client Nombre de transactions cumulées sur la période donnée associée à l adresse IP du client 15 Testeurs de cartes Nombre de transactions cumulées sur la période Remarque Fonctionne uniquement pour les paiements par carte Fonctionne uniquement pour les paiements par carte Fonctionne uniquement pour les paiements par carte Uniquement en cas de souscription de l option paiement express Services Page de paiement / Capture / Recrédit - Page 14 / 48

15 16 Limitation en nombre d alias par CB donnée associée à l adresse IP du client Les alias déjà associés à la carte utilisée pour le paiement Uniquement en cas de souscription de l option paiement express Fonctionne uniquement pour les paiements par carte. Exemple de données envoyées par le serveur de paiement de la banque à l interface «Retour» pour un paiement immédiat, différé, partiel ou récurrent : TPE= &date=05%2f12%2f2006%5fa%5f11%3a55%3a23&montant=62% 2e75EUR&reference=ABERTYP00145&MAC=e4359a2c18d86cf2e4b0e c202e89947b04&texte-libre=letextelibre&coderetour=paiement&cvx=oui&vld=1208&brand=vi&status3ds=1&numauto= &originecb=FRA&bincb=010101&hpancb=74E94B03C22D786E0F2C2 CADBFC1C00B004B7C45&ipclient=127%2e0%2e0%2e1&originetr=FRA&ver es=y&pares=y Exemple de données envoyées par le serveur de paiement de la banque à l interface «Retour» pour la première échéance d un paiement fractionné : TPE= &date=05%2f12%2f2006%5fa%5f11%3a55%3a23&montant=62% 2e75EUR&reference=ABERTYP00145&MAC=e4359a2c18d86cf2e4b0e c202e89947b04&texte-libre=letextelibre&coderetour=paiement&cvx=oui&vld=1208&brand=vi&status3ds=1&numauto= &originecb=FRA&bincb=010101&hpancb=74E94B03C22D786E0F2C2 CADBFC1C00B004B7C45&ipclient=127%2e0%2e0%2e1&originetr=FRA&ver es=y&pares=y&montantech=20eur Exemple de données envoyées par le serveur de paiement de la banque à l interface «Retour» pour un blocage d un paiement immédiat par le MPF: TPE= &date=05%2f10%2f2011%5fa%5f15%3a33%3a06&montant=1%2 e01eur&reference=p &mac=70156d2cff27a9b8aae5afebe590d 9CFCAAF9BDC&textelibre=Ceci+est+un+test%2c+ne+pas+tenir+compte%2e&coderetour=Annulation&cvx=oui&vld=0912&brand=MC&status3ds=- 1&motifrefus=filtrage&originecb=FRA&bincb=513283&hpancb=764AD2 4CFABBB818E8A7DC61D4D6B4B89EA837ED&ipclient=10%2e45%2e166%2e76 &originetr=inconnue&veres=&pares=&filtragecause=4- &filtragevaleur=fra- Exemple de données envoyées par le serveur de paiement de la banque à l interface «Retour» pour un paiement avec l option paiement express : Services Page de paiement / Capture / Recrédit - Page 15 / 48

16 TPE= &date=05%2f12%2f2006%5fa%5f11%3a55%3a23&montant=62% 2e75EUR&reference=ABERTYP00145&MAC=e4359a2c18d86cf2e4b0e c202e89947b04&texte-libre=letextelibre&coderetour=paiement&cvx=oui&vld=1208&brand=vi&status3ds=1&numauto= &originecb=FRA&bincb=010101&hpancb=74E94B03C22D786E0F2C2 CADBFC1C00B004B7C45&ipclient=127%2e0%2e0%2e1&originetr=FRA&cbe nregistree=1&cbmasquee=123456******7890 Remarque : Les pays sont désignés par leur code iso de trois lettres selon la norme ISO alpha-3. Services Page de paiement / Capture / Recrédit - Page 16 / 48

17 Validation du sceau Le message de confirmation reçu est scellé par un sceau MAC qui a été calculé par le serveur de paiement de la banque à l aide de la clé de sécurité commerçant attribuée à votre terminal de paiement. Une fonction de validation du sceau doit être implémentée dans l interface «Retour» pour s assurer qu il n y a pas eu de falsification des données contenues dans le message de confirmation du paiement reçu. Pour cela, la fonction doit recalculer le code MAC associé au message et le comparer à celui transmis dans le message : si les deux codes sont identiques, l information reçue est fiable (intégrité des informations et authentification de l émetteur). Pour calculer le MAC il faut utiliser une fonction de hachage cryptographique en combinaison avec une clé secrète respectant les spécifications de la RFC Cette fonction générera le sceau à partir de données à certifier et de la clé de sécurité commerçant sous sa forme opérationnelle. Les données à certifier seront présentées sous la forme d une concaténation dans un ordre précis des informations envoyées par le serveur de la banque : <TPE>*<date>*<montant>*<reference>*<texte-libre>*3.0*<coderetour>*<cvx>*<vld>*<brand>*<status3ds>*<numauto>*<motifrefu s>*<originecb>*<bincb>*<hpancb>*<ipclient>*<originetr>*<vere s>*<pares>* Exemple si vous êtes inscrit au module prévention fraude et à l option 3DSecure et le paiement est accepté : *05/12/2006_a_11:55:23*62.75EUR*ABERTYP00145*LeTexteL ibre*3.0*paiement*oui*1208*vi*1*010101**fra*010101*74e94b03c 22D786E0F2C2CADBFC1C00B004B7C45* *FRA*Y*Y* Services Page de paiement / Capture / Recrédit - Page 17 / 48

18 Création de l accusé de réception La réponse renvoyée par l interface «Retour» au serveur de paiement de la banque doit être un des deux messages présentés dans le tableau ci-dessous, dépendant seulement de la vérification du sceau MAC reçu, sans tenir compte de la valeur du code-retour de paiement, dès lors que cette valeur fait partie de la liste des valeurs énumérées pour le champ code-retour. Sceau validé Oui Non Accusé de réception à renvoyer au format texte version=2<lf> cdr=0<lf> version=2<lf> cdr=1<lf> Remarque : <LF> correspond à un saut de ligne Lorsque le serveur de la banque ne reçoit pas l accusé de réception pour un sceau validé, il envoie un courriel d alerte sur une boîte aux lettres électronique de surveillance indiquée par le commerçant et refait une seconde tentative. Ce courriel contient un lien permettant de rejouer via la méthode GET la requête émise par le serveur bancaire, un code de l erreur rencontrée lors de l appel de l url de confirmation et l accusé de réception renvoyé par le serveur commerçant. Dès la phase de test, le commerçant doit nous fournir l adresse d une boîte aux lettres électronique régulièrement relevée. Pour passer en production, le serveur commerçant doit avoir renvoyé un accusé de réception avec un sceau validé pour les trois derniers tests. Services Page de paiement / Capture / Recrédit - Page 18 / 48

19 2 Demander la mise en recouvrement d une demande de paiement 2.1 Présentation Le but du service Capture_Paiement est de permettre aux commerçants de mettre en recouvrement, par requête informatique et de manière sécurisée, les paiements qui ont été préalablement autorisés. Ce service peut être utilisé avec les modes de paiement suivants : - paiement différé - paiement partiel - paiement fractionné (pour la première échéance uniquement) - paiement récurrent (selon la configuration choisie) Pour demander une mise en recouvrement, l application du commerçant doit faire appel au service web de capture du serveur de la banque (via un message HTTPS), en fournissant un certain nombre d informations (le montant de la commande, sa date, sa référence, le numéro du TPE virtuel du commerçant, etc.). Un sceau doit être calculé pour certifier les données échangées. En réponse à cette demande, le serveur de la banque retourne le résultat de la demande de capture à l application du commerçant : capture acceptée ou capture refusée. 2.2 Appel au service de demande de capture Les informations à fournir L application du commerçant doit émettre une requête en méthode POST par un message HTTPS (SSL V3), à destination du service Capture_Paiement sur les serveurs de la banque, contenant les champs suivants : Champs Description Remarque version Version du système de paiement utilisée Version actuelle 3.0 TPE Numéro de TPE Virtuel du commerçant exemple : Taille : 7 caractères date Date et heure de la demande de capture au format JJ/MM/AAAA:HH:MM:SS date_commande Date de la commande au format JJ/MM/AAAA montant Montant TTC de la commande initiale Format : montant_a_capturer - Un nombre entier Montant TTC de la demande de capture - Un point décimal montant_deja_capture Montant TTC correspondant au montant (optionnel) déjà capturé sur cette commande Exemple : 05/12/2006:11:55:23 Exemple : 03/12/2006 Services Page de paiement / Capture / Recrédit - Page 19 / 48

20 montant_restant Montant TTC correspondant au solde de la commande après la capture présentement demandée - Un nombre entier (optionnel) - Une devise sur 3 caractères alphabétiques ISO4217 (EUR, USD, etc.) Exemples : 62.73EUR 10GBP 1024USD reference Référence de la commande Exemple : ABERTYP00145 texte-libre Zone de texte libre lgue societe MAC stoprecurrence phonie Taille : 3200 caractères maxi. Code langue (en majuscules) Taille : 2 caractères Code alphanumérique permettant au commerçant d utiliser le même TPE Virtuel pour des sites différents (paramétrages distincts) se rapportant à la même activité Sceau issu de la certification des données Taille : 40 caractères hexadécimaux Force la fin de la récurrence pour les TPEs en paiement récurrent. La valeur de ce champ sera renvoyée en cas d appel phonie FR, EN, DE, IT, ES, NL, PT ou SV Ce code est fourni par nos services. Exemple : monsite1 Ce paramètre est optionnel. Ce paramètre est optionnel Les champs de cette requête (sauf la version et les montants) doivent tous être encodés en HTML. Les spécifications d encodage sont décrites en fin de document. Remarque : Il est possible qu une demande d autorisation soit refusée pour un motif du type «appel phonie» (montant trop élevé, centre d autorisation encombré, etc.). Il peut alors être nécessaire pour le commerçant de faire une demande manuelle (téléphone, fax) au centre d autorisation du porteur de la carte, qui communiquera en retour des coordonnées bancaires et du montant, un numéro d autorisation pour cette transaction Calcul du sceau Le sceau (à mettre dans le champ MAC) doit être calculé à l aide d une fonction de hachage cryptographique en combinaison avec une clé secrète respectant les spécifications de la RFC Les données à certifier seront présentées sous la forme d une concaténation dans un ordre précis des informations du formulaire : Services Page de paiement / Capture / Recrédit - Page 20 / 48

21 <TPE>*<date>*<montant_a_capturer><montant_deja_capture><mont ant_restant>*<reference>*<texte-libre>* <version>*<lgue>*<societe>* Exemples de requête de capture Exemple 1 : recouvrement partiel de 62 pour une commande initiale de 100 Chaîne utilisée pour le calcul du sceau : *05/12/2006:11:55:23*62.00EUR0EUR38EUR*ABERTYP00145* ExempleTexteLibre*3.0*FR*monSite1* Requête : POST /capture_paiement.cgi HTTP/1.0 Pragma: no-cache Connection: close User-Agent : AuthClient Host: paiement.creditmutuel.fr Accept: */* Content-type: application/x-www-form-urlencoded Content-length: 307 version=3.0 &TPE= &date=05%2f12%2f2006%3a11%3a55%3a23 &date_commande=03%2f12%2f2006 &montant=100.00eur &montant_a_capturer=62.00eur &montant_deja_capture=0eur &montant_restant=38.00eur &reference=abertpy00145 &texte-libre=exempletextelibre &lgue=fr &societe=monsite1 &MAC=78bc376c5b192f1c cbdb0050f156b9a2 La somme des 3 montants doit être égale au montant initial de la commande Cette capture ne peut s effectuer que si votre TPE est configuré en Paiement Partiel ou en Paiement Récurrent. En cas de succès, une capture ultérieure d un montant de 38 est encore réalisable. Services Page de paiement / Capture / Recrédit - Page 21 / 48

22 Exemple 2 : recouvrement total d une commande de 100 Chaîne utilisée pour le calcul du sceau : *05/12/2006:11:55:23*100.00EUR0EUR0EUR*ABERTYP00145* ExempleTexteLibre*3.0*FR*monSite1* Requête : POST /capture_paiement.cgi HTTP/1.0 Pragma: no-cache Connection: close User-Agent : AuthClient Host: paiement.creditmutuel.fr Accept: */* Content-type: application/x-www-form-urlencoded Content-length: 305 version=3.0 &TPE= &date=05%2f12%2f2006%3a11%3a55%3a23 &date_commande=03%2f12%2f2006 &montant=100.00eur &montant_a_capturer=100.00eur &montant_deja_capture=0eur &montant_restant=0eur &reference=abertpy00145 &texte-libre=exempletextelibre &lgue=fr &societe=monsite1 &MAC=78bc376c5b192f1c cbdb0050f156b9a2 Les 2 montants doivent être identiques Cette capture peut s effectuer si votre TPE est configuré en Paiement Partiel, en Paiement Récurrent ou en Paiement Différé. En cas de succès, aucune capture ultérieure n est réalisable. Services Page de paiement / Capture / Recrédit - Page 22 / 48

23 2.3 Réponse de la demande de capture Les informations retournées En réponse à la demande de capture, l application du commerçant reçoit un message d acquittement de la part du serveur de la banque. Ce message est un document de type MIME «text/plain» précisant le résultat de la capture. Il contient les champs suivants séparés par un caractère CHR(10) : Champs Description Remarque version Numéro de version du message Version actuelle : 1.0 d acquittement reference Référence de la commande Exemple : ABERTYP00145 cdr Code retour indiquant le résultat de la capture lib aut phonie Libellé détaillé précisant la nature du code retour Numéro d autorisation du paiement si celui-ci a été accepté Autorisation refusée pour un motif du type «appel phonie» Si cdr est différent de 1, la capture n a pas été effectuée. Valeurs possibles : 1 : capture acceptée 0 : capture refusée -1 : erreur Voir ci-dessous pour la liste des libellés possibles Ce champ n est présent que si le champ «phonie» était présent et renseigné dans la requête appelante La liste des valeurs disponibles pour le libellé est donnée dans le tableau suivant : cdr Libellés Description Remarque 1 paiement accepte L autorisation bancaire a été délivrée et la mise en recouvrement a été effectuée 1 commande annulee La demande d annulation a été prise en compte et la commande a été annulée 1 recurrence stoppee La demande d annulation définitive du renouvellement a été prise en compte 0 commande non authentifiee La référence ne correspond pas à une commande 0 commande expiree La date de commande dépasse le délai autorisé (+/- 24h) 0 commande grillee Le nombre maximal de tentatives de fourniture de Uniquement en Paiement Récurrent Vérifier les paramètres référence et date_commande La commande n est plus acceptée par le serveur bancaire Services Page de paiement / Capture / Recrédit - Page 23 / 48

24 carte a été atteint (3 tentatives sont acceptées) 0 autorisation refusee L autorisation bancaire n a pas été délivrée 0 la commande est deja annulee La commande a été annulée lors d une précédente capture 0 paiement deja accepte Une demande d autorisation a déjà été délivrée pour cette commande -1 signature non valide La signature MAC est invalide -1 verification echouee (mode de paiement) Le mode de paiement n est pas compatible avec cette requête -1 la demande ne peut La demande de capture est aboutir formulée de manière incorrecte -1 montant errone Un des montants transmis est -1 commercant non identifie mal formaté Les paramètres servant à identifier le site commerçant ne sont pas corrects -1 traitement en cours La commande est en cours de traitement -1 date erronee La date ne respecte pas le format requis -1 autre traitement en cours Une autre transaction est en cours de traitement sur la même référence -1 probleme technique Un problème technique est survenu La capture n est pas effectuée Aucune requête ne sera acceptée sur cette commande Par exemple : le paiement immédiat, car le recouvrement est fait automatiquement Vérifier les paramètres envoyés Vérifier les 4 paramètres de montant Vérifier les champs societe, lgue et TPE Vérifier le paramètre date Réitérer la demande Réitérer la demande Services Page de paiement / Capture / Recrédit - Page 24 / 48

25 2.3.2 Exemples de messages retournés Cas d une capture acceptée version=1.0 reference= cdr=1 lib=paiement accepte aut= Cas d une annulation acceptée version=1.0 reference= cdr=1 lib=commande annulee aut= Cas d une annulation de récurrence version=1.0 reference= cdr=1 lib=recurrence stoppee aut= Cas d une autorisation refusée sans le champ phonie fourni version=1.0 reference= cdr=0 lib=autorisation refusee Cas d une autorisation refusée au motif d appel phonie avec le champ phonie renseigné à «oui» version=1.0 reference= cdr=0 lib=autorisation refusee phonie=oui Cas d une autorisation refusée avec le champ phonie renseigné à «oui» version=1.0 reference= cdr=0 lib=autorisation refusee Cas d une capture refusée avant la demande d autorisation version=1.0 reference= cdr=0 lib=commande non authentifiee Cas d une erreur version=1.0 reference= cdr=-1 lib=commercant non identifie Services Page de paiement / Capture / Recrédit - Page 25 / 48

26 3 Demander une annulation de paiement ou une annulation de récurrence 3.1 Annulation de paiement Dans le cas où le commerçant a demandé un paiement et qu il ne souhaite pas le mettre en recouvrement (marchandise non disponible, client qui s est rétracté, etc.), il peut notifier le serveur de la banque de l abandon de sa demande de paiement. Pour cela, il appellera le service de capture comme décrit dans le chapitre précédent, en spécifiant le montant à capturer et le montant restant à 0EUR. Exemple : annuler une commande d un montant initial de 100 Chaîne utilisée pour le calcul du sceau : *05/12/2006:11:55:23*0EUR0EUR0EUR*ABERTYP00145*Exemp letextelibre*3.0*fr*monsite1* Requête : POST /capture_paiement.cgi HTTP/1.0 Pragma: no-cache Connection: close User-Agent : AuthClient Host: paiement.creditmutuel.fr Accept: */* Content-type: application/x-www-form-urlencoded Content-length: 299 version=3.0 &TPE= &date=05%2f12%2f2006%3a11%3a55%3a23 &date_commande=03%2f12%2f2006 &montant=100.00eur &montant_a_capturer=0eur &montant_deja_capture=0eur &montant_restant=0eur &reference=abertpy00145 &texte-libre=exempletextelibre &lgue=fr &societe=monsite1 &MAC=78bc376c5b192f1c cbdb0050f156b9a2 Le montant à capturer et le montant restant doivent être égaux à 0 Le montant déjà capturé doit correspondre à l historique de la commande Cette capture peut s effectuer si votre TPE est configuré en Paiement Partiel ou en Paiement Différé. En cas de succès, aucune capture ultérieure n est réalisable. Services Page de paiement / Capture / Recrédit - Page 26 / 48

27 3.2 Annulation de récurrence Si le commerçant ne souhaite pas poursuivre les renouvellements automatiques d un abonnement, il peut notifier le serveur de la banque de l abandon de la récurrence du paiement. Pour cela, il appellera le service de capture comme décrit dans le chapitre précédent, en spécifiant le montant à capturer et le montant restant à 0EUR et le champ stoprecurrence à OUI. Exemple : annuler la récurrence d une commande d un montant initial. Chaîne utilisée pour le calcul du sceau : *05/12/2006:11:55:23*0EUR0EUR0EUR*ABERTYP00145*Exemp letextelibre*3.0*fr*monsite1* Requête : POST /capture_paiement.cgi HTTP/1.0 Pragma: no-cache Connection: close User-Agent : AuthClient Host: paiement.creditmutuel.fr Accept: */* Content-type: application/x-www-form-urlencoded Content-length: 318 version=3.0 &TPE= &date=05%2f12%2f2006%3a11%3a55%3a23 &date_commande=03%2f12%2f2006 &montant=100.00eur &montant_a_capturer=0eur &montant_deja_capture=0eur &montant_restant=0eur &stoprecurrence=oui &reference=abertpy00145 &texte-libre=exempletextelibre &lgue=fr &societe=monsite1 &MAC=78bc376c5b192f1c cbdb0050f156b9a2 Le montant à capturer et le montant restant doivent être égaux à 0 Le montant déjà capturé doit correspondre à l historique de la commande Cette capture peut s effectuer si le TPE est configuré en Paiement Récurrent. En cas de succès, la commande ne sera plus renouvelée. Services Page de paiement / Capture / Recrédit - Page 27 / 48

28 4 Le service de remboursement (recrédit) 4.1 Présentation Le but du service Récrédit_Paiement est de permettre aux commerçants de rembourser leurs clients d une partie ou de la totalité de leur achat, de façon sécurisée, via Internet. Pour demander un remboursement, l application du commerçant doit faire appel au service web de recrédit du serveur de la banque (via un message HTTPS), en fournissant un certain nombre d informations (le montant du remboursement, sa date, sa référence, le numéro du TPE virtuel du commerçant, etc.). Un sceau doit être calculé pour certifier les données échangées. En réponse à cette demande, le serveur de la banque retourne le résultat de la demande de remboursement à l application du commerçant : acceptée ou refusée. 4.2 Appel au service de recrédit Les informations à fournir L application du commerçant doit émettre une requête en méthode POST par un message HTTPS (SSL V3), à destination du service Recredit_Paiement sur les serveurs de la banque, contenant les champs suivants : Champs Description Remarque version Version du système de paiement utilisée Version actuelle 3.0 TPE Numéro de TPE Virtuel du commerçant exemple : Taille : 7 caractères date Date et heure de la demande de recrédit au format JJ/MM/AAAA:HH:MM:SS date_commande Date initiale de la commande au format JJ/MM/AAAA date_remise Date à laquelle a eu lieu la mise en recouvrement au format JJ/MM/AAAA num_autorisation Numéro d autorisation renvoyé par le Exemple : 1234A6 serveur de la banque lors de la demande de paiement montant Montant TTC de la commande initiale Format : montant_recredit Montant TTC à recréditer montant_possible Montant TTC de recrédit maximum autorisé pour le numéro d autorisation fourni Exemple : 05/12/2006:11:55:23 Exemple : 03/12/2006 Exemple : 04/12/ Un nombre entier - Un point décimal (optionnel) - Un nombre entier (optionnel) - Une devise sur 3 caractères alphabétiques ISO4217 (EUR, USD, etc.) Services Page de paiement / Capture / Recrédit - Page 28 / 48

29 Exemples : 62.73EUR 10GBP 1024USD reference Référence de la commande à recréditer Exemple : ABERTYP00145 texte-libre Zone de texte libre Taille : 3200 caractères maximum lgue Code langue (en majuscules) Taille : 2 caractères societe Code alphanumérique à usage interne uniquement permettant au commerçant d utiliser le même TPE Virtuel pour des sites différents (paramétrages distincts) se Exemple : monsite1 rapportant à la même activité MAC Sceau issu de la certification des données Taille : 40 caractères hexadécimaux FR, EN, DE, IT, ES, NL, PT ou SV Ce code est fourni par nos services. Note : le champ «montant_possible» est nécessaire afin que le serveur commerçant et le serveur bancaire soient en phase. Si un remboursement a déjà été effectué sur ce numéro d autorisation, il doit être décompté par le commerçant. Par exemple, pour une commande de 100, si un remboursement de 10 a déjà été effectué, le prochain remboursement présentera une valeur de «montant_possible» de Calcul du sceau Le sceau (à mettre dans le champ MAC) est calculé à l aide d une fonction de hachage cryptographique en combinaison avec une clé secrète respectant les spécifications de la RFC Les données à certifier seront présentée sous la forme d une concaténation dans un ordre précis des informations de la requête : <TPE>*<date>*<montant_recredit><montant_possible>* <reference>*<texte-libre>*<version>*<lgue>*<societe>* Contrôle de l IP et limite du nombre de remboursements Pour des raisons de sécurité, les requêtes de remboursement ne peuvent être émises que depuis des serveurs avec une adresse IP connue de nos services. De plus, chaque adresse IP est limitée quotidiennement dans le nombre de requêtes de remboursement qu elle est autorisée à effectuer. Avant de pouvoir effectuer des requêtes de remboursement dans l environnement de production, il vous faudra donc communiquer par courriel à centrecom@e-i.com la liste des adresses IP à autoriser, ainsi que le nombre de remboursement quotidiens maximum pour chacune d entre elles. Services Page de paiement / Capture / Recrédit - Page 29 / 48

30 Pour des raisons de commodités, aucun contrôle n est effectué pour les requêtes de remboursement dans l environnement de test. Services Page de paiement / Capture / Recrédit - Page 30 / 48

31 4.2.4 Exemple de requête de recrédit Exemple 1 : recrédit partiel de 32 sur une commande de 100 Chaîne utilisée pour le calcul du sceau : *05/12/2006:11:55:23*32.00EUR100EUR*ABERTYP00145* ExempleTexteLibre*3.0*FR*monSite1* Requête : POST /recredit_paiement.cgi HTTP/1.0 Pragma: no-cache Connection: close User-Agent : AuthClient Host: paiement.creditmutuel.fr Accept: */* Content-type: application/x-www-form-urlencoded Content-length: 328 version=3.0 &TPE= &date=05%2f12%2f2006%3a11%3a55%3a23 &date_commande=03%2f12%2f2006 &date_remise=04%2f12%2f2006 &num_autorisation=1234a6 &montant=100.00eur &montant_recredit=32.00eur &montant_possible=100eur &reference=abertpy00145 &texte-libre=exempletextelibre &lgue=fr &societe=monsite1 &MAC=78bc376c5b192f1c cbdb0050f156b9a2 En cas de succès, un recrédit d un montant maximal de 68 est encore réalisable. Exemple 2 : recrédit total sur une commande de 100 Chaîne utilisée pour le calcul du sceau : *05/12/2006:11:55:23*100EUR100EUR*ABERTYP00145* ExempleTexteLibre*3.0*FR*monSite1* Requête : POST /recredit_paiement.cgi HTTP/1.0 Pragma: no-cache Connection: close User-Agent : AuthClient Host: paiement.creditmutuel.fr Accept: */* Content-type: application/x-www-form-urlencoded Content-length: 326 Services Page de paiement / Capture / Recrédit - Page 31 / 48

32 version=3.0 &TPE= &date=05%2f12%2f2006%3a11%3a55%3a23 &date_commande=03%2f12%2f2006 &date_remise=04%2f12%2f2006 &num_autorisation=1234a6 &montant=100.00eur &montant_recredit=100eur &montant_possible=100eur &reference=abertpy00145 &texte-libre=exempletextelibre &lgue=fr &societe=monsite1 &MAC=78bc376c5b192f1c cbdb0050f156b9a2 4.3 Réponse de la demande de recrédit Les informations retournées En retour à la demande de recrédit, l application du commerçant reçoit un message d acquittement de la part du serveur de la banque. Ce message est un document de type MIME «text/plain» précisant le résultat du recrédit. Il contient les champs suivants séparés par un caractère CHR(10) : Champs Description Remarque version Numéro de version du message d acquittement reference Référence de la commande Exemple : cdr lib Code retour indiquant le résultat du recrédit Libellé précisant la nature du code retour Version actuelle 1.0 ABERTYP00145 Valeurs possibles : 0 : recrédit effectué <0 : erreur Voir plus loin pour la liste des libellés possibles La liste des valeurs disponibles pour le libellé est donnée dans le tableau suivant : cdr Libellés Description Remarque 0 recredit effectue La demande de recrédit a été prise en compte -1 recredit refuse La demande de recrédit n a pas été prise en compte Commercant non Les paramètres servant à identifier le site Vérifier les -30 identifie commerçant ne sont pas corrects paramètres societe, TPE et lgue -31 signature non validee La signature MAC est invalide Services Page de paiement / Capture / Recrédit - Page 32 / 48