Guide d implémentation

Guide d implémentation Echange de fichiers Gestion des paiements par identifiant Version 1.5

SUIVI, HISTORIQUE Rédaction, Vérification, Approbation Rédaction Vérification Approbation Nom Date/Visa Nom Date/Visa Nom Date/Visa Lyra-Network 20/06/2013 Lyra-Network 20/06/2013 Lyra-Network 20/06/2013 Historique du document Version Auteur Date Commentaires 1.5 Lyra-Network 20/06/2013 1.4a Lyra-Network 11/12/2012 Mise à jour du champ 25 Ajout des codes retour autorisation Précisions sur la mise à disposition du fichier de réponse ANS Mise à jour des notifications (Suppression de l appel à l URL serveur) 1.4 Lyra-Network 31/05/2012 Mise à jour du chapitre Fichier de paiement V2 : Ajout Ref commande / Info1 / Info2 / Info3 dans le fichier retour 1.2 Lyra-Network 07/01/2011 Précisions apportées sur la réponse serveur à serveur 1.1 Lyra-Network 03/12/2010 Ajout d exemples de contenu des fichiers REQ et ANS 1.0 Lyra-Network 10/05/2010 Version initiale. Confidentialité Toutes les informations contenues dans ce document sont considérées comme confidentielles. L utilisation de celles-ci en dehors du cadre de cette consultation ou la divulgation à des personnes extérieures est soumise à l approbation préalable de Lyra Network.

SOMMAIRE Suivi, historique... 2 1. PRINCIPE GENERAL... 4 1.1: Présentation du service... 4 1.2: Principe de fonctionnement... 4 2. FICHERS DE PAIEMENT... 5 2.1: Dépôt de fichier... 5 2.2: Traitement des fichiers de paiement... 5 2.3: Format du nom du fichier... 6 2.4: Format du fichier des demandes de paiement... 7 2.4.1: Généralités... 7 2.4.2: Enregistrement d entête... 7 2.4.3: Enregistrement de détail... 8 2.4.4: Enregistrement de fin... 8 2.4.5: Exemple de fichier de demande de paiement... 9 2.5: Format du fichier de réponse aux demandes de paiement... 9 2.5.1: Généralités... 9 2.5.2: Enregistrement d entête... 10 2.5.3: Enregistrement de détail... 11 2.5.4: Enregistrement de fin... 14 2.5.5: Exemple de fichier de réponse à une demande de paiement... 14 3. Notifications... 15 3.1: Url serveur à la fin du paiement... 15 3.2: Mail de confirmation de paiement... 15 4. ASSISTANCE TECHNIQUE... 15

1. PRINCIPE GENERAL 1.1: Présentation du service Le service d échange de fichiers du module de gestion des paiements par identifiants permet aux sites marchands de réaliser des opérations de débit sur les cartes bancaires de leurs clients abonnés. Ce service permet de réaliser ces opérations sous la forme d un «traitement par lot» : le site marchand communique à la plateforme de paiement une série d ordres sous forme de fichiers. La plateforme de paiement traite ces ordres et génère à son tour des fichiers de compte-rendu. 1.2: Principe de fonctionnement Le protocole de transfert de fichiers utilisé est FTP. Dans les transactions FTP, la plateforme de paiement agit comme le serveur, et le site marchand comme le client. L accès au répertoire dans lequel seront stockés les fichiers est protégé par un couple nom d utilisateur/mot de passe qui vous a été préalablement communiqué à l ouverture du service. Des règles de nommage spécifiques à chaque type de fichier sont à appliquer. Tout fichier ne respectant pas ces règles de nommage ne sera pas pris en compte. Tout fichier traité par la plateforme donnera lieu à la génération d un fichier de réponse. Si une anomalie a été détectée pendant le traitement, un e-mail d alerte est adressé au commerçant. Les fichiers déposés sur la plateforme, ou générés par celle-ci, sont supprimés du répertoire dès que leur date de création dépasse les 15 jours. Cette suppression sera toujours à l initiative de la plateforme de paiement. Guide d implémentation : Paiements par identifiant - Fichier 4/15

2. FICHERS DE PAIEMENT 2.1: Dépôt de fichier Vous devez déposer le fichier de paiement sur le serveur FTP mis à disposition. Les identifiants de connexion vous ont été transmis par mail à la souscription du service «paiement par dépôt de fichier». Le fichier de paiement doit être déposé dans le répertoire Identifiant boutique / depot Identifiant boutique que vous pouvez retrouver dans le back office de la solution dans l onglet : Paramétrage/boutique/nom de la boutique => rubrique configuration Répertoire de dépôt du fichier de paiement 2.2: Traitement des fichiers de paiement La plateforme de paiement procède au traitement des fichiers de paiement transférés par le site marchand deux fois par jour tous les jours : une fois à 7h00 et une fois à 13h00. Le fichier de réponse est déposé dans le répertoire id Répertoire fichier de réponse Le fichier de réponse est disponible entre 8h00 et 9h00 et entre 14h00 et 15h00 Guide d implémentation : Paiements par identifiant - Fichier 5/15

2.3: Format du nom du fichier La convention de nommage d un fichier de demande de paiement est la suivante : <AAAAMMJJ>.<siteID>.PAY.REQ.<z>.<xx> Le fichier de réponse associé sera nommé de la manière suivante : <AAAAMMJJ>.<siteID>.PAY.ANS.<z>.<xx> Où : - <AAAAMMJJ> représente la date de génération du fichier. - <siteid> représente le numéro de boutique qui vous a été attribué. - <z> prend soit la valeur «T» pour un fichier en mode TEST, soit la valeur «P» pour un fichier en mode PRODUCTION. - <xx> correspond au numéro séquentiel du fichier dans la journée, sur 2 caractères numériques. Exemple : le premier fichier de demande de paiements, concernant la boutique 43218765, généré le 10/05/2010, en mode PRODUCTION, devra porter le nom suivant : 20100510.43218765.PAY.REQ.P.01 Si un deuxième fichier doit être généré dans la même journée, alors son nom devra être : 20100510.43218765.PAY.REQ.P.02 La plateforme de paiement, après traitement de ces fichiers, génèrera les fichiers suivants : 20100510.43218765.PAY.ANS.P.01 20100510.43218765.PAY.ANS.P.02 REMARQUE : Les fichiers déposés ne doivent pas comporter d extension. Exemple :.csv ou.txt. Si vous déposez un fichier avec extension celui-ci ne sera pas traiter. Guide d implémentation : Paiements par identifiant - Fichier 6/15

2.4: Format du fichier des demandes de paiement 2.4.1: Généralités Le fichier de demandes de paiement sera constitué d une série d enregistrements. On appelle «enregistrement» une liste de paramètres séparés par le caractère «;», et terminés par un retour chariot. On a donc un enregistrement par ligne. Ce type de format est communément appelé «CSV» (pour Comma Separated Values), et est notamment reconnu par MS Excel. Le fichier aura la structure suivante : - Un enregistrement d entête spécifiant des informations sur la transmission. - Un nombre variable d enregistrements contenant les informations des paiements à effectuer. - Un enregistrement de fin, permettant de s assurer de la cohérence du fichier transmis. Les paragraphes suivants décrivent le format des divers enregistrements. Pour les champs applicables, la colonne «Equivalence» correspond à la codification du champ telle qu utilisée dans l interface vers la page de paiement. Dans ce cas, le format du paramètre, ainsi que les règles de gestion s y rapportant sont les mêmes. Se référer à la documentation «Guide d implémentation interface avec la plateforme de paiement paramétrage avancé» pour une description détaillée de ces paramètres. 2.4.2: Enregistrement d entête Pos. Description Format Remarques Equivalence 01 Code enregistrement n2 Valorisé à 00 02 Type de fichier Valorisé à PAY 03 Version de fichier n2 Valorisé à 02 04 Identifiant de boutique n8 Identifiant fourni à sa création vads_site_id 05 Environnement TEST ou PRODUCTION vads_ctx_mode 06 Date de création n8 Au format AAAAMMJJ 07 Heure de création n6 Au format HHMMSS 08 Date d exécution demandée n8 Réservé à usage futur. Par défaut, le fichier est traité dans la vacation suivante. Guide d implémentation : Paiements par identifiant - Fichier 7/15

2.4.3: Enregistrement de détail Pos. Description Format Remarques Equivalence 01 Code enregistrement n2 Valorisé à 02 02 Numéro de séquence n..6 Numéro de séquence de l enregistrement détail dans le fichier. Démarre à 1. 03 Date de la transaction n8 Au format AAAAMMJJ vads_trans_date 04 Heure de la transaction n6 Au format HHMMSS vads_trans_date 05 Identifiant de transaction n..6 Unique sur la journée et partagé avec les autres modes de paiement. 06 Type de transaction a2 Valorisé à CD (Card Debit). 07 Montant n..12 En son unité indivisible (en centimes pour l Euro par exemple). 08 Devise n3 ISO 4217 code numérique (978 pour l Euro) 09 Date de remise n8 demandée Au format AAAAMMJJ, la laisser vide pour indiquer la date du jour. 10 Mode de validation n..1 0 pour validation automatique 1 pour validation manuelle Vide pour utiliser le mode de validation configuré par défaut 11 Identifiant de carte ans..50 Identifiant de la carte à utiliser pour le paiement 12 Contrat n7 Contrat commerçant à utiliser. Laisser à vide pour utiliser celui par défaut. 13 Référence de commande 14 Informations de transaction 1 15 Informations de transaction 2 16 Informations de transaction 3 vads_trans_id vads_amount vads_currency vads_validation_ mode vads_identifier ans..32 Laisser à vide si non utilisé vads_order_id ans..255 Laisser à vide si non utilisé vads_order_info1 ans..255 Laisser à vide si non utilisé vads_order_info2 ans..255 Laisser à vide si non utilisé vads_order_info3 2.4.4: Enregistrement de fin Pos. Description Format Remarques Equivalence 01 Code enregistrement n2 Valorisé à 01 02 Nombre d enregistrements détail transmis n..6 Guide d implémentation : Paiements par identifiant - Fichier 8/15

2.4.5: Exemple de fichier de demande de paiement Exemple d un fichier de test déposé le 30/11/2010 pour la boutique 12345678, contenant une demande de paiement pour l identifiant MON-IDENTIFIANT-TEST, avec comme paramètres : Numéro de transaction : 300001 Montant : 32,99 Nom du fichier : 20101130.12345678.PAY.REQ.T.01 00;PAY;02;12345678;TEST;20101130;142008; 02;1;20101130;142008;300001;CD;3299;978;;;MON-IDENTIFIANT-TEST;;;;; 01;1 2.5: Format du fichier de réponse aux demandes de paiement 2.5.1: Généralités Il y a deux catégories d erreur : - Les erreurs de format et/ou valorisation de champ. - Les erreurs liées à l exécution des paiements. Le traitement effectué par la plateforme s effectue en deux phases : - La première phase vérifie l intégrité du fichier et détecte les erreurs de première catégorie (format et/ou valorisation). En cas d erreur de cette catégorie, le fichier est rejeté dans son intégralité. Cette première phase ne réalise des contrôles que sur la globalité du fichier. Les cas d erreur sur les enregistrements détail sont traités dans la deuxième phase. - La deuxième phase procède à l exécution des paiements, ligne par ligne. En cas d erreur sur un des paramètres (exemple : identifiant non trouvé, devise incorrecte, etc.), le code d erreur 30 sera renseigné au niveau de l enregistrement détail, et un champ complémentaire désignera la position de la donnée concernée. En cas de refus d un paiement (échec contrôle risques, refus demande d autorisation), l origine du refus sera renseigné au niveau de l enregistrement de détail. Dans le premier cas d erreur, le fichier de résultat ne comprendra qu un unique enregistrement d entête matérialisant l incident et un enregistrement de fin. Le commerçant devra resoumettre le fichier après correction, en modifiant le nom du fichier échangé. Dans le deuxième cas, le fichier de résultat contiendra le même nombre d enregistrements de détail que le fichier de demande. Seuls les paiements pour lesquels il y aura eu une erreur sur un des paramètres seront à resoumettre par le commerçant. Si un incident de fonctionnement survient et que la plateforme n a pu traiter en temps et en heure le fichier, les traitements manquants seront effectués après rétablissement du service. Il ne faut donc pas représenter les paiements non traités dans un nouveau fichier. Guide d implémentation : Paiements par identifiant - Fichier 9/15

2.5.2: Enregistrement d entête Pos. Description Format Remarques Equivalence 01 Code enregistrement n2 Valorisé à 00 02 Type de fichier Valorisé à PAY 03 Version de fichier n2 Valorisé à 02 04 Code de retour de la première phase du traitement n1 0 : Traitement effectué 1 : Erreur de format 2 : Erreur de valorisation 05 Information sur l erreur ans..255 Complément d information sur l erreur, vide en cas de succès. 06 Identifiant de boutique n8 Idem demande si valide. vads_site_id 07 Environnement Idem demande si valide. vads_ctx_mode 08 Date de création n8 Idem demande si valide 09 Heure de création n6 Idem demande si valide 10 Date de fin de traitement n8 Au format AAAAMMJJ 11 Heure de fin de n6 Au format HHMMSS traitement Guide d implémentation : Paiements par identifiant - Fichier 10/15

2.5.3: Enregistrement de détail Pos. Description Format Remarques Equivalence 01 Code enregistrement n2 Valorisé à 02 02 Numéro de séquence n..6 Idem demande 03 Date de la transaction n8 Idem demande vads_trans_date 04 Heure de la transaction n6 Idem demande vads_trans_date 05 Identifiant de transaction n..6 Idem demande vads_trans_id 06 Type de transaction a2 Idem demande 07 Montant n..12 Idem demande vads_amount 08 Devise n3 Idem demande vads_currency 09 Montant en contre-valeur n..12 Vide si non applicable euro 10 Devise de contre-valeur n3 Vide si non applicable, sinon 978 11 Date de remise n8 Date Remise prévue demandée 12 Mode de validation n1 0 si validation automatique vads_validation_mode 1 si validation manuelle 13 Identifiant de carte ans..50 Idem demande vads_identifier 14 Contrat n7 Contrat commerçant utilisé pour traiter cette demande 15 Référence de commande ans..32 Idem demande vads_order_id 16 Informations de ans..255 Idem demande vads_order_info1 transaction 1 17 Informations de ans..255 Idem demande vads_order_info2 transaction 2 18 Informations de ans..255 Idem demande vads_order_info3 transaction 3 19 Code retour global n2 Code retour du traitement 00 : Succès vads_result 02 : Le commerçant doit contacter la banque du porteur. 05 : Paiement refusé 30 : Erreur de paramètre. Un complément d information est disponible dans le champ 25 96 : Erreur technique 20 Code retour d autorisation n..2 Valeur retournée par le vads_auth_result serveur d autorisation. Vide si non applicable. 00 Autorisation acceptée 02 Contacter l émetteur de carte 03 Commerçant invalide 04 Conserver la carte 05 Ne pas honorer 07 Conserver la carte, conditions spéciales 08 Approuver après identification du porteur 12 transaction invalide 13 Montant invalide 14 Numéro de porteur invalide 15 Emetteur de carte invalide 17 Annulation client Guide d implémentation : Paiements par identifiant - Fichier 11/15

Pos. Description Format Remarques Equivalence 19 Répéter la transaction ultérieurement 20 Réponse erronée (erreur dans le domaine serveur) 24 Mise à jour de fichier non supportée 25 Impossible de localiser l enregistrement Enregistrement dupliqué, 26 ancien enregistrement remplacé 27 Erreur en «edit» sur champ de mise à jour 28 accès interdit au fichier 29 Mise à jour de fichier impossible 30 Erreur de format 31 Identifiant de l organisme acquéreur inconnu 33 Date de validité de la carte dépassée 34 Suspicion de fraude 38 Nombre d essais de code confidentiel dépassé 41 Carte perdue 43 Carte volée 51 Provision insuffisante 54 Date de validité de la carte dépassée 55 Code confidentiel erroné 56 Carte absente du fichier 57 Transaction non permise à ce porteur 58 Transaction interdite au terminal 59 Suspicion de fraude 60 L accepteur de carte doit contacter l acquéreur 61 Montant de retrait hors limite 63 Règles de sécurité non respectées 68 Réponse non parvenue ou reçue trop tard 75 Nombre d essais code confidentiel dépassé Porteur déjà en opposition, 76 ancien enregistrement conservé 90 Arrêt momentané du système 91 Emetteur de cartes ou réseau inaccessible 94 Demande dupliquée 96 Mauvais fonctionnement du système 97 Echéance de la temporisation de surveillance globale Guide d implémentation : Paiements par identifiant - Fichier 12/15

Pos. Description Format Remarques Equivalence 98 Serveur inaccessible (positionné par le serveur) 99 Incident domaine initiateur 21 Numéro d autorisation n6 Numéro d autorisation vads_auth_number retourné par l acquéreur. Vide si non applicable. 22 Mode d autorisation MARK : Prise d empreinte vads_auth_mode FULL : Autorisation Vide si non applicable. 23 Date d autorisation n8 Vide si non applicable 24 Heure d autorisation n6 Vide si non applicable 25 Code retour an255 Contient le retour du module vads_extra_result complémentaire de contrôle des risques (si souscrit), ou la position du champ erroné en cas d erreur 30. Vide si non applicable. 26 Numéro de carte Extrait du n de carte utilisée, vide si non applicable 27 Date expiration carte n8 Au format AAAAMMJJ. Vide si non applicable Guide d implémentation : Paiements par identifiant - Fichier 13/15

2.5.4: Enregistrement de fin Pos. Description Format Remarques Equivalence 01 Code enregistrement n2 Valorisé à 01 02 Nombre total n..6 d enregistrements détail transmis 03 Nombre de paiements n..6 réussis 04 Nombre de paiements échoués n..6 2.5.5: Exemple de fichier de réponse à une demande de paiement Voici la réponse à notre fichier d exemple 20101130.12345678.PAY.REQ.T.01 Nom du fichier de réponse : 20101130.12345678.PAY.ANS.T.01 00;PAY;02;0;;12345678;TEST;20101130;153149;20101201;070019 02;1;20101130;153149;300001;CD;3299;978;3299;978;20101201;;MON-IDENTIFIANT- TEST;1111111;;;;;00;0;083652;FULL;20101201;070020;;497010XXXXXX0000;20110630 01;1;1;0 Guide d implémentation : Paiements par identifiant - Fichier 14/15

3. NOTIFICATIONS 3.1: Url serveur à la fin du paiement L url serveur ne sera pas appelée lors du traitement du fichier. Seule l analyse du fichier de réponse (mis à disposition dans le répertoire /id) devra permettre au marchand de mettre à jour son système d information. 3.2: Mail de confirmation de paiement Aucun mail de confirmation ne sera envoyé par la plateforme Systempay à l acheteur ou au marchand en cas de paiement accepté. Aucun mail d avertissement ne sera envoyé au marchand en cas de paiement refusé. 4. ASSISTANCE TECHNIQUE Pour tout problème d accès à l outil de gestion de caisse, il convient d utiliser les liens «compte bloqué» ou «mot de passe oublié» disponibles sur la page de connexion de l outil de gestion de caisse. Pour toute question technique, vous pouvez nous contacter par téléphone au (Numéro Azur Coût d un appel local depuis un poste fixe) les jours ouvrés du lundi au vendredi de 09h00 à 18h00 (heure légale française). Guide d implémentation : Paiements par identifiant - Fichier 15/15