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 de paiement par abonnement jusqu'au démarrage en production.
A qui s’adresse ce document
Ce document a pour objectif de vous aider à mettre en place le paiement récurrent des services que vous délivrez à vos clients (appelés abonnés dans la suite du document).
L’objectif est de présenter les fonctionnalités liées au paiement par abonnement et d’expliquer comment les mettre en œuvre avec la solution Sherlock's.
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
Pour vous permettre d'effectuer des paiements, Sherlock's doit stocker les coordonnées de paiement de vos abonnés.
Vous avez quelques points à traiter avant de démarrer :
- Pour être en conformité avec le RGPD, vous devez compléter votre registre interne de traitement des données personnelles, en précisant que les données bancaires sont conservées par Sherlock's. Pour davantage d'informations sur le RGPD, veuillez vous référer à notre documentation sur la sécurité des systèmes d'information,
- Informer vos clients du stockage de leurs coordonnées et des modalités des paiements récurrents (durée, montant, périodicité…),
Vue d’ensemble du service abonnement
Description fonctionnelle
Stockage des coordonnées de l’abonné
Lorsque vous enregistrez un abonné dans votre système d’information, vous devez lui associer un identifiant de compte unique que Sherlock's va utiliser pour stocker les coordonnées de paiement. Par la suite, vous pouvez le débiter de manière récurrente par transfert de fichier ou en mode en ligne.
Schéma de principe du paiement par abonnement avec une carte :
Vous gérez l’identifiant de l’abonné qui est associé au compte de votre client. Sherlock's stocke dans un espace sécurisé PCI appelé wallet les coordonnées de paiement de l’abonné.
Le schéma ci-dessus s’applique aussi au paiement par abonnement avec un mandat SDD.
Dans ce cas, Sherlock's stocke l’identifiant du mandat dans la base wallet.
Le service abonnement se base sur le wallet Sherlock's qui est un portefeuille virtuel sécurisé dans lequel sont stockées les coordonnées de paiement de l’abonné :
- Le wallet est mono moyen de paiement,
- Identifiant Abonné =
merchantWalletId.
Les moyens de paiement permettant d’effectuer des paiements récurrents sont :
- Carte CB, Visa, Mastercard, Amex, Bancontact (option WIP requise)
- Mandat SDD (SEPA Direct Debit).
Sherlock's stocke dans le wallet, toutes informations nécessaires pour vous permettre de débiter votre abonné à partir de son identifiant :
- Carte CB, Visa, Mastercard, Bancontact, Amex
- Numéro de carte
- Date d’expiration
- Marque de la carte
- Mandat SDD
- Identifiant du mandat
Cependant Sherlock's permet de partager une même base wallet entre plusieurs boutiques d’une même enseigne.
Si vous êtes dans ce cas, veuillez contacter l’assistance technique.
Enrôlement de l’abonné (CIT)
L’enrôlement de l’abonné consiste à enregistrer ses coordonnées de paiement dans le wallet de Sherlock's. L’enrôlement peut être associé ou non à un premier paiement.
2 interfaces permettent d’enrôler un abonné :
- Sherlock’s Paypage : vous enregistrez les données de paiement de l’abonné lors du premier paiement réalisé depuis les pages hébergées par Sherlock's.
- Sherlock’s Office M2M : vous gérez vos propres pages pour la saisie des données de paiement et vous utilisez l’interface web en ligne pour enregistrer l’abonné dans le wallet Sherlock's.
Paiement des échéances de l'abonnement (MIT)
Les paiements récurrents sont ensuite transmis à partir de l’identifiant de l’abonné (champ merchantWalletId) sans que vous ayez à communiquer les données sensibles.
2 types d’interfaces pour débiter ou créditer les abonnés :
- Sherlock’s Office M2M : Vous vous connectez à Sherlock's via une interface en ligne Web pour transmettre les demandes de débit ou de crédit.
- Sherlock’s Office Batch : A chaque échéance, vous transférez à Sherlock's le fichier contenant les requêtes de débit ou crédit des abonnés.
Gestion de l’abonné
Du fait que le service d’abonnement se base sur un wallet mono moyen de paiement (1 wallet = 1 moyen de paiement), la gestion du wallet se limite :
- au changement d’un moyen de paiement par suppression du wallet existant et création d’un nouveau wallet ;
- à la suppression d’un wallet et des coordonnées de paiement à la demande de l’abonné (obligation légale).
Moyen de paiement expiré :
- les moyens de paiement (et les wallets associés) expirés depuis plus de 3 mois, sont supprimés automatiquement de la base wallet
Authentification de l’abonné
Dans la cinématique d’abonnement, vous devez authentifier votre client avant d’accéder à l’identifiant abonné stocké dans votre base client.
Une fois l’authentification faite, vous transmettez à Sherlock's l’identifiant abonné dans la requête via le champ merchantWalletId.
Votre gestion des identifiants abonnés attribués à vos clients doit :
- garantir une relation 1-1 entre l’abonné et le client (1 client = 1 Abonné) ;
- permettre le stockage des identifiants abonnés.
Sherlock's gère le stockage sécurisé des coordonnées de paiement de l’abonné.
Personnalisation des pages
Afin de conserver la charte graphique de votre site de commerce électronique, les pages des interfaces Sherlock’s Paypage et Sherlock's Walletpage sont personnalisables.
Veuillez consulter le guide de personnalisation des pages pour davantage d'informations.
Reporting
Nous préconisons l’utilisation de la version TAB20_V21, ou plus, des journaux des transactions, afin d’y retrouver les champs merchantWalletId et schemeTransactionIdentifier.
Pour gérer les cartes expirées, utilisez le journal des cartes échues.
Pour plus d’informations, merci de consulter le guide de description des journaux.
Données à conserver pour le chaînage CIT MIT
Afin de traiter les échéances suivantes de l'abonnement (MIT) et de
pouvoir les chaîner à la CIT, lors de la CIT, veuillez à bien conserver le
merchantWalletId.
Choix des connecteurs
Comme Sherlock's offre plusieurs interfaces pour enrôler les abonnés et traiter les paiements il convient d’analyser votre besoin métier pour choisir les connecteurs les plus adaptés à votre situation.
Le tableau ci-dessous vous aide à faire votre choix.
| Cas d'usage | Sherlock’s Paypage | Sherlock’s Office | Sherlock’s In-App | Sherlock’s Office Batch | Sherlock's Walletpage | Sherlock's Gestion | Préconisations pour choisir le connecteur |
|---|---|---|---|---|---|---|---|
| Gestion des pages d'enrôlement | |||||||
| Vous externalisez les pages de saisie des coordonnées de paiement pour vous affranchir des exigences PCI. | V | X | X | X | X | X | |
| Vous gérez les pages de saisie des coordonnées de paiement que vous intégrez dans votre processus d’enrôlement des abonnés. | X | V | V | X | X | X | Sherlock’s Office répond à votre besoin pour le e-commerce. Pour le m-commerce, nous préconisons l’usage de Sherlock’s In-App. |
| Débiter ou créditer l'abonné | |||||||
| Vous débitez ou créditez vos abonnés à échéances fixes (cas des forfaits ou des services facturés après consommation). | X | V | X | V | X | X | Le mode fichier de Sherlock’s Office Batch est le connecteur adapté au traitement périodique batch de paiement des abonnés, mais vous pouvez aussi utiliser Sherlock’s Office |
| Vous débitez ou créditez vos abonnés à échéances variables (cas des services prépayés où l’abonné doit charger son compte avant de consommer). | X | V | X | X | X | X | Le mode transactionnel de Sherlock’s Office est le connecteur adapté pour débiter ou créditer vos abonnés à échéances variables. |
| Gérer l'abonné | |||||||
| Renouveler le moyen de paiement de l'abonné. | Le renouvellement est traité comme l’enrôlement d’un abonné par l’enregistrement des coordonnées de paiement dans un nouveau wallet. | Réutilisez le même connecteur que celui utilisé pour l’enrôlement des abonnés. | |||||
| Vous supprimez l'abonné. | X | V | V | V | V | V | Utilisez Sherlock’s Office si vous souhaitez une suppression en temps réel et Sherlock’s Office Batch dans le cas contraire. Si vous ne souhaitez pas automatiser cette fonctionnalité, vous pouvez supprimer vos abonnés à partir de l’extranet BackOffice Sherlock's. |
| Initialisation de la base des abonnés | |||||||
| Vous migrez une base abonnés existante. | X | X | X | V | X | X | Sherlock’s Office Batch vous permet d’initialiser la base des abonnés à partir d’une base existante. |
Mise en œuvre
Afin de mettre en œuvre l’abonnement Sherlock's, vous devez vous munir du guide des connecteurs adéquat.
Enrôler l'abonné (CIT)
Enrôler l’abonné avec Sherlock’s Paypage
Il s’agit d’une cinématique de paiement Sherlock’s Paypage classique dans laquelle les coordonnées de paiement sont enregistrées dans le wallet en cas de transaction acceptée.
Description
- Pour enregistrer les coordonnées de paiement de l’abonné vous le redirigez versSherlock’s Paypage en communiquant dans la requête les données de la transaction (montant, devise, ..) ainsi que l’identifiant de l’abonné (champ merchantWalletId).
- Sherlock's affiche la page de paiement, l’abonné fournit ses coordonnées de paiement puis valide.
- Sherlock's procède à la vérification 3-D Secure.
- Sherlock's effectue les contrôles anti-fraude.
- Sherlock's envoie une demande d’autorisation à l’acquéreur.
- Sherlock's enregistre la transaction dans le back office.
- Si la transaction est acceptée Sherlock's enregistre les coordonnées de paiement de l’abonné dans le wallet.
- Sherlock's vous retourne les réponses manuelle et automatique contenant les détails de la transaction y compris le résultat de l’enregistrement de l’abonné dans le wallet.
- Sherlock's vous retourne les réponses manuelle et automatique contenant les détails de la transaction y compris le résultat de l’enregistrement de l’abonné dans le wallet.
- Sherlock's envoie ou pas la transaction en remise en fonction des modalités que vous avez paramétrées dans la requête de paiement.
Paramétrer la requête
Effectuer une requête de paiement classique Sherlock's comme décrit dans la documentation du connecteur.
Cependant, le champ suivant doit être valorisé comme ceci :
| Champ | Valeur |
|---|---|
| merchantWalletId | identifiant de l'abonné |
Pour les abonnements avec des cartes uniquement (obligation DSP2, voir documentation chaînage pour plus d'informations), les champs suivants ont un comportement spécial et doivent être renseignés comme ceci :
| Champ | Valeur |
|---|---|
| paymentPattern | RECURRING_1 |
| captureDay | 0 à 6 |
| captureMode | AUTHOR_CAPTURE ou VALIDATION |
| amount | montant du premier paiement, peut être valorisé à 0 (si le 1er mois de l'abonnement est gratuit par exemple). |
| authenticationAmount | à valoriser si le champ amount = 0 avec le montant moyen
d'une occurence de paiement de l'abonnement. Si le champ n'est pas rempli, le montant de l'authentification sera le même que celui indiqué dans le champ amount. |
| challengeMode3DS | forcé à CHALLENGE_MANDATE (authentification forte obligatoire pour les moyens de paiement CB, VISA, MC et AMEX avant l'ajout de la carte dans le wallet) |
Analyser la réponse
Sherlock's retourne une réponse manuelle et automatique classique Sherlock’s Paypage. Lorsque vous recevez la réponse, avant de l'analyser et suivre les conseils du tableau ci-dessous, vérifiez le seal. Le seal recalculé, doit être identique au seal reçu.
Les champs relatifs à l’enrôlement de l’abonné sont les suivants :
| Etat | Champs de la réponse | Actions à réaliser |
|---|---|---|
Transaction acceptée Abonné enrôlé |
|
Stockez dans votre base client les données suivantes :
Vous pouvez soumettre des paiements récurrents. |
Transaction acceptée Abonné non enrôlé |
|
Transaction acceptée mais problème technique temporaire lors de l’enrôlement du moyen de paiement dans le wallet. Demandez à l'abonné de s'enrôler à nouveau. |
Transaction refusée Abonné non enrôlé |
responseCode = XX (différent
de 00) |
Consultez le guide connecteur Sherlock’s Paypage pour analyser la réponse de Sherlock's. |
Enrôler l’abonné avec Sherlock’s Office
Avant d’enregistrer le moyen de paiement dans le wallet, vous devez au préalable l’avoir vérifié via une requête de paiement standard.
Description
Vous gérez la saisie des données du moyen de paiement sur votre site Web.
- Etape 1 : Vous faîtes une requête à Sherlock's
pour vérifier le moyen de paiement avant d’enrôler L'abonné.
- Authentification 3-D Secure pour vérifier que c’est bien le titulaire qui utilise la carte (CB, Visa, Mastercard, Amex, Bancontact).
- Contrôles de lutte contre la fraude que vous avez configurés en fonction de vos règles métier (ex. carte étrangère, carte commerciale, ..)
- Demande d’autorisation vers l’acquéreur pour vérifier que la carte n’est pas en opposition (carte volée, perdue, ..)
- Sherlock's enregistre la transaction.
- En fonction des éléments fournis dans la requête, Sherlock's envoie, ou pas, la transaction en remise vers l’acquéreur.
- Sherlock's vous envoie les résultats de la vérification du moyen de paiement.
- Etape 2 : Une fois la vérification du moyen de paiement effectuée, vous sollicitez Sherlock's une seconde fois pour enregistrer le moyen de paiement dans le wallet.
- Sherlock's vous retourne la réponse de l’enregistrement du moyen de paiement.
La séquence décrite ci-dessus se transpose sur les moyens de paiement Amex, et Bancontact.
Paramétrer les requêtes de vérification du moyen de paiement
Vous utilisez les méthodes ci-dessous en fonction du niveau de vérification du moyen de paiement à enrôler.
Carte CB, Visa, Mastercard, Bancontact, Oney, AMEX
- étape 1.1 cardCheckEnrollment : vérification de l'enrôlement 3-D Secure de la carte (voir documentation Sherlock’s Office JSON ou SOAP pour voir les paramètres de la requête)
- étape 1.2 cardValidateAuthenticationAndOrder : authentification et demande d'autorisation avec contrôles anti-fraude (voir documentation Sherlock’s Office JSON ou SOAP pour voir les paramètres de la requête)
Pour la méthode cardCheckEnrollment, les champs suivants ont un comportement particulier et doivent être valorisés comme ceci :
| Champ | Valeur |
|---|---|
| paymentPattern | RECURRING_1 |
| challengeMode3DS | CHALLENGE_MANDATE (authentification forte obligatoire pour les moyens de paiement CB, VISA, MC et AMEX avant l'ajout de la carte dans le wallet) |
| amount | montant de la première échéance de l'abonnement (peut-être valorisé à 0 si la première échéance est gratuite par exemple ou si le 1er paiement ne s'effectue que plus tard) |
| authentAmount | à valoriser si le champ amount = 0 avec le montant moyen
d'une occurence de paiement de l'abonnement. Si le champ n'est pas rempli, le montant de l'authentification sera le même que celui indiqué dans le champ amount. |
| captureDay | 0 à 6 |
| captureMode | AUTHOR_CAPTURE ou VALIDATION |
Mandat SDD
| Méthodes du service CheckOut | Type de vérification |
|---|---|
| directDebitOrder | Demande d’autorisation SDD avec contrôle anti-fraude |
Veuillez consulter le guide Sherlock’s Office correspondant au connecteur choisi (JSON ou SOAP) ainsi que les guides des moyens de paiement pour connaître les détails d'implémentation.
Analyser la réponse d’autorisation avec contrôles fraude
Lorsque vous recevez la réponse, avant de l'analyser et suivre les conseils du tableau ci-dessous, vérifiez le seal. Le seal recalculé, doit être identique au seal reçu.
Méthodes CardOrder, cardValidateAuthenticationAndOrder et directDebitOrder
| Etat | Champs de la réponse | Action à réaliser |
|---|---|---|
| Transaction acceptée |
|
Conservez dans votre système d'informations le champ schemeTransactionIdentifier.Vous pouvez enregistrer la carte dans le wallet via la méthode addcard ou addDirectDebit. |
| Transaction refusée | responseCode = XX |
Indiquez au client que son numéro de carte est invalide et demandez-lui d’enrôler un autre moyen de paiement. |
Paramétrer la requête d’enrôlement des coordonnées de paiement de l'abonné
Vous utilisez les méthodes ci-dessous en fonction du moyen de paiement à enrôler. Le champ merchantWalletId contient l’identifiant du client.
Carte CB, Visa, Mastercard, Bancontact, Oney, Amex
| Méthodes du service wallet | Type d’action |
|---|---|
| addcard | Ajout d’une carte dans le wallet |
Veuillez consulter le guide Sherlock’s Office adéquat ainsi que les guides des moyens de paiement pour savoir comment renseigner la requête en fonction de votre besoin métier.
Analyser la réponse d’enrôlement
Lorsque vous recevez la réponse, avant de l'analyser et suivre les conseils du tableau ci-dessous, vérifiez le seal. Le seal recalculé, doit être identique au seal reçu.
| Etat | Champs de la réponse | Action à réaliser |
|---|---|---|
| Abonné enrôlé | walletReponseCode = 00 paymentMeanId = 1 |
Le moyen de paiement a été ajouté au wallet. Vous pouvez débiter ou créditer votre abonné. |
Abonné non enrôlé Requête invalide |
walletReponseCode = xx paymentMeanId = non renseigné |
Consultez le guide connecteur Sherlock’s Office pour analyser la réponse de Sherlock's. |
Débiter un abonné (MIT)
Débiter l’abonné avec Sherlock’s Office Batch
Une fois l’abonné enregistré, vous pouvez le débiter en mode fichier avec Sherlock’s Office Batch.
Description
Vous formatez un fichier Sherlock’s Office Batch en utilisant la méthode walletOrder.
Chaque enregistrement walletOrder contient :
- L’identifiant de l’abonné à débiter (champ merchantWalletId),
- Les données des transactions (montant, référence commande,…).
- Pour les débit avec des cartes uniquement : l'identifiant reliant le débit à l'enrôlement de la carte (champ initialTransactionSchemeIdentifier)
- Vous envoyez le fichier à Sherlock's via FTPS ou SFTP.
- Sherlock's récupère les coordonnées de paiement de l’abonné stockées dans le wallet.
- Sherlock's exécute des contrôles anti-fraude que vous avez configurés sur votre boutique.
- Sherlock's envoie les demandes d’autorisation aux acquéreurs.
- Sherlock's stocke la transaction dans le back office.
- Sherlock's formate le fichier réponse et vous le renvoie.
- Le soir, Sherlock's envoie les remises de paiement des transactions acceptées.
Veuillez consulter les guides Sherlock’s Office Batch XML ou Sherlock’s Office Batch CSV pour avoir le détail sur la mise en œuvre (structure du fichier, description des enregistrements, transfert du fichier, gestion des erreurs…).
Paramétrer la requête
Pour générer un paiement récurrent avec la méthode walletOrder, vous renseignez les champs ci-dessous :
| Champ | Valeur | Commentaire |
|---|---|---|
| merchantWalletID | ˂id abonné˃ | |
| paymentMeanId | 1 | L’identifiant du moyen de paiement dans le wallet est obligatoire bien que le wallet ne contienne qu'un seul moyen de paiement. |
Veuillez consulter les guides Sherlock’s Office Batch XML ou Sherlock’s Office Batch CSV pour savoir comment renseigner les autres champs de la requête en fonction de votre besoin métier.
Pour les paiements avec des cartes, les champs ci-dessous ont un comportement particuliers et doivent être valorisé comme ceci :
| Champ | Valeur | Commentaire |
|---|---|---|
| paymentPattern | RECURRING_N | Paiement récurrent pour indiquer à l’acquéreur qu'il n’y a pas de données 3-D Secure et le CVV. |
| cardCSCValue | Non renseigné | |
| initialSchemeTransactionIdentifier | valeur du champ schemeTransactionIdentifier reçue lors de la prise d'abonnement |
Analyser la réponse
| Etat | Champs de la réponse | Actions à réaliser |
|---|---|---|
| Transaction acceptée | responseCode = 00 | Vérifier le lendemain dans le journal des transactions que l’envoi en paiement a bien été effectué (transactionStatus = CAPTURED). |
| Transaction refusée | responseCode = XX | Consultez les guides connecteurs Sherlock’s Office Batch pour analyser la réponse de Sherlock's. |
Débiter l’abonné avec Sherlock’s Office
Le connecteur Sherlock’s Office JSON/SOAP propose aussi la méthode walletOrder en mode message avec les mêmes règles que Sherlock’s Office Batch pour le formatage de la requête et l’analyse de la réponse.
Veuillez consulter un des guides Sherlock’s Office pour avoir le détail de mise en œuvre.
Créditer l'abonné
Créditer l’abonné avec Sherlock’s Office Batch
Vous pouvez créditer un abonné à partir de son identifiant sans faire référence à une transaction initiale de débit.
Description
La solution Sherlock’s Office Batch permet de réaliser des paiements par lot.
Vous formatez un fichier Sherlock’s Office Batch en utilisant la méthode walletCredit.
Chaque enregistrement walletCredit contient :
- L’identifiant de l’abonné à débiter (champ merchantWalletId),
- Les données des transactions (montant, référence commande,…).
- Vous envoyez le fichier à Sherlock's via FTPS ou SFTP.
- Sherlock's récupère les coordonnées de paiement de l’abonné stockées dans le wallet.
- Sherlock's envoie les demandes d’autorisation aux acquéreurs.
- Sherlock's stocke la transaction dans le back office.
- Sherlock's formate le fichier réponse et vous le renvoie.
- Le soir, Sherlock's envoie les remises de paiement des transactions acceptées.
Veuillez consulter les guides Sherlock’s Office Batch XML ou CSV pour avoir le détail sur la mise en œuvre (structure du fichier, description des enregistrements, transfert du fichier, gestion des erreurs…).
Paramétrer la requête
Pour générer un paiement récurrent abonné avec la méthode walletCredit, vous renseignez les champs ci-dessous :
| Champ | Valeur | Commentaire |
|---|---|---|
| merchantWalletID | ˂id abonné˃ | |
| paymentMeanId | 1 | L’identifiant du moyen de paiement dans le wallet est obligatoire bien que le wallet ne contienne qu'un seul moyen de paiement. |
Veuillez consulter les guides Sherlock’s Office Batch XML ou Sherlock’s Office Batch CSV pour savoir comment renseigner les autres champs de la requête en fonction de votre besoin métier.
Analyser la réponse
| Etat | Champs de la réponse | Actions à réaliser |
|---|---|---|
| Transaction acceptée | responseCode = 00 | Vérifier le lendemain dans le journal des transactions que l’envoi en paiement a bien été effectué (transactionStatus = CREDITED) |
| Transaction refusée | responseCode = XX | Consultez le guide connecteur Sherlock’s Office Batch pour analyser la réponse de Sherlock's. |
Créditer l’abonné avec Sherlock’s Office
Le connecteur Sherlock’s Office JSON/SOAP propose aussi la possibilité de créditer un abonné via la méthode walletCreditHolder en mode message.
Les règles pour le formatage de la requête et l’analyse de la réponse sont les mêmes que celles de Sherlock’s Office Batch.
Veuillez consulter le guide Sherlock’s Office pour avoir le détail de mise en œuvre.
Gérer les moyens de paiement et le compte d’un abonné
Avec Sherlock's Walletpage
Description
L’interface Sherlock's Walletpage permet à l’abonné de gérer de manière autonome son wallet. Les fonctionnalités autorisées dans le cadre d'un abonnement sont les suivantes :
- consultation du contenu d’un compte abonné,
- édition du nom (alias) d’un moyen de paiement d’un compte abonné,
- suppression d’un compte abonné.
Paramétrer la requête
Par défaut, l’ensemble des fonctionnalités de gestion est disponible pour l’utilisateur. Toutefois, il est possible de réduire le périmètre de ces fonctionnalités, en indiquant la liste de fonctionnalités souhaitée dans le champ walletActionNameList.
Pour la gestion de wallet, vous devez renseigner les champs ci-dessous :
| Champ | Valorisation |
|---|---|
| merchantWalletId | Identifiant de l'abonné |
| walletActionNameList | Valoriser comme ceci : UPDATEPM,SIGNOFF |
Veuillez consulter le guide Sherlock's Walletpage correspondant au connecteur choisi (JSON, POST ou SOAP) pour savoir comment renseigner la requête en fonction de votre besoin métier.
Analyser la réponse
Lorsque vous recevez la réponse, avant de l'analyser et suivre les conseils du tableau ci-dessous, vérifiez le seal. Le seal recalculé, doit être identique au seal reçu.
| Etat | Champs de la réponse | Actions à réaliser |
|---|---|---|
| abonné supprimé | walletPaymentMeanDataList non renseigné | |
| abonné non supprimé | walletPaymentMeanDataList renseigné | Vous pouvez mettre à jour votre système d’information avec le nouveau contenu du wallet. |
Avec Sherlock’s Office et Sherlock’s Office Batch
Vue d'ensemble
Le service « Wallet » de l’interface Sherlock’s Office vous permet de gérer le contenu des wallets de vos clients. Les fonctionnalités suivantes sont disponibles :
- Obtention du contenu complet d’un compte abonné,
- Obtention du détail d’un moyen de paiement contenu dans un compte abonné,
- Suppression d’un compte abonné,
En utilisant les interfaces Sherlock’s Office ou Sherlock’s Office Batch, vous devez gérer les pages de gestion du wallet pour permettre à vos abonnés de gérer leur compte.
Consulter le contenu d’un compte abonné avec Sherlock’s Office
Sherlock’s Office vous permet de consulter les coordonnées d’un client via la requête getWalletData.
- Paramétrer la requêtePour consulter le contenu d’un wallet avec la méthode getWalletData, vous devez renseigner les champs ci-dessous :
Champ Valorisation merchantWalletID Identifiant du client Veuillez consulter le guide Sherlock’s Office correspondant au connecteur choisi (JSON ou SOAP) pour savoir comment renseigner les autres champs de la requête en fonction de votre besoin métier.
- Analyser la réponse
Etat Champs de la réponse Action à réaliser abonné trouvé dans la base wallet walletReponseCode = 00
walletPaymentMeanDataList renseigné avec les moyens de paiement enregistrés dans le walletL'abonné existe dans le wallet. Analysez le champ walletPaymentMeanDataList pour accéder aux données du moyen de paiement du client.- paymentMeanBrand
- paymentMeanId
- maskedPAN
- PANExpiryDate
abonné non trouvé dans la base wallet walletReponseCode = 25
Le compte a été supprimé ou n’a pas été créé. Autre refus walletReponseCode = xx
Consultez le guide Sherlock’s Office correspondant au connecteur choisi (JSON ou SOAP) pour analyser la réponse de Sherlock's.
Modifier le nom d'un moyen de paiement d’un compte abonné avec Sherlock’s Office
Sherlock’s Office vous permet de modifier l’alias d’un moyen de paiement d’un abonné via la requête updatePaymentMean.
- Paramétrer la requêtePour modifier un moyen de paiement avec la méthode updatePaymentMean, vous devez renseigner les champs ci-dessous :
Champ Valorisation merchantWalletID Identifiant du client paymentMeanId Numéro de séquence du moyen de paiement paymentMeanAlias Nouvel alias du moyen de paiement
Veuillez consulter le guide Sherlock’s Office correspondant au connecteur choisi (JSON ou SOAP) pour savoir comment renseigner les autres champs de la requête en fonction de votre besoin métier.
- Analyser la réponse
| Etat | Champs de la réponse | Action à réaliser |
|---|---|---|
| Alias modifié | walletReponseCode = 00 walletActionDateTime renseigné |
|
| Client non trouvé dans base wallet | walletReponseCode = 25 |
Le compte abonné n’existe pas. |
| Autre refus | walletReponseCode = xx |
Consultez le guide Sherlock’s Office correspondant au connecteur choisi (JSON ou SOAP) pour analyser la réponse de Sherlock's. |
Supprimer un abonné avec Sherlock’s Office
Sherlock’s Office vous permet de supprimer un abonné via la requête signOff.
- Paramétrer la requête
Pour supprimer un wallet avec la méthode signOff, vous devez renseigner les champs ci-dessous :
| Champ | Valorisation |
|---|---|
| merchantWalletID | Identifiant du client |
Veuillez consulter le guide Sherlock’s Office correspondant au connecteur choisi (JSON ou SOAP) pour savoir comment renseigner les autres champs de la requête en fonction de votre besoin métier.
- Analyser la réponse
| Etat | Champs de la réponse | Action à réaliser |
|---|---|---|
| abonné supprimé | walletReponseCode = 00 | Vous pouvez mettre à jour votre système d’information |
| abonné non supprimé | walletReponseCode = xx | Consultez le guide Sherlock’s Office correspondant au connecteur choisi (JSON ou SOAP) pour analyser la réponse de Sherlock's. |
Changer ou renouveler le moyen de paiement d’un abonné
Si l’abonné souhaite changer de moyen de paiement (carte perdue, validité expirée, …), vous devez créer un nouveau wallet avec un nouvel identifiant abonné pour enregistrer les nouvelles coordonnées de paiement.
Anticiper l’expiration des moyens de paiement des abonnés
Vous recevez mensuellement par mail ou fichier SFTP le journal des cartes échues. Ce journal référence les clients dont le moyen de paiement va expirer dans un délai 3 mois (délai paramétrable de 1 à 3 mois).
A partir du journal des cartes échues, vous pouvez alerter vos clients pour qu'ils renouvellent leur moyen de paiement enregistré dans le wallet.
A noter que vous n’avez pas besoin de ce fichier pour connaître la date d’expiration du moyen de paiement des clients. En effet, lors de l’enrôlement de l'abonné, vous recevez en réponse des informations que vous pouvez stocker dans votre système d’information :
- Identifiant du moyen de paiement dans le wallet (champ paymentMeanId)
- Marque du moyen de paiement (champ paymentMeanBrand)
- Date d'expiration (champ panExpiryDate)
- PAN masqué (champ maskedPAN)
Pour avoir le contenu détaillé du journal des cartes échues, veuillez consulter le document Description des journaux.
Synthèse
Abonnement dont 1er paiement à moins de 6 jours
Voici un exemple de paiement par abonnement avec une première échéance à moins de 6 jours :
Connecteurs :
| CIT | MIT | |
|---|---|---|
| Connecteur |
|
|
Paramètres de la requête :
| champ | CIT | MIT |
|---|---|---|
| paymentPattern | RECURRING_1 | RECURRING_N |
| ChallengeMode3DS | CHALLENGE_MANDATE | X |
| captureDay | [ 0 , 6 ] | [ 0 , 99 ] |
| captureMode |
|
|
| amount | montant 1ère échéance | montant nème échéance |
| authentAmount | montant moyen des échéances | X |
| initialSchemeTransactionIdentifier | X | valeur du champ schemeTransactionIdentifier reçu en réponse de la CIT |
Abonnement dont 1er paiement à plus de 6 jours
Voici un exemple de paiement par abonnement avec une première échéance à plus de 6 jours :
Connecteurs :
| CIT | MIT | |
|---|---|---|
| Connecteur |
|
|
Paramètres de la requête :
| champ | CIT | MIT |
|---|---|---|
| paymentPattern | RECURRING_1 | RECURRING_N |
| ChallengeMode3DS | CHALLENGE_MANDATE | X |
| captureDay | 0 | [ 0 , 99 ] |
| captureMode | X |
|
| amount | 0 | montant nème échéance |
| authentAmount | montant moyen des échéances | X |
| initialSchemeTransactionIdentifier | X | valeur du champ schemeTransactionIdentifier reçu en réponse de la CIT |
Démarrer l’abonnement en 5 étapes
Etape 1 - Souscrire au service
Votre boutique n’est pas inscrite sur Sherlock's.
Si votre boutique n’a pas encore été inscrite, vous devez remplir le formulaire d’inscription (en demandant le service abonnement) et le retourner à LCL.
Votre boutique est déjà inscrite sur Sherlock's.
Si votre boutique est déjà inscrite sur Sherlock's, vous devez demander à LCL d’activer le service abonnement.
Données de configuration du service abonnement.
- Interfaces utilisées pour l’enrôlement
- Sherlock’s Paypage
- Sherlock’s Office
- Sherlock’s Office Batch
- Interfaces utilisées pour débiter ou créditer vos abonnés
- Sherlock’s Office
- Sherlock’s Office Batch
- Dans le cas d’une base abonnés partagée entre plusieurs boutiques d’une même enseigne, indiquer l’identifiant de l’enseigne.
Si ce n’est pas précisé, Sherlock's définit une base wallet dédiée à votre boutique.
Etape 2 - Mettre en œuvre le service
Lorsque vous avez choisi les interfaces Sherlock's qui répondent à votre besoin (cf. chap. 3), vous devez intégrer les connecteurs Sherlock's pour connecter votre site à Sherlock's.
Le chapitre précédent a décrit comment utiliser Sherlock's dans le cadre de l’abonnement en fonction des différents connecteurs :
- Nom des méthodes,
- Valorisation et analyse des champs métier de l’abonnement.
Vous devez consulter les guides des connecteurs choisis pour paramétrer les requêtes de paiement en fonction de vos besoins (customerID, orderId, returnContext,….).
Etape 3 - Tester le service sur l’environnement recette
Une fois la mise en œuvre des connecteurs Sherlock's réalisée, vous pouvez effectuer des tests pour valider votre intégration de Sherlock's.
Contactez l’assistance technique pour vous configurer un transfert de fichier si vous utilisez Sherlock’s Office Batch.
| Données de test | |
|---|---|
| merchantId | 201000076660001 |
| clé secrète | 8yTiAEzvhl7xt3_oEbdaH9Y9NY9A4XpNEjkk6q6Dou4 |
| version de la clé | 1 |
| carte de test | cf page "Cartes de test" |
| Serveur | URL de test |
|---|---|
| Sherlock’s Paypage POST | https://payment-webinit-sherlocks.test.sips-services.com/paymentInit |
| Sherlock’s Paypage JSON | https://payment-webinit-sherlocks.test.sips-services.com/rs-services/v2/paymentInit |
| Sherlock’s Paypage SOAP | https://payment-webinit-sherlocks.test.sips-services.com/services/v2/paymentInit |
| Sherlock’s Office | https://office-server-sherlocks.test.sips-services.com/ |
| Sherlock's Walletpage POST | |
| Sherlock's Walletpage JSON | |
| Sherlock's Walletpage SOAP |
la boutique de test est configurée en mode transactionReference, sans génération automatique du transactionReference. Par conséquent, il est nécessaire que vous transmettiez le champ transactionRefence valorisé dans vos requêtes de test.
Etape 4 - Valider le service en production
Vous êtes à présent en mesure de valider la connexion à Sherlock's de production.
Au préalable, nous conseillons d’isoler votre site Web du public pour éviter que des clients effectuent des transactions pendant cette phase de validation.
Vous devez changer l’URL pour vous connecter au serveur Sherlock's de production en utilisant les identifiants reçus lors l’inscription merchantId, secretKey et keyVersion.
| URL Sherlock's | URL du serveur de paiement Sherlock's récupéré par mail. |
| MerchantId | Identifiant de la boutique reçu par mail. |
| 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é). |
Si vous souhaitez personnaliser vos pages de paiement ou vos pages de gestion du wallet, veuillez suivre la procédure décrite dans le document Custompages.
Comment valider l’enrôlement
Immédiatement
- Soumettez une requête d’enrôlement selon le scénario d’enrôlement que vous avez choisi.
- Consultez le contenu du wallet via la méthode getWalletData du connecteur Sherlock’s Office.
- Soumettez une seconde fois la requête avec le même identifiant abonné, vous devez avoir un refus d’enrôlement car le wallet est mono moyen de paiement.
Comment valider le débit abonné
Immédiatement
- Soumettez une requête walletOrder pour déclencher un débit abonné.
- Consultez la transaction via Sherlock's Gestion à partir du transactionReference ou du S10transactionId.
Le lendemain
- Vérifiez la présence de la transaction dans le journal des transactions.
- Vérifiez sur votre compte commerçant que l’opération a bien été créditée.
- Remboursez la transaction via Sherlock's Gestion BackOffice (optionnel).
Le sur lendemain
- Vérifiez que l’opération de remboursement apparaît dans le journal des opérations.
- Vérifiez sur votre compte commerçant le débit suite au remboursement.
Comment valider le crédit abonné
Immédiatement
- Soumettez une requête walletCredit ou WalletCreditHolder pour déclencher un crédit abonné.
- Consultez la transaction via Sherlock's Gestion à partir du transactionReference ou du S10transactionId.
Le lendemain
- Vérifiez la présence de la transaction dans le journal des transactions.
- Vérifiez sur votre compte que l’opération a bien été débitée.
Etape 5 - Démarrer le service en production
Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos abonnés d'utiliser le service OneClick et de s’enregistrer.
L’enrôlement des abonnés
Dans la journée
- Surveillez le taux d’acceptation (nombre de responseCode 00 par rapport au nombre total de transactions),
- Vérifiez la nature des refus non bancaires,
- Problème technique : responseCode 90, 97, 99,
- Fraude : responseCode 34, 3D Failure,
- Nombre max de tentatives de paiement atteint : responseCode 75.
Le lendemain
- Vérifiez dans le journal des transactions la présence de toutes les transactions traitées (acceptées et refusées),
- Vérifiez, dans le journal des opérations, la présence des opérations que vous avez effectuées ainsi que les remises (si vous avez choisi cette option du journal).
Le débit des abonnés
- Surveillez le taux d’acceptation (nombre de responseCode 00/nombre total de transactions).
- Vérifiez la nature des refus non bancaires
- Problème technique : responseCode 90, 97, 99,
- Fraude acquéreur : responseCode 34.
