Migration simplifiée vers Sherlock's 2.0

Pour rechercher dans la page utiliser Ctrl+F sur votre clavier

Faire un retour sur cette page

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 migration de Sherlock's 1.0 vers Sherlock's 2.0.

À qui s’adresse ce document

Ce document est à destination des commerçants disposant de l’offre Sherlock's 1.0 (Payment et Office Server) et souhaitant conserver leur merchant_id.

Il a pour but de faciliter la migration vers Sherlock's 2.0.

Tip: après lecture de ce document nous vous invitons à consulter attentivement l'arborescence documentaire disponible en annexe 2 : celle-ci vous permettra de consulter la documentation utile à votre migration.

Attention: si vous souhaitez opter pour le choix « Nouveau merchantID 2.0 », nous vous invitons à utiliser le « Guide de démarrage rapide » qui sera plus proche de votre besoin.

Principes de migration vers Sherlock's 2.0

	Ce qui reste après la migration	Ce qui change après la migration
Données et formats		Nouveau format des requêtes et des réponses automatiques et manuelles. Nouvelle URL de paiement. Nouvelle URL de gestion de caisse via Sherlock’s Office.
Identification de la transaction	Fonctionnement avec le `transaction_id` (utilisation du champ s10TransactionId)
Gestion de caisse	Accès à Sherlock's Gestion identique. Droits de gestion de caisse identiques.	Création d'un user admin pour accéder à la gestion de transaction via le Portail Sherlock's
Reporting	Conservation du format des journaux.
Accès aux extranets	Sherlock's CustomPages Possibilité d'utiliser l'extranet Sherlock's CustomPages pour préparer et tester votre personnalisation de pages.	Sherlock’s Téléchargement Création d'accès au téléchargement de la clé secrète via Portail Sherlock's
Fraude	Conservation des contrôles de lutte contre la fraude.
Modalités d'inscription	Pas de réinscription des boutiques du commerçant
Connecteurs		Nouveaux connecteurs non intrusifs en remplacement des API. Nouvelle clé secrète (par boutique) qui remplace le certificat Sherlock's 1.0.
Transfert de fichier	Compte FTP inchangé. Le remitter_id ne change pas. Pas de modification au niveau du nommage des fichiers requête et réponse ni au niveau du format
Moyens de paiement		Nouveaux moyens de paiement internationaux. Moyens de paiement uniquement en 2.0.
Personnalisation de page		Mise en place d'une nouvelle personnalisation de page avec l'aide de l'outil Sherlock's CustomPages ainsi que du support Sherlock's

Attention: afin d'être en conformité avec les réglementations MIF et 3DSv2, le choix de la marque et 3-D Secure sont des composantes désormais obligatoires. Nous vous invitons à contacter le support si vos boutiques ne bénéficient pas de ces fonctionnalités actuellement.

Étapes de migration

Chronologie

Nous avons identifié une liste d’étapes indispensables à la bonne réalisation de la migration de Sherlock's 1.0 vers Sherlock's 2.0. Ces étapes peuvent être schématisées de la manière suivante :

Schéma décrivant les différentes étapes de la migration technique et les modification contractuelles.

Ce que vous devez faire

Ce paragraphe a pour objectif de vous indiquer les étapes techniques successives que vous devrez suivre afin de réaliser avec succès votre évolution vers Sherlock's 2.0.

Vous disposez d’une boutique en 1.0, vous avez donc un merchant_id qui permet de vous identifier. Toutes vos transactions sont réalisées avec ce merchant_id et vous bénéficiez de journaux consolidés et d’une visualisation de toutes vos transactions sur l’extranet ( Sherlock's Gestion ) tous moyens de paiement confondus.

Étape 1 : préparer la migration

Avant de démarrer la migration de 1.0 vers 2.0 vous devez contacter le support Sherlock's :

par téléphone au : 0 811 107 022 (0,05€ / min + prix appel, du lundi au vendredi de 9h à 17h) ;
par e-mail : sherlocks@worldline.com.

Le support effectuera les étapes suivantes :

inscription de votre contact administratif et de votre contact technique sur votre boutique : cette étape a pour objectif de pouvoir vous générer les utilisateurs nécessaires pour récupérer votre clé secrète.
envoi d'un e-mail d'information : cet e-mail contient le PV de fin de migration à retourner dûment rempli lors de l'étape 4.

Étape 2 : intégrer les connecteurs 2.0 et faire les tests avec les données de simulation

Cette étape nécessite des connaissances techniques. Une connaissance élémentaire des standards relatifs aux langages de programmation Web pratiqués aujourd’hui, tels que Java, PHP ou .Net, est nécessaire pour développer la connexion.

Vous allez choisir le connecteur que vous souhaitez intégrer. Ce choix se fait en fonction de votre besoin. Par exemple, si vous utilisez actuellement Sherlock's Payment 1.0, vous pouvez opter pour le connecteur Sherlock’s Paypage.

D'autre part, l'intégrateur devra choisir le type de connecteur : JSON, POST ou SOAP (pour Sherlock’s Office).

Votre intégration se fera nécessairement avec un transaction_id généré chez vous. Cette configuration est imposée pour :

permettre à votre boutique de fonctionner avec les API 1.0 et les connecteurs 2.0 ;
garder les formats de journaux 1.0.

Tableau informatif

Table 1. Boutique en mode transactionId - Vous vous connectez à Sherlock's avec un transactionId que vous avez généré
Données	Création de transaction via :
Données	Sherlock’s Paypage / Sherlock’s Office	Sherlock's Gestion
transactionId fourni par vous-même	Traitement standard	Proposé par Sherlock's, modifiable et affiché en rouge
transactionId absent	Rejet code = 12	Rejet code = 12
transactionReference fourni par vous-même	Rejet code = 12	N/A
transactionReference absent	OK	N/A
Référence complémentaire générée par Sherlock's	transactionReference	transactionReference
Contenu réponse	s10TransactionId s10TransactionIdDate transactionReference

Le site Web de documentation en ligne vous propose des documents dédiés pour chaque connecteur dans la partie Développeur. Nous vous invitons à vous reporter à l'arborescence documentaire disponible en annexe 2 de ce document pour les documents de référence. Vous pouvez utiliser le site Web de documentation en ligne pour toutes les documentations supplémentaires.

Tip: si vous souhaitez personnaliser vos pages de paiement, vous pouvez utiliser notre outil Sherlock's CustomPages, permettant de tester et visualiser le rendu des pages. Pour cela, merci de vous référer à la documentation Sherlock's CustomPages afin d’utiliser l’outil.

Si vous ne personnalisez pas votre page, le template par défaut de la page sera appliqué.

Après votre intégration, pour effectuer vos tests, les données de simulation sont disponibles dans les documentations dédiées aux connecteurs que vous intégrez.

Pour le connecteur Sherlock’s Paypage, les données de simulation sont une URL, un merchant_id et une clé secrète dédiée, qui vous permettront de faire vos tests sans impacter votre flux de production actuel.

Table 2. transactionId généré par vous-même
Champ	Valeur
Votre ID (merchantId)	002001000000003
Version de la clé (keyVersion)	1
Clé secrète	002001000000003_KEY1

Il s'agit bien d'une simulation. Donc les transactions effectuées ne seront pas consultables dans votre Sherlock's Gestion.

Tip: pour le connecteur Sherlock’s Office, nous vous invitons à contacter notre support.

Étape 3 : récupérer la clé secrète sur Portail Sherlock's et passer en production

Lors de votre premier contact avec notre support, des données de contact technique vous ont été demandés ; à l'aide de ces informations, un utilisateur Portail Sherlock's a été créé sur notre plateforme de téléchargement. Un e-mail de connexion a été adressé au contact identifié.

https://sherlocks-extranet.secure.lcl.fr

LCL met à disposition sur Portail Sherlock's, dans l'espace Téléchargement,une clé secrète qui permet de sécuriser les échanges entre votre site Web et le serveur Sherlock's.

Vous êtes responsable de sa conservation et devez prendre toutes les mesures pour :

en restreindre l'accès ;
la sauvegarder de manière chiffrée ;
ne jamais la copier sur un disque non sécurisé ;
ne jamais l'envoyer (e-mail, courrier) de manière non sécurisée.

La compromission de la clé secrète (et son utilisation par un tiers malveillant) perturberait le fonctionnement normal de votre boutique, et pourrait notamment générer des transactions et des opérations de caisse injustifiées (des remboursements par exemple).

C’est la même clé secrète qui est utilisée sur les différents connecteurs.

En cas de besoin, vous pourrez aussi effectuer une demande de renouvellement de clé via cet extranet.

Une fois la connexion de votre site Web et/ou application testée, vous êtes à présent en mesure de valider la connexion de production.

Au préalable, nous conseillons d’isoler votre site Web et/ou application du public pour éviter que des clients effectuent des transactions pendant cette phase de validation.

Pour basculer sur le serveur de production, vous devez changer l’URL et utiliser les identifiants de votre boutique : merchantId 1.0, secretKey et keyVersion.

Connecteur Sherlock’s Paypage :

URL Sherlock's	JSON : https://sherlocks-payment-webinit.secure.lcl.fr/rs-services/v2/paymentInit POST : https://sherlocks-payment-webinit.secure.lcl.fr/paymentInit SOAP : https://sherlocks-payment-webinit.secure.lcl.fr/services/v2/paymentInit
merchantId	merchant_ID 1.0
SecretKey	Clé secrète que vous récupérez via l’extranet Sherlock’s Téléchargement
keyVersion	Version clé secrète récupérée sur Sherlock’s Téléchargement (logiquement 1 pour la 1ère clé)

Connecteur Sherlock’s Office :

URL Sherlock's	https://sherlocks-office-server.secure.lcl.fr
merchantId	merchant_ID 1.0
SecretKey	Clé secrète que vous récupérez Sherlock’s Téléchargement
KeyVersion	Version clé secrète récupérée sur Sherlock’s Téléchargement (logiquement 1 pour la 1ère clé)

Votre système de paiement sera pleinement opérationnel.

Attention: dans le cas où vous détectiez une anomalie (problème non identifié lors de la phase de recette de vos développements internes), il est possible de rebasculer les flux sur Sherlock's 1.0 via les API.

IMPORTANT: cette solution de cohabitation technique reste possible jusqu'à la fin de maintenance des API 1.0. Toutefois, une fois que vous nous aurez adressé le PV de fin de migration, les API 1.0 seront désactivées pour votre boutique.

Lors de cette phase de cohabitation technique, vous devez impérativement veiller à l'unicité de vos identifiants de transaction pour éviter les doublons entre les transactions générées via Sherlock's 1.0 et les transactions générées via Sherlock's 2.0.

Étape 4 : valider la fin de migration

Une fois votre site Web migré sur les connecteurs 2.0, vous devez adresser au support un procès-verbal de fin de migration à l'adresse sherlocks@worldline.com. Le procès-verbal vous a été fourni dans l'e-mail d'information envoyé lors de votre demande de migration.

Tip: si votre migration concerne plusieurs boutiques, pensez à noter les merchant_id concernés dans le procès-verbal de fin de migration.

Votre évolution est à présent terminée et vous pouvez bénéficier des options et moyens de paiement 2.0.

Annexe 1 : FAQ migration

Pourquoi migrer sur 2.0 ?

Le service Sherlock's 1.0 s'arrête le 30/06/2022.

Dans ce contexte, LCL vous invite à migrer vers le service Sherlock's 2.0, celui-ci vous permettant :

de simplifier l’intégration de Sherlock's et standardiser les méthodes de connexion : nouveaux connecteurs Sherlock's à l’état de l’art ;
d'optimiser le parcours client : nouvelles fonctionnalités et nouvelle ergonomie des interfaces client (application InApp, webresponsive, …) ;
d'avoir plus d’autonomie dans la gestion de vos transactions et de vos paramètres commerçant : nouvelle interface Sherlock's Gestion ;
de faciliter votre déploiement sur le marché international : nouveaux moyens de paiement ;
de bénéficier de fonctionnalités avancées : lutter efficacement contre la fraude, tableau de bord, …

Peut-on continuer de recevoir les journaux au format 1.0 ?

Dans le cas où vous conservez votre merchant_id, l’identification par le transaction_Id est maintenue, donc vous conservez vos journaux à l’ancien format 1.0.

De plus, les transactions effectuées avec les connecteurs apparaîtront bien dans vos journaux 1.0.

Attention: le choix de cette migration nécessite que le transaction_id soit généré par le commerçant via le champ s10TransactionId et non par Sherlock's.

s10TransactionId est un identifiant alternatif de la transaction compatible avec Sherlock's 1.0. Il identifie une transaction de manière unique sur une journée. Le couple s10TransactionId/s10TransactionIdDate assure l’unicité de la transaction.

Est-ce que tous les champs sont reportés en 2.0 ?

Certains champs ne sont pas reportés en 2.0. Vous devez en tenir compte lors de vos développements.

Merci de vous référer à l'annexe 2 : arborescence documentaire

Peut-on garder la même personnalisation des pages de paiement ?

La personnalisation de la page peut être récupérée si :

Personnalisation logo 1.0 : Aujourd’hui, vous ne précisez pas le templateName via l’API 1.0. Lorsque vous utiliserez le connecteur 2.0, vous devrez préciser dans votre requête le paramètre templateName = « custom-MerchantID » ( le MerchantID est votre identifiant sur 15 caractères ).
Personnalisation « template » ou « css » : Aujourd’hui, vous précisez le templateName via l’API 1.0. vous avez généré une personnalisation via customPage (ou par envoi à Worldline) dont vous devrez réutiliser le nom du template dans le champ templateName.

Tip: Vous pouvez aussi travailler votre nouvelle personnalisation de pages à l'aide de Sherlock's CustomPages et de soumettre votre personnalisation à notre assistance technique pour la mise en place.

Peut-on changer la personnalisation des pages de paiement ?

Si vous souhaitez modifier la personnalisation de votre page de paiement, vous pouvez accéder à l'outil "customePage" qui vous permettra de générer une nouvelle personnalisation de votre page de paiement.

Un guide de personnalisation des pages est mis à votre disposition ainsi que l'outil de personnalisation des pages Custompages.

Merci de vous référer à l'annexe 2 : arborescence documentaire

Peut-on utiliser la base wallet existante 1.0 ?

La base Wallet 1.0 est tout à fait utilisable avec Sherlock's 2.0.

À quoi correspond `s10TransactionReference` ?

Il s'agit de l'objet logiciel qui intègre le transactionId.

Le champ s10TransactionReference doit être valorisé lorsqu’on réalise un paiement avec une ancienne boutique 1.0.

Le champ transactionReference ne doit pas être valorisé.

Exemple avec votre propre transactionId (typiquement lorsque vous incrémentez les Id à partir de votre base de données) :

// $s10TransactionReference=array(
// "s10TransactionId" => "000001",
// // "s10TransactionIdDate" => "not needed", Please note that the date is not needed, Sherlock's server will apply its date.
// );
//

Où peut-on trouver un exemple de code fonctionnel ?

LCL met à disposition un exemple de code PHP sur Github qui initialise un paiement Sherlock’s Paypage sur l'environnement de simulation.

Quels sont les moyens de paiement disponibles en 2.0 ?

La liste des moyens de paiement disponibles en 2.0 est fournie sur notre site Web de documentation en ligne.

Merci de vous référer à l'annexe 2 : arborescence documentaire

Quels sont les contrôles de fraude disponibles en 2.0 ?

Les contrôles de fraude disponibles en 2.0 sont détaillés dans le guide « Gestion de la lutte contre la fraude ».

Merci de vous référer à l'annexe 2 : arborescence documentaire

Quels sont les devises acceptées en 2.0 ?

Les devises acceptées dépendent du contrat acquéreur.

Les devises prévues pour les schèmes Visa, Mastercard et Amex sont listées dans le Dictionnaire des Données disponible sur la Documentation en ligne.

Merci de vous référer à l'annexe 2 : arborescence documentaire

Comment valider que ma migration est OK ?

LCL met à votre disposition des données de simulation, dont les informations sont dans les documentations connecteurs.

Après avoir fait vos tests sur l'environnement de simulation, et afin de finaliser votre migration, vous devez mettre en place vos données de production : merchant_id, URL et secret_key.

Votre migration est considérée comme réussie si vous n'obtenez pas de code de rejet Sherlock's.

Dès lors, les transactions sont réelles et visibles sur Sherlock's Gestion et dans vos journaux. Les fonds seront remisés sur votre compte. Et si vous avez souscrit l'option, les transactions seront rapprochées.

IMPORTANT: vous devez adresser le procès-verbal de fin de migration à l'assistance technique à l'adresse sherlocks@worldline.com.

Merci de vous référer à l'annexe 2 : arborescence documentaire

Annexe 2 : Arborescence documentaire

Dans cette annexe vous trouverez un tableau récapitulatif des documents de référence pour accompagner votre migration :

Besoin	Document de référence
Connecteurs	Migration Sherlock's Payment vers Sherlock’s Paypage Migration Sherlock’s Office 1.0 vers Sherlock’s Office 2.0 Migration Sherlock’s Office Batch 1.0 vers Sherlock’s Office Batch 2.0
Personnalisation des pages	Migration de la personnalisation des pages de paiement (Paypage)
Journaux	Correspondance des journaux 1.0 2.0
Champs	Correspondance des données 1.0 2.0
Dictionnaire des données	Dictionnaire des données
Documentation en ligne	Documentation en ligne Sherlock's
Sherlock's Gestion	Portail Sherlock's
Sherlock’s Téléchargement	Portail Sherlock's
Sherlock's CustomPages	Sherlock's CustomPages

Tip: si vous souhaitez utiliser Sherlock’s Office Batch 2.0, nous vous invitons à consulter la documentation correspondante. Nous vous rappelons cependant que la migration simplifiée vous permet de conserver Sherlock’s Office Batch 1.0.