Introduction
Sherlock's est une solution de paiement de commerce électronique multicanale sécurisée conforme à la norme PCI DSS. Elle vous permet d’accepter et de gérer des transactions de paiement en prenant en compte les règles métiers liées à votre activité (paiement à la livraison, paiement différé, paiement récurrent, paiement en plusieurs fois, …).
L’objectif du présent document est d’expliquer la mise en œuvre de la solution Sherlock’s Office Batch et des tests initiaux relatifs au paiement ou à la gestion de caisse.
A qui s’adresse ce document
Sherlock’s Office Batch a pour but d'offrir aux commerçants les fonctions de Sherlock’s Office en mode Batch. Ces fonctions sont basées sur l'échange hors-ligne de fichiers. Certaines options du mode en ligne ne sont pas disponibles comme par exemple l’authentification 3-D Secure.
C’est un guide d’implémentation qui s’adresse à l’équipe technique du commerçant.
Pour avoir une vue d’ensemble de la solution Sherlock's, nous vous conseillons de consulter les documents suivants :
- Présentation fonctionnelle,
- Configuration des fonctionnalités.
Prérequis
Une connaissance des protocoles de transfert des fichiers ainsi qu’une connaissance des standards relatifs aux langages de programmation pratiqués aujourd’hui, tels que Java, PHP ou .Net, est nécessaire pour développer la connexion à Sherlock’s Office Batch.
Comprendre le paiement avec Sherlock’s Office Batch
Le traitement des fichiers par Sherlock’s Office Batch se décompose en plusieurs étapes :
1. Le commerçant dépose des fichiers de requêtes sur un compte FTPS ou SFTP externe fourni par LCL.
2. La passerelle de transfert de fichiers LCL reçoit les fichiers de requêtes et les envoie au moteur Sherlock’s Office Batch.
3. Le moteur Sherlock’s Office Batch traite les fichiers de requêtes un par un et génère un fichier de réponses par fichier de requêtes.
4. Le moteur Sherlock’s Office Batch envoie le fichier de réponses au compte FTPS ou SFTP externe via la passerelle de transfert de fichiers.
5. Le commerçant récupère le fichier de réponses depuis le compte FTPS ou SFTP externe fourni par LCL.
6. Le moteur Sherlock’s Office Batch, via la passerelle de transfert de fichier, détruit le fichier de réponses après le premier téléchargement réussi par le commerçant.
Règles générales concernant les transferts
- Le commerçant peut choisir entre FTPS ou SFTP comme méthode de transfert.
- LCL fournit un compte commerçant dédié (avec nom d'utilisateur et mot de passe), et le compte LCL doit être le même pour les fichiers de requêtes et les fichiers de réponses, mais des restrictions s'appliquent quant au nom du fichier.
- En plus des vérifications de nom d'utilisateur et de mot de passe, les serveurs SFTP et FTPS de LCL exécutent une vérification de l'adresse IP du commerçant.
- LCL donne au fichier de réponses un nom différent de celui du fichier de requêtes.
- Après une période donnée (1 semaine), les fichiers de réponse sont supprimés des comptes FTPS ou SFTP, même s'ils n'ont pas été téléchargés.
Gérer les opérations de plusieurs commerçants
Le remettant est un partenaire qui joue le rôle d'un opérateur technique gérant les échanges de fichiers avec la plate-forme de paiement Sherlock's. Un remettant peut envoyer des opérations de plusieurs commerçants dans le même fichier à condition qu'elles soient déclarées au nom de ce remettant lors de l'étape d’inscription.
Il est intéressant de noter qu'un remettant peut également être lui-même un commerçant.
Comprendre le format des fichiers échangés
Les fichiers de requête et de réponse échangés avec Sherlock’s Office Batch sont au format CSV.
Chaque fichier est constitué de quatre parties successives :
- FILE TYPE correspondant au type de fichier (voir le chapitre suivant pour les explications des différents types) ;
- HEADER contenant l’en-tête du fichier ;
- BODY contenant toutes les opérations ;
- END indiquant la fin du fichier.
L'en-tête du fichier contient un identifiant sous la forme d’un numéro de séquence. Ce numéro de séquence doit être :
- numérique ;
- unique pour tous vos fichiers (sans limite de temps) ;
- croissant et il doit commencer à 1 et augmenter de 1 en 1.
Le corps du fichier contient plusieurs enregistrements. Un enregistrement correspond à une opération liée à une transaction Sherlock's (création ou mise à jour).
- Exemple de structure principale du fichier de requête ou de réponse :
<OPERATION> contient le nom de l'opération (AUTHOR, VALIDATE, etc.).
Dans le format CSV, chaque enregistrement est préfixé par le nom du type d’élément écrit en majuscules.
Les valeurs des champs de chaque élément sont écrites l'une après l'autre et séparées par un point-virgule, sans espace et sans être préfixées de leur nom. L'ordre de ces champs doit être respecté.
Plusieurs fichiers de requête peuvent être traités en une journée. Lorsque plusieurs fichiers de requête sont disponibles sur le compte FTPS externe, Sherlock’s Office Batch les traite un par un successivement (et non simultanément et par ordre d’arrivée sur le compte FTPS).
Il y a un fichier de réponse pour chaque fichier de requête même si le traitement du fichier génère des erreurs.
Règles générales concernant les fichiers échangés
- La taille des fichiers ne doit pas dépasser 100 Mo ou 100 000 enregistrements d'opérations.
- Les fichiers sont dédiés à un seul remettant.
- Un fichier de requête ne peut pas contenir plusieurs opérations qui concernent la même transaction. Par exemple, il n'est pas possible de créer une transaction et de l'annuler dans le même fichier de requête.
- L'ordre des opérations dans le corps du fichier de réponse peut être différent de l'ordre des opérations dans le fichier de requête.
La grammaire CSV contient des fonctions spécifiques qui seront détaillées tout au long de ce document. Avec cette grammaire, l'ordre des champs doit être respecté.
Merci de vous rapprocher de votre contact habituel dans le cas où la limite de 100 Mo ou 100 000 enregistrements entraîne une contrainte dans votre intégration.
Comprendre le format du fichier de requête
Le type de fichier est basé sur le service utilisé.
Tous les champs de l’élément file type de la requête sont obligatoires et en format ANS20. Ils sont retournés à l’identique dans la réponse.
- Le nom de la balise est file.
- Le champ type doit valoir 'request' pour la requête et 'response' pour la réponse.
- Les champs format et version dépendent du type de service appelé.
| Format | Version | Description du service |
|---|---|---|
| office | Doit valoir 19 | Acceptation des transactions et des opérations de caisse. |
| token | Doit valoir 1 | Tokenisation et détokenisation des PAN. |
- Exemple de type de fichier :
...
FILE;request;office;19
...L’entête est basé sur un enregistrement contenant les champs suivants :
| Champs | Présence | Format | Description | Numéro de champ CSV |
|---|---|---|---|---|
| Le nom de la balise est header | Obligatoire | ANS20 | Indique un enregistrement d'en-tête | 1 |
| remitterId | Obligatoire | N15 | Identifiant du remettant | 2 |
| date | Obligatoire | XML Date | Date à laquelle le fichier a été créé dans le fuseau horaire du commerçant (AAAA-MM-JJ+hhmm). | 3 |
| time | Obligatoire | XML Time | Heure à laquelle le fichier a été créé dans le fuseau horaire du commerçant (hh:mm:ss+hhmm). | 4 |
| sequence | Obligatoire | N6 | Numéro de séquence du fichier. Vous pouvez utiliser un remplissage à base de « 0 » sur la gauche (par exemple : 000001 pour le numéro de la première séquence). | 5 |
- Exemple d’entête :
...
HEADER;023101122334455;2012-06-11+0200;14:28:00+0100;86
...Le corps contient des opérations en fonction du service déclaré dans l'élément file. Il faut se reporter au chapitre suivant pour connaître le détail des champs suivant l’opération souhaitée.
Dans le format CSV, il n'y a pas de balise particulière pour la partie « corps » du fichier : toutes les opérations sont détaillées directement après la partie « header ».
- Exemple de partie « corps » pour le service « office » :
…
CARDORDER;1;012323232323231;SIM201206810160;1000;0;VALIDATION;470;
201201;209910;4975497549754975;1;978;test@worldline.com;123;127.0.0.1;
2012-11-29T17:04:30Z;INTERNET;123456;;context;;origin;all;;;;;;;;;FRA
;;PAN;;;;;;VISA;APPLIED_DEFAULT;;;;;;
...La partie finale est basée sur un enregistrement contenant les champs suivants :
| Champs | Présence | Format | Description | Numéro de champ CSV |
|---|---|---|---|---|
| Le nom de la balise est end | Obligatoire | ANS20 | Indique la fin de l'enregistrement | 1 |
| nbRecord | Obligatoire | N6 | Nombres d'opérations dans la partie « body » | 2 |
- Exemple d’élément « end » :
END;227Nommage du fichier de requête
Le fichier de requête doit être transmis dans une archive au format ZIP. L’archive doit se nommer OFBREQxx.ZIP où xx désigne un nombre compris entre 01 et 99.
Une archive ne doit contenir qu’un seul fichier requête.
Le nom du fichier requête est libre mais nous vous conseillons de respecter le nommage suivant : SOB.Alias.Date-Heure.csv
Avec :
- SOB : fichier requête à destination de « Sherlock’s Office Batch » ;
- Alias : alias/merchantId Sherlock's de la boutique remettante ;
- Date : date du fichier sous le format AAMMJJ ;
- Heure : heure du fichier sous le format HHMMSS.
Comprendre le format du fichier de réponse
L'en-tête est basé sur un enregistrement contenant les champs suivants :
| Champs | Format | Description | Numéro de champ CSV |
|---|---|---|---|
| Le nom de la balise est header. | ANS20 | Indique un enregistrement d'en-tête | 1 |
| remitterId | N15 | Identifiant du remettant | 2 |
| date | XML Date | Date de création du fichier dans le fuseau horaire du commerçant, le format de la date est YYYY-MM-DD+hhmm. | 3 |
| time | XML Time | Heure de création du fichier dans le fuseau horaire du commerçant, le format de l'heure est hh:mm:ss+hhmm. | 4 |
| sequence | N6 | Numéro de séquence du fichier. | 5 |
| processingResponseCode | AN2 | Code réponse de traitement. | 6 |
| beginProcessTime | ANS25 ISO8601 |
Horodatage de début du traitement du fichier dans le fuseau horaire du commerçant. | 7 |
| endProcessTime | ANS25 ISO8601 |
Horodatage de fin du traitement du fichier dans le fuseau horaire du commerçant. | 8 |
- Exemple d’en-tête :
...
HEADER;023101122334455;2012-06-11+0200;14:28:00+0100;86;00;
2012-06-07T11:30:47+02:00;2012-06-07T11:31:43+02:00
...L’élément “error-details” n’est renvoyé que lorsqu’une erreur intervient lors du contrôle du fichier requête. « error-details » est une chaîne de caractère décrivant l’erreur.
- Exemple d’en-tête :
...
ERRORDETAILS;ERROR_FILE_ALREADY_PROCESSED: processing_response_code = [02] : Error in the file sequence number. The file has already been processed.
Expected sequence number [2] - Request file sequence number [1]
...A chaque opération du fichier de requête correspond un élément du fichier de réponse dont les attributs ont été remplis lors du renvoi. Les champs retournés sont décrits au chapitre suivant.
La fin du fichier de réponse est similaire à celle du fichier de requête et comporte les champs suivants :
| Champs | Format | Description | Numéro de champ CSV |
|---|---|---|---|
| Le nom de la balise est end. | ANS20 | Indique la fin de l'enregistrement. | 1 |
| nbRecord | N6 | Nombres d'opérations dans la partie « body ». | 2 |
- Exemple d’élément « end » :
END;227Nommage du fichier de réponse
Le fichier de réponse est transmis dans une archive au format ZIP. Le nom de cette archive est s******.OFBREP**.zip.
Où :
- s****** est un numéro de séquence unique et non paramétrable ;
- OFBREP** un nombre compris entre 01 et 99 identique au fichier requête.
Le nom du fichier de réponse contenu dans l’archive a pour formalisme : OFFUBZ.OFFBAREP.$alias.$date (exemple : OFFUBZ.OFFBAREP.MM20LEQUIPE0861.181216).
Où :
- $alias est l’alias Sherlock's de la boutique ;
- $date est la date du traitement du ficher, au format AAMMJJ.
Rapprochement des fichiers de requête et de réponse
Afin d'aider au rapprochement des fichiers de requête et de réponse, chaque fichier de requête est identifiée par un numéro de séquence qui est également retourné avec la réponse.
Tous les champs du fichier de requête sont également retournés dans le fichier de réponse à l'exception des champs suivants en raison de la conformité avec PCI DSS :
- cardNumber peut être retourné masqué dans le champ maskedPan ;
- cardEffectiveDate (date de début de validité de la carte) ;
- cardExpiryDate (date d'expiration de la carte) ;
- cardSeqNumber (numéro de séquence de la carte si présent) ;
- cardCSCValue (cryptogramme visuel de la carte).
Sherlock's peut modifier la valeur du champ suivant si la création de la transaction est suivie d'une autorisation bancaire :
- transactionDate
Démarrer avec Sherlock’s Office Batch en 4 étapes
Étape 1 : demander la création d’un compte FTPS
Pour cela, vous devez renvoyer le formulaire d’inscription à Sherlock’s Office Batch remis par votre interlocuteur technique LCL. La création du compte FTPS prend environ 12 jours à réception du formulaire correctement rempli.
Des échanges par mail ont ensuite lieu pour tester le compte FTPS en recette avant mise en place en environnement de production.
Étape 2 : utiliser les fonctions disponibles
Les différentes fonctions possibles font l’objet de requêtes spécifiques. La liste des fonctions et les détails des requêtes et réponses sont disponibles sur cette page.
Une requête est composée de champs génériques et de champs de type container.
Un container est une structure de données utilisée afin de regrouper fonctionnellement les données.
Si le champ est un champ d'un container, il est désigné <nom du container>.<nom du champ>.
Analyser les erreurs lors de la vérification du fichier
Il y a plusieurs niveaux de codes réponses lors du traitement d'un fichier par Sherlock’s Office Batch. Plusieurs vérifications globales sont effectuées avant que le fichier ne soit traité. Si l'une de ces vérifications échoue, le fichier est entièrement refusé (processingResponseCode n'est égal ni à 00 ni à 01).
Le fichier de réponses retourné contient le code de résultat global du traitement dans le champ processingResponseCode présent dans l'en-tête du fichier.
Codes de resultat global du traitement
| Code | Signification |
|---|---|
| 00 | Fichier traité correctement. Le fichier contient la liste des opérations. |
| 01 | Fichier traité correctement. Une opération a été associée à un commerçant qui n'est pas lié à l'identifiant de remettant. Le champ officeBatchResponseCode sera valorisé à 80 par l'opération. |
| 02 | Fichier déjà traité. Le numéro de séquence du fichier est inférieur à ce qu’il devrait être. Le numéro correct est envoyé dans le message qui décrit l'erreur. |
| 03 | Rupture de séquence dans le numéro de séquence du fichier. Le numéro de séquence du fichier est supérieur à ce qu’il devrait être. Le numéro correct est envoyé dans le message qui décrit l'erreur. |
| 04 | Problème technique. Problème interne |
| 05 | Fichier trop grand |
| 06 | Le nombre d'opérations dépasse la quantité maximale autorisée. Le nombre maximal d'opérations a été atteint. |
| 07 | Le nombre d'opérations compté est différent du nombre indiqué dans le champ nbRecord. |
| 08 | Opération en double |
| 09 | Enregistrement invalide |
| 10 | Format de fichier invalide. Le format du fichier est invalide (la description de l'erreur sera retournée dans la balise « error details ».). |
| 11 | Remettant invalide. Le remettant déclaré dans l'en-tête est invalide. Fichier invalide (ces codes concernent les versions plus anciennes de Sherlock’s Office Batch.) |
| Autres codes | Fichier invalide (ces codes concernent les versions plus anciennes de Sherlock’s Office Batch.) |
| Code réponse | Cause | Solution |
|---|---|---|
| Différent de 00 et 01 | Redémarrage du traitement | Le fichier de requêtes doit être renvoyé en intégralité avec le même numéro de séquence de fichier. |
| 03 | Rupture de numéro de séquence du fichier | Le fichier a été complètement refusé. Si nécessaire, le numéro de séquence doit être corrigé et le fichier renvoyé. |
| 04 | Erreur technique | Une opération a provoqué une erreur technique. Le
traitement du fichier n'a pas été interrompu. Dans ce cas, le
traitement peut être très rapide, car toutes les opérations avec
le code 25 ou 90 seront refusées (champ
responseCode). Pour l'heure, LCL n'a pas fourni de mécanisme pour différer le traitement dans l'attente qu'une connexion soit de nouveau établie. |
| Aucun | Erreur de format du fichier CSV | Lorsqu’il n’est pas possible d’identifier le service de
traitement par lot de la version du fichier, ou si ce dernier
comporte une erreur de format (blanc dans le fichier, etc.), une
réponse générique est envoyée au commerçant. Cette réponse ressemble à ceci : RESPONSE FATAL_ERROR END |
Analyser les erreurs causées par une opération
Chaque opération est considérée comme indépendante. Chaque opération a son propre code de réponse stocké (champ officeBatchResponseCode). Le code indique le champ qui est à l'origine du problème.
Si une opération échoue, le traitement n'est pas interrompu. L'opération est refusée avec le code-réponse Sherlock's classique (champ responseCode).
| Codes | Champs en question |
|---|---|
| 00 | Aucun (tous les champs sont corrects.) |
| 01 | merchantId error |
| 03 | transactionReference error |
| 04 | merchantTransactionDateTime error |
| 05 | amount error |
| 06 | captureDay error |
| 07 | captureMode error |
| 08 | operationAmount error |
| 09 | operationOrigin error |
| 11 | currencyCode error |
| 12 | customerIpAddress error |
| 13 | customerEmail error |
| 14 | customerId error |
| 16 | orderId error |
| 17 | orderChannel error |
| 18 | transactionOrigin error |
| 19 | returnContext error |
| 20 | fromTransactionReference error |
| 21 | cardExpiryDate error |
| 22 | cardNumber error |
| 23 | cardCSCValue error |
| 24 | cardEffectiveDate error |
| 25 | cardSeqNumber error |
| 26 | paymentMeanBrand error |
| 27 | authorisationId error |
| 28 | merchantWalletId error |
| 29 | paymentMeanId error |
| 30 | paymentPattern error |
| 31 | number error |
| 32 | statementReference error |
| 33 | panType error |
| 34 | mandateId error |
| 35 | valueDate error |
| 36 | paymentMeanAlias error |
| 37 | account error |
| 38 | bankCode error |
| 39 | transactionActors error |
| 45 | Date fields format error |
| 46 | settlementMode error |
| 47 | comment error |
| 48 | validationIndicator error |
| 50 | s10TransactionId error |
| 51 | s10TransactionIdDate error |
| 52 | s10FromTransactionId error |
| 53 | s10FromTransactionIdDate error |
| 54 | fraudData error |
| 55 | riskManagementDynamicParam error |
| 56 | riskManagementDynamicValue error |
| 57 | riskManagementDynamicSettingList error |
| 58 | fraudListReason error |
| 59 | fraudListType error |
| 60 | fraudListLevel error |
| 61 | fraudListElementType error |
| 62 | fraudListElementValue error |
| 63 | lastRecoveryIndicator error |
| 64 | order context field error |
| 65 | travel context field error |
| 66 | Delivery data field error |
| 67 | Address field error |
| 68 | Contact field error |
| 69 | cardAuthPolicy error |
| 70 | Shopping Cart Detail field error |
| 71 | merchantExternalId error |
| 72 | paymentMeanBrandSelectionStatus error |
| 73 | settlementArchivingReference error |
| 74 | settlementMerchantSpecificData error |
| 75 | fromTransactionAcceptor error |
| 76 | initialAuthenticationCavv error |
| 77 | bancontactMerchantCustomerAuthenticationMethod error |
| 78 | invoiceReference error |
| 79 | subMerchantCategoryCode error |
| 80 | Commerçant non enregistré pour Sherlock’s Office Batch/non lié au remettant déclaré dans l'en-tête. |
| 81 | subMerchantLegalId error |
| 82 | subMerchantShortName error |
| 83 | subMerchantContractNumber error |
| 84 | subMerchantUrl error |
| 85 | subMerchantAddress error |
| 86 | subMerchantId error |
Étape 3 : tester sur l’environnement de recette client
L’objectif est de valider que la structure du fichier et la syntaxe des requêtes sont correctes. Pour cette 1ère étape, il n’y a pas de connexion vers l’acquéreur de paiement : les demandes d’autorisations carte sont simulées. Les transactions sont stockées dans le back office Sherlock's et vous pouvez tester les opérations de caisse sur ces transactions.
Contactez l’assistance technique pour configurer une boutique sur l’environnement de recette et demander la mise en place d’un transfert de fichier entre votre site et Sherlock's.
Étape 4 : valider le passage en production
Commencez par soumettre un fichier contenant un nombre limité d’opérations afin de valider le passage en production. Vérifiez dans le fichier réponse que toutes les opérations se sont bien déroulées :
- Surveillez le taux d’acceptation (nombre de responseCode 00/nombre total d’opérations).
- Vérifiez la nature des refus non bancaires.
- Problème technique : responseCode 90, 97, 99,
- Fraude acquéreur : responseCode 34.
