Introduction
A qui s'adresse ce document ?
Ce document s’adresse aux commerçants qui souhaitent une intégration rapide et simple de la solution Sherlock's. Il vous permet de démarrer avec le connecteur Sherlock’s Paypage POST sans personnalisation des pages de paiement.
Les options décrites dans ce guide sont les plus couramment utilisées.
Ce guide vous explique comment accepter des paiements :
- en euros ;
- avec les moyens de paiement Visa, Vpay, Electron, Mastercard, Maestro et PayPal ;
- sécurisés par 3-D Secure.
Vous utilisez Sherlock's Gestion pour la gestion de caisse et recevez quotidiennement les journaux par mail.
Ce document est valable pour la version 2.18 du connecteur et les versions ultérieures.
Prérequis
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 à Sherlock’s Paypage POST.
Gestion de la clé secrète
Lors de votre inscription, LCL met à disposition sur Sherlock’s Téléchargement (voir l'annexe "Télécharger la clé secrète"), une clé secrète qui permet de sécuriser les échanges entre votre site 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.
Sherlock's en bref
Sherlock's est une solution de paiement e-commerce 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, …).
Vous gardez le choix de votre établissement bancaire et des moyens de paiement acceptés.
Quotidiennement, Sherlock's envoie par mail les journaux d’activité :
- Le journal des transactions qui récapitule l’ensemble des transactions acceptées ou refusées.
- Le journal des opérations qui récapitule les opérations de caisse que vous avez effectuées.
- Le journal de rapprochement des transactions qui donne la vue financière des paiements crédités sur vos comptes.
- Le journal de rapprochement des impayés qui rapproche les impayés de l’établissement bancaire (ex. contestation porteur) avec les transactions que vous avez acceptées.
Sherlock's propose l’interface Sherlock’s Paypage pour connecter votre site Web à la plateforme de paiement.
Sherlock’s Paypage assure l’interface de paiement directement avec votre client via un navigateur Internet ou un mobile.Sherlock’s Paypage met donc à votre disposition des pages de paiements sécurisées, prêtes à l’emploi et accessibles par vos clients.
Sherlock’s Paypage s’accompagne d’une interface web de gestion de caisse : Sherlock's Gestion. Elle vous permet de créer et gérer vos transactions. (validation, annulation, remboursement, ….)
Fonctionnement de Sherlock’s Paypage
| Ref | Nom | Fréquence | Description |
|---|---|---|---|
| a1 | Requête de paiement Sherlock’s Paypage | 24h/24h | Requête de paiement envoyée par vous au serveur Sherlock's |
| a2 | Réponse automatique | 24h/24h | Réponse du serveur Sherlock's qui vous est envoyée une fois le paiement effectué. Envoi automatique indépendant de l’action du client. En cas d'abandon du client, vous recevrez la réponse automatique environ 15 minutes après la redirection du client vers les pages de paiement Sherlock's |
| a3 | Réponse manuelle | 24h/24h | Réponse du serveur Sherlock's qui vous est envoyée lorsque le client clique sur « continuer ». Envoi conditionné par l’action du client. |
| d1 | Authentification du porteur | 24h/24h | Requête envoyée au serveur d’authentification 3-D Secure de la banque du porteur |
| e1 | Demande d’autorisation | 24h/24h | Demande d’autorisation envoyée à votre établissement bancaire |
| e2 | Remise en paiement | 1/jour | Remise en paiement envoyé par Sherlock's vers l’établissement bancaire pour vous créditer |
| e3 | Retour du paiement | 24h/24h | Retour de l’établissement bancaire sur le traitement d’acquisition des paiements |
| b | Gestion de caisse | 24h/24h | Opération de caisse envoyée par vous au serveur Sherlock's |
| c | Journaux | 1/jour | Journaux envoyés par mail |
Cinématique d'une transaction CB, VISA, MASTERCARD
Le parcours client est le suivant :
- Validation du panier de votre page commerçant,
- Redirection du client sur la page Sherlock's de sélection du moyen de paiement,
- Saisie des données carte,
- Authentification du client sur une page de sa banque (si 3-D Secure),
- Affichage du ticket de caisse par Sherlock's,
- Confirmation de la prise en compte de la commande sur votre page commerçant.
Dans cette cinématique que la saisie des données de la carte s'effectue chez Sherlock's.Vous n’avez pas connaissance de ces données sensibles.
Cinématique d'une transaction PayPal
Le parcours client est le suivant :
- Validation du panier sur votre page commerçant
- Redirection du client sur la page de sélection du moyen de paiement Sherlock's
- Identification du client sur une page PayPal et validation du moyen de paiement
- Affichage du ticket de caisse par Sherlock's
- Confirmation de la prise en compte de la commande sur votre page commerçant
Identification des transactions
Les transactions de votre boutique sont identifiées de manière unique grâce au champ transactionReference.
Cet identifiant est calculé par Sherlock's ou par vous lors de la création de la transaction. Le couple (transactionReference, merchantId) identifie de manière unique la transaction pendant toute la vie de la transaction.
Démarrer avec Sherlock’s Paypage POST en 5 étapes
Pour accepter des paiements via Sherlock's vous devez avoir préalablement signé :
- un contrat de vente à distance e-commerce/vente par correspondance (VPC) avec votre banque ;
- un contrat d’acceptation avec le revendeur de la solution Sherlock's ;
La souscription au service 3-D Secure de Visa et MasterCard qui sécurise les paiements internet est une clause obligatoire du contrat de vente à distance avec votre banque.
Pour pouvoir accepter les paiements PayPal, vous devez également avoir signé un contrat avec PayPal. Votre compte commerçant PayPal doit également être configuré de manière à autoriser l’appel à Sherlock's (cf annexe "paramétrer son compte PayPal").
Étape 1 : inscrire la boutique
Afin d’inscrire votre boutique, vous devez remplir le formulaire d’inscription envoyé par LCL et le retourner à ce dernier.
Lors de la saisie du formulaire, vous désignez un contact administratif et un contact technique afin que LCL puisse vous communiquer les informations nécessaires pour démarrer votre boutique.
LCL procède alors à l’enregistrement de la boutique et vous retourne votre identifiant commerçant (merchantId) ainsi que vos identifiants et mots de passe Portail Sherlock's (récupération de la clé secrète et gestion de caisse).
L’inscription de la boutique n’est pas nécessaire pour commencer à intégrer le connecteur et à tester la connexion sur l’environnement de simulation. Vous pouvez ne demander l’inscription de votre boutique qu’au moment de faire les tests en production.
Etape 2 : Connecter votre site à Sherlock’s Paypage
Vous devez intégrer le connecteur Sherlock’s Paypage POST pour connecter votre site commerçant au serveur de paiement Sherlock's.
Vous devez donc mettre en place les liens a1 (requête de paiement), a2 et a3 (réponse de paiement automatique et manuelle) décrits dans ce schéma :
Si le client ne clique pas sur « continuer », la réponse manuelle ne sera pas envoyée et vous n’aurez pas de réponse venant de Sherlock's vous confirmant le traitement de la transaction.
Générer la requête de paiement
La requête paiement est envoyée depuis une page de votre site web vers le serveur Sherlock's via un formulaire web avec la méthode POST. Ce formulaire doit pointer vers l’URL du serveur de paiement Sherlock's et contenir les champs suivants :
| Donnée du formulaire | Présence | Description |
|---|---|---|
| Data | Obligatoire | Ensemble des champs de la requête de paiement (champs décrits ci-dessous dans la partie « construire la requête de paiement : donnée Data ») |
| InterfaceVersion | Obligatoire | L’interface version définit la version de la requête et de la réponse échangée avec le serveur de paiement. Les champs décrits ci-après correspondent à la dernière interfaceVersion. Si vous utilisez une version antérieure du connecteur, il est possible que certains champs ne soient pas disponibles et ne puissent être utilisés. |
| Seal | Obligatoire | Signature de la donnée Data qui permet de garantir la sécurité de la requête de paiement |
| Encode | Optionnel | Dans le cas où la donnée Data comporte des caractères
spéciaux, vous devez changer l’encodage. La valeur du champ Encode
précise la méthode d’encodage utilisée pour la donnée Data. En cas
d’encodage, le seal est calculé sur la donnée data
encodé. Valeurs:
|
| SealAlgorithm | Optionnel | Algorithme utilisé pour le calcul de l’empreinte de la
donnée Data Valeurs :
|
Construire la requête de paiement : donnée Data
La donnée Data est composée de plusieurs champs, elle contient toutes les informations relatives à la transaction.
Elle est fournie sous la forme d’une chaîne de caractères respectant la syntaxe suivante :
<nomChamp1>=<valeurChamp1>|<nomChamp2>=<valeurChamp2>|… |<nomChampN>=<valeurChampN>La donnée Data est composée des champs suivants :
- Champs obligatoires
| Champs | Format | Description |
|---|---|---|
| amount | N12 | Montant de la transaction. Il doit être transmis dans la plus petite unité de la devise. Ex : pour l’Euro, un montant de 10,50€ doit être transmis sous la forme 1050. |
| currencyCode | N3 (restricted values / ISO4217) | Code de la devise de la transaction. Ce code est compatible ISO 4217. Ex : le code de l’euro est 978. |
| keyVersion | N10 | Version de la clé secrète du commerçant utilisée pour calculer le seal du message. Ex : KeyVersion=1 pour la 1ère clé générée à l’inscription de la boutique. |
| merchantId | N15 | Identifiant de la boutique, fourni par Sherlock's au commerçant lors de l’inscription de sa boutique. |
| normalReturnUrl | ANS512 (url) | URL du commerçant pour le retour à la boutique en cas d’acceptation ou de refus de la transaction (réponse manuelle). Ex : https://www.monsite.fr/RetourPaiement |
| automaticResponseUrl | ANS512 (url) | URL fournie par le commerçant et utilisée par le serveur de
paiement pour notifier au commerçant de manière online et
automatique le résultat de la transaction (réponse
automatique). NB : champ non obligatoire mais utilisation fortement recommandée pour que vous receviez la réponse de paiement même si le client ne clique pas sur « continuer » |
- Principaux champs métiers facultatifs qui vous permettent de faciliter la correspondance entre votre système d’information et le serveur de paiement Sherlock's
| Champs | Format | Description |
|---|---|---|
| customerId | ANS19 (restrictedString) | Identifiant du client |
| customerEmail | ANS128 (email) | E-mail du client |
| orderId | ANS32 | Numéro de commande associé à la transaction de paiement. |
| returnContext | ANSU255 (extendedString) | Contexte de la commande transmis dans la requête de paiement et restitué sans modification dans la réponse et le journal des transactions. Vous pouvez y stocker toute les informations qui facilitent le traitement de la réponse. |
- Champs CB, Visa, Mastercard, Vpay, Electron et Maestro : Pas de champ spécifique
- Champs PayPal (champs disponibles depuis la version HP_2.18)
| Champs | Format | Description |
|---|---|---|
| addrOverride | ANS20 (restricted values) | Indicateur vous permettant :
Valeurs :
|
| invoiceId | AN127 | Numéro de commande, équivaut à l’orderId mais doit être unique chez PayPal. Obligatoire pour l’utilisation de PayPal. |
| landingPage | AN5 (restricted values) | Indicateur vous permettant de masquer le formulaire de
souscription sur les pages PayPal. Valeurs :
|
| mobile | AN5 (restricted values) | Indicateur vous permettant de préciser si le terminal
utilisé par le client est le mobile Valeurs :
|
| orderDescription | ANS127 | Description de la commande |
Sécuriser la requête
La requête contient les paramètres de la transaction et est envoyée par le navigateur Web du client. Il est théoriquement possible pour un pirate d’intercepter la demande et de la modifier avant l’envoi au serveur de paiement.
De ce fait, il est nécessaire de renforcer la sécurité pour assurer l’intégrité des paramètres de la transaction envoyée. Sherlock's répond à ce besoin par un échange de signatures qui permet de vérifier :
- l’intégrité des messages requête et réponse ;
- l’authentification de l’émetteur et du destinataire car ils se partagent la même clé secrète.
Signer l'empreinte de la requête de paiement
La sécurisation de la requête est effectuée en calculant la valeur « hashée » conformément aux paramètres de la transaction (donnée Data). Ensuite, la clé secrète y est ajoutée. Toutes les chaînes de caractères sont converties en UTF-8 avant le « hashage ».
L’algorithme de « hashage » génère un résultat irréversible qui doit être envoyé sous forme hexadécimale dans le champ POST nommée Seal.
Lorsque le message est reçu, le destinataire doit recalculer la valeur « hashée » pour la comparer à celle reçue. Toute différence indique que les données échangées ont été falsifiées.
Il existe 2 méthodes pour signer l’empreinte de la donnée Data :
Pour l’algorithme HMAC-SHA256 :
- Utilisation de la donnée Data uniquement (encodée si l’option correspondante est choisie)
- Utilisation de la clé secrète partagée pour générer la variante HMAC du message
- Codage UTF-8 des données constituant le résultat de l’opération précédente
- « Hashage » HMAC-SHA256 des octets obtenus
HMAC-SHA256( UTF-8(Data), UTF-8(secretKey))Pour l’algorithme SHA-256 (bien que celui-ci soit la valeur par défaut, cet algorithme n’est plus recommandé à ce jour) :
- Concaténation du champ Data et de la clé secrète (encodée si l’option correspondante est choisie)
- Codage UTF-8 des données constituant le résultat de l’opération précédente
- « Hashage » SHA256 des octets obtenus
SHA256( UTF-8(Data+secretKey))Exemples de code Hmac Sha256
- Exemple d’encodage Hmac Sha256 en Php 5
<?php … // Seal computation thanks to hash sorted data hash with merchant key $data_to_send= utf8_encode($data) $seal=hash_hmac('sha256', $data_to_send, $secretKey); … … ?>data_to_send et secretKey doivent utiliser un jeu de caractères UTF-8. Référez-vous à la fonction utf8_encode pour la conversion de caractères ISO-8859-1 en UTF-8.
- Exemple d’encodage Hmac Sha256 en Java
import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class ExampleHMACSHA256 { /** * table to convert a nibble to a hex char. */ static final char[] hexChar = { '0' , '1' , '2' , '3' , '4' , '5' , '6' , '7' , '8' , '9' , 'a' , 'b' , 'c' , 'd' , 'e' , 'f'}; /** * Fast convert a byte array to a hex string * with possible leading zero. * @param b array of bytes to convert to string * @return hex representation, two chars per byte. */ public static String encodeHexString ( byte[] b ) { StringBuffer sb = new StringBuffer( b.length * 2 ); for ( int i=0; i<b.length; i++ ) { // look up high nibble char sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] ); // look up low nibble char sb.append( hexChar [b[i] & 0x0f] ); } return sb.toString(); } /** * Computes the seal * @param Data the parameters to cipher * @param secretKey the secret key to append to the parameters * @return hex representation of the seal, two chars per byte. */ public static String computeSeal(String data, String secretKey) throws Exception { Mac hmacSHA256 = Mac.getInstance("HmacSHA256"); SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"); hmacSHA256.init(keySpec); return encodeHexString(hmacSHA256.doFinal(data.getBytes())); } /** * @param args */ public static void main(String[] args) { try { System.out.println (computeSeal("parameters", "key")); } catch (Exception e) { e.printStackTrace(); } } } - Exemple d’encodage Hmac Sha256 en .net
(Exemple effectué à l’aide d’un simple formulaire nommé « Form1 » contenant deux champs texte pour saisir data et txtSecretKey, ainsi qu’un autre champ pour afficher lblHEX).
using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Text; using System.Windows.Forms; using System.Security.Cryptography; namespace ExampleDotNET { public partial class Form1 : Form { public Form1() { InitializeComponent(); } private void cmdGO_Click(object sender, EventArgs e) { String sChaine = data.Text; UTF8Encoding utf8 = new UTF8Encoding(); Byte[] encodedBytes = utf8.GetBytes(sChaine); byte[] shaResult; HMAC hmac = new HMAC.Create("HMACSHA256"); var key = "YourSecretKey"; hmac.Key = utf8.GetBytes(key); hmac.Initialize(); shaResult = hmac.ComputeHash(encodedBytes); lblHEX.Text = ByteArrayToHEX(shaResult); } private string ByteArrayToHEX(byte[] ba) { StringBuilder hex = new StringBuilder(ba.Length * 2); foreach (byte b in ba) hex.AppendFormat("{0:x2}", b); return hex.ToString(); } } }
Exemples de code Sha256
- Exemple d’encodage Sha256 en Php 5
<?php
echo hash('sha256', $data.$secretKey);
?> Le jeu de caractères UTF-8 doit être utilisé pour les données Data et secretKey. Pour effectuer une conversion de ISO-8859-1 à UTF-8, faites appel à la fonction utf8_encode.
- Exemple d’encodage Sha256 en Java
import java.security.MessageDigest;
public class ExampleSHA256 {
/**
* table to convert a nibble to a hex char.
*/
static final char[] hexChar = {
'0' , '1' , '2' , '3' ,
'4' , '5' , '6' , '7' ,
'8' , '9' , 'a' , 'b' ,
'c' , 'd' , 'e' , 'f'};
/**
* Fast convert a byte array to a hex string
* with possible leading zero.
* @param b array of bytes to convert to string
* @return hex representation, two chars per byte.
*/
public static String encodeHexString ( byte[] b )
{
StringBuffer sb = new StringBuffer( b.length * 2 );
for ( int i=0; i<b.length; i++ )
{
// look up high nibble char
sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );
// look up low nibble char
sb.append( hexChar [b[i] & 0x0f] );
}
return sb.toString();
}
/**
* Computes the seal
* @param Data the parameters to cipher
* @param secretKey the secret key to append to the parameters
* @return hex representation of the seal, two chars per byte.
*/
public static String computeSeal(String Data, String secretKey) throws Exception
{
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update((Data+secretKey).getBytes("UTF-8"));
return encodeHexString(md.digest());
}
/**
* @param args
*/
public static void main(String[] args) {
try {
System.out.println (computeSeal("parameters", "key"));
} catch (Exception e) {
e.printStackTrace();
}
}
}- Exemple d’encodage Sha256 en .NET
Exemple complété à l’aide d’un simple formulaire appelé « Form 1 » contenant deux champs de texte à renseigner : data, txtSecretKey et un autre à afficher : lblHEX.
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using System.Security.Cryptography;
namespace ExampleDotNET
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void cmdGO_Click(object sender, EventArgs e)
{
String sChaine = data.Text + txtSecretKey.Text;
UTF8Encoding utf8 = new UTF8Encoding();
Byte[] encodedBytes = utf8.GetBytes(sChaine);
byte[] shaResult;
SHA256 shaM = new SHA256Managed();
shaResult = shaM.ComputeHash(encodedBytes);
lblHEX.Text = ByteArrayToHEX(shaResult);
}
private string ByteArrayToHEX(byte[] ba)
{
StringBuilder hex = new StringBuilder(ba.Length * 2);
foreach (byte b in ba)
hex.AppendFormat("{0:x2}", b);
return hex.ToString();
}
}
}Envoyer la requête à Sherlock's
La demande de paiement est une requête HTTPS POST adressée à Sherlock’s Paypage POST.
Exemple de requête dans le formulaire Web (Data non encodé. Les champs optionnels sealAlgotrihm et encode ne sont pas renseignés).
Traitement des erreurs
Voici une liste des erreurs que vous pourriez rencontrer et les messages pour chacun de ces cas. Si l’erreur persiste, contactez l’assistance.
| Etat | Exemple de message d’erreur | Action à réaliser |
|---|---|---|
| MerchantId inexistant | Merchant ID (merchantId) not found : findMerchantPoi [220555555550002] is not found [5c62b84e3ae83d] | Vérifiez le merchantId utilisé avec celui retourné par Sherlock's après l’inscription. |
| Algorithme de seal incorrect | Invalid field value : Invalid sealAlgorithm value (SHA-257) [609eac90a8ee1e]] | Vérifiez l’algorithme seal utilisé (champ seal) |
| Erreur clé secrète | Invalid signature : rge7gesgd86g556dgv4r89g4d6 [609aec21985569] | La signature calculée par Sherlock's à la
réception de la requête n’est pas identique à celle que vous avez
envoyée.
|
| Version de clé invalide | Invalid field value : Unable to find a valid key for the following keyVersion=0 [609aec2b60b1d0] | Sherlock's ne trouve pas la version de clé
que vous indiquez (champ keyVersion).
|
| Champ Encode incorrect | Invalid keyword : ENCODE [609aecdee11d52] | Vérifiez que l’algorithme de l’encodage que vous utilisez est correctement renseigné dans le champ encode. |
| URL de retour incorrecte | Technical problem : code=30 message=normalReturnUrl is invalid https:// [609aec31b00b94] | Vérifiez la syntaxe de l’URL que vous indiquez dans le champ normaReturnUrl |
Traiter la réponse de paiement
Une fois le paiement terminé :
- Sherlock's affiche le ticket de caisse
- Une réponse automatique vous est envoyée à l’URL contenue dans le champ autoResponseUrl de la requête (optionnel mais fortement conseillé).
- Sherlock's invite le client à revenir sur votre site grâce à l’URL renseignée dans le champ normalReturnUrl de la requête. L'action faite par le client déclenche l'envoi d'une réponse manuelle.
Ces quatre champs sont retournés par Sherlock's dans les réponses (automatique et manuelle) :
| Champs | Description |
|---|---|
| Data | Contient les champs de réponse. Respecte la même syntaxe que le champ Data de la requête de paiement. |
| Encode | Type d’encodage utilisé. S’il vaut base64 ou base64url, le champ Data doit être décodé en Base64/Base64Url pour retrouver la chaîne des champs concaténés. |
| Seal | Signature du champ Data qui permet de garantir la sécurité de la réponse de paiement. |
| InterfaceVersion | Valeur et numéro de version de l’interface utilisée. |
Vérifier la sécurité de la réponse
Tout d’abord vous devez vérifier la sécurité du message retourné en recalculant le Seal selon la même méthode que celle utilisée pour la requête. Ensuite, comparez le champ Seal calculé avec celui de la réponse Sherlock's.
Si les Seal sont identiques, vous poursuivez en traitant la réponse de paiement contenue dans le champ Data.
Dans le cas contraire, vous devez stopper le traitement: vérifier la clé secrète et/ou l’algorithme utilisés et si besoin contacter le support technique.
Analyser la réponse de paiement
La réponse de paiement contenue dans le champ Data est composée :
- Champs génériques
| Champs | Format | Description |
|---|---|---|
| amount | N12 | Montant de la transaction. Le montant est transmis dans la plus petite unité de la devise. Exemple pour l’Euro : un montant de 10,50 Euros doit être transmis sous la forme 1050. |
| currencyCode | N3 (restricted value / ISO4217) | Code de la devise de la transaction. Ce code est compatible ISO 4217. |
| customerId | AN19 (restrictedString) | Identifiant du client |
| customerEmail | ANS128 (email) | E-mail du contact |
| transactionReference | AN35 | Identifiant unique de la transaction par commerçant. |
| guaranteeIndicator | A1 (restricted values) | Niveau de garantie de la transaction (tableau des valeurs ci-dessous). |
| orderId | ANS32 | Numéro de commande associé à la transaction de paiement |
| responseCode | N2 (restricted values) | Code réponse du serveur Sherlock's (tableau des valeurs ci-dessous). |
| acquirerResponseCode | AN2 (restricted values) | Code réponse retourné par l’acquéreur lors d’une demande d’autorisation (tableau des valeurs ci-dessous). |
| authorisationId | AN10/ANS32 | Identifiant d’autorisation, retourné par le serveur d’autorisation de la banque du client en cas d’accord (non renseigné en cas de refus). |
| maskedPAN | ANS19 | Numéro de PAN masqué. |
| panExpiryDate | N6 (YYYYMM) | Date d'expiration du PAN. |
| paymentMeanBrand | ANS20 (restricted values) | Nom du moyen de paiement utilisé par le client. Valeurs :
|
| returnContext | ANSU255 (extendedString) | Contexte de la commande transmis dans la requête de paiement et restitué sans modification dans la réponse et le journal des transactions. |
- Champs si paiement carte
| Champs | Format | Description |
|---|---|---|
| holderAuthenStatus | ANS20 (restricted values) | Résultat du processus d’authentification porteur (tableau des valeurs ci-dessous). |
| cardProductCode | AN5 | Code produit de la carte. |
| cardProductName | ANS70 | Libellé du code produit de la carte. |
| issuerCode | AN6 | Code émetteur de la carte |
| issuerCountryCode | A3 (restricted values) | Code pays de l’émetteur de la carte |
| issuingCountryCode | A3 (restricted values) | Code pays dans lequel la carte est émise |
Champs si paiement PayPal
pas de champ spécifique- Valeurs des champs à analyser
Le champ responseCode donne le résultat de l’acceptation.
La valeur 00 dans le champ responseCode signifie que le paiement est accepté.
En cas de refus (responseCode différent de 00), le champ acquirerResponseCode précise la nature du refus de la banque (si paiement carte) ou du serveur PayPal (si paiement PayPal).
| responseCode | Description | Type refus |
|---|---|---|
| 00 | Transaction acceptée | |
| 05 | Transaction refusée | Bancaire |
| 34 | Suspicion de fraude (seal erroné) | Fraude |
| 75 | Nombre maximum de tentatives atteint | Moyen de paiement |
| 90 | Service temporairement indisponible | Technique |
| 97 | Session expirée (aucune action de l'utilisateur pendant 15 min), transaction refusée | Technique |
| 99 | Problème temporaire au niveau du serveur Sherlock's | Technique |
| holderAuthentStatus | Description | Valeur 3-D |
|---|---|---|
| ATTEMPT | Le client n’a pas eu à s’authentifier. | 3D_ATTEMPT |
| CANCEL | Le client a abandonné durant l'authentification. | 3D_ABORT |
| ERROR | Problème technique lors de l’authentification 3DS. | 3D_ERROR |
| FAILURE | Le client n’a pas réussi à s’authentifier (erreur de mot de passe). | 3D_FAILURE |
| NOT_ENROLLED | La carte utilisée n’est pas enrôlée 3-D Secure. | 3D_NOTENROLLED |
| NOT_PARTICIPATING | Le client ne s’est pas authentifié car :
|
SSL |
| SUCCESS | Le porteur de la carte s’est authentifié correctement. | 3D_SUCCESS |
| guaranteeIndicator | Description |
|---|---|
| Y | Paiement 3D garanti |
| N | Paiement 3D non garanti |
| U | Garantie 3D non définie |
| Paiement non 3D |
| acquirerResponseCode | Description | Correspondance responseCode |
|---|---|---|
| 00 | Transaction approuvée ou traitée avec succès | 00 |
| 02 | Contacter l'émetteur du moyen de paiement | 02 |
| 03 | Accepteur invalide | 03 |
| 04 | Conserver le support du moyen de paiement | 05 |
| 05 | Ne pas honorer | 05 |
| 07 | Conserver le support du moyen de paiement, conditions spéciales | 05 |
| 08 | Approuver après l'identification | 05 |
| 12 | Transaction invalide | 12 |
| 13 | Montant invalide | 05 |
| 14 | Coordonnées du moyen de paiement invalides | 14 |
| 15 | Émetteur du moyen de paiement inconnu | 05 |
| 17 | Paiement interrompu par le client | 17 |
| 24 | Opération impossible | 05 |
| 25 | Transaction inconnue | 05 |
| 30 | Erreur de format | 30 |
| 31 | Id de l'organisation d'acquisition inconnu | 05 |
| 33 | Moyen de paiement expiré | 05 |
| 34 | Suspicion de fraude | 34 |
| 40 | Fonction non supportée | 05 |
| 41 | Moyen de paiement perdu | 05 |
| 43 | Moyen de paiement volé | 34 |
| 51 | Provision insuffisante ou crédit dépassé | 05 |
| 54 | Moyen de paiement expiré | 05 |
| 56 | Moyen de paiement manquant dans le fichier | 05 |
| 57 | Transaction non autorisée pour ce porteur | 05 |
| 58 | Transaction interdite au terminal | 05 |
| 59 | Suspicion de fraude | 05 |
| 60 | L'accepteur du moyen de paiement doit contacter l'acquéreur | 05 |
| 61 | Excède le maximum autorisé | 05 |
| 62 | Transaction en attente de confirmation de paiement | 05 |
| 63 | Règles de sécurité non respectées | 05 |
| 65 | Nombre de transactions du jour dépassé | 05 |
| 68 | Réponse non parvenue ou reçue trop tard | 05 |
| 75 | Nombre de tentatives de saisie des coordonnées du moyen de paiement dépassé | 75 |
| 87 | Terminal inconnu | 05 |
| 90 | Arrêt momentané du système | 90 |
| 91 | Emetteur du moyen de paiement inaccessible | 90 |
| 92 | La transaction ne contient pas les informations suffisantes pour être redirigée vers l'organisme d'autorisation Transaction dupliquée | 90 |
| 94 | Transaction dupliquée | 90 |
| 96 | Mauvais fonctionnement du système | 90 |
| 97 | Requête expirée: transaction refusée | 90 |
| 98 | Serveur inaccessible | 90 |
| 99 | Incident technique | 99 |
| A1 | Paiement refusé par l'acquéreur (données 3-D Secure manquantes dans la demande d'autorisation). | 05 |
Traitement de la réponse
| Etat | Champs de la réponse | Action à réaliser |
|---|---|---|
| Paiement 3-D Secure accepté | responseCode = 00 acquirerResponseCode = 00 garanteeIndicator = Y,N,U, vide |
Vous pouvez livrer la commande en fonction du niveau de garantie que vous souhaitez (champ garanteeIndicator). |
| Refus 3-D Secure | reponseCode = 05 holderAuthenStatus = FAILURE |
L’authentification du client a échoué, ce n’est pas nécessairement un cas de fraude. Vous pouvez proposer à votre client de payer avec autre moyen de paiement en générant une nouvelle requête. |
| Refus bancaire | responseCode = 05 | L’autorisation est refusée pour un motif non lié à la fraude. Vous pouvez proposer à votre client de payer avec un autre moyen de paiement en générant une nouvelle requête. |
| Repli VADS | responseCode = 05 acquirerResponseCode = A1 |
Le paiement a été refusé par l'acquéreur car il manque les
données 3-D Secure dans la demande d'autorisation. Veuillez
retenter le paiement avec une cinématique
3-D Secure. |
| Refus fraude | responseCode = 34 | Autorisation refusée pour cause de fraude. Ne livrez pas la commande. |
| Refus nombre max d’essais atteint | responseCode = 75 | Le client a fait plusieurs tentatives toutes échouées car
les informations saisies n’étaient pas correctes. Deux
possibilités :
Prenez contact avec votre client pour définir avec lui
la suite à donner. |
| Refus suite problème technique | responseCode = 90, 99 acquirerResponseCode = 90 à 98 |
Problème technique temporaire lors du traitement de la transaction. Proposez à votre client de refaire un paiement ultérieurement. |
Etape 3 : Tester la connexion à Sherlock’s Paypage
Une fois le développement de la connexion à Sherlock’s Paypage réalisé, vous pouvez effectuer un test sur le serveur de simulation Sherlock’s Paypage.
Pour effectuer ce test, il faut utiliser les identifiants suivants :
| URL | https://sherlocks-payment-webinit-simu.secure.lcl.fr/paymentInit |
| ID du commerçant (merchantId) | 002016000000001 |
| Clé secrète (secretKey) | 002016000000001_KEY1 |
| Version de la clé (keyVersion) | 1 |
Ce serveur de simulation n’est pas raccordé aux serveurs bancaires réels car sa fonction est de valider la connexion entre votre site Web et le serveur de paiement.
Sherlock’s Paypage simule donc l’appel aux serveurs d’autorisation pour vous permettre de tester les différents résultats d’un paiement.
Il n’est donc pas nécessaire d’utiliser des cartes réelles pour effectuer les tests.
Tester des transactions CB, VISA, MASTERCARD
- Le numéro de carte (PAN) doit comporter de 16 à 19 chiffres
- Les six premiers chiffres du PAN déterminent le type de carte,
conformément au tableau ci-dessous :
Type de carte Début du numéro de carte VPAY 400000 VISA 410000 CB 420000 Cartes co-badgées CB et VISA 430000 Cartes co-badgées CB et VPAY 440000 Cartes co-badgées CB et VISA_ELECTRON 450000 Cartes co-badgées VISA et MASTERCARD 460000 MAESTRO 500000 MASTERCARD 510000 Cartes co-badgées CB et MASTERCARD 520000 Cartes co-badgées CB et MAESTRO 530000 - Le code réponse Sherlock's (champ responseCode) est calculé à partir des deux derniers chiffres du numéro de carte.
- Le code de sécurité (CVV) comporte 3 ou 4 chiffres. Cette valeur est sans importance pour le résultat de la simulation.
Exemple : Si vous utilisez le numéro de carte 4100 0000 0000 0005, la carte sera identifiée comme VISA et le paiement sera refusé (code réponse Sherlock's 05).
Les cartes co-badgées peuvent être utilisées avec chacune des marques définies dans le tableau.
Toutes les cartes sont enrôlées 3-D Secure, vous êtes redirigé vers le serveur de simulation 3-D Secure sur lequel vous choisissez le résultat désiré de l’authentification 3-D Secure.
Tester des transactions PayPal
Si vous choisissez de tester PayPal, vous êtes redirigé vers le serveur de simulation qui simule les transactions PayPal selon leur résultat du paiement chez PayPal. Ensuite, vous retournez au serveur de paiement qui affiche le ticket avec le résultat du paiement.
Etape 4 : Valider la connexion en production
Une fois la connexion de votre site Web à testée, vous êtes à présent en mesure de valider la connexion à Sherlock’s Paypage POST de production.
Pour ce faire, 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 | https://sherlocks-payment-webinit.secure.lcl.fr/paymentInit |
| merchantId | Identifiant de la boutique reçu par mail |
| secretKey | Clé secrète que vous récupérez via 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é) |
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.
Comment valider le bon fonctionnement en production
Immédiatement :
- faites une transaction avec une carte de paiement réelle (si possible la vôtre). Si la transaction est acceptée, elle sera envoyée en banque pour créditer votre compte commerçant et débiter le compte carte ;
- vérifiez que vos pages de paiement intègrent vos paramètres de personnalisation ;
- consultez la transaction via Sherlock's Gestion à partir du transactionReference.
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é créditée ;
- remboursez la transaction via Sherlock's Gestion (optionnel).
Le surlendemain :
- vérifiez que l’opération de remboursement apparaît dans le journal des opérations ;
- vérifiez sur votre compte le débit suite au remboursement.
Cette procédure de validation est également applicable au moyen de paiement PayPal.
Étape 5 : démarrer en production
Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos clients d’acheter et de payer.
Dans la journée :
- 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, 99 ;
- fraude : responseCode 34 ;
- nombre maximum de tentatives de paiement atteint : responseCode 75 ;
- abandon : responseCode 97.
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, les opérations que vous avez effectuées ainsi que les remises (si vous avez choisi cette option du journal).
Annexes
Créer votre compte PayPal
Afin d'utiliser le moyen de paiement PayPal sur votre site Web, vous devez posséder un compte PayPal. Il doit s'agir d'un compte professionnel (le type du compte est choisi lorsque vous vous enregistrez sur http://www.PayPal.com).
Si vous avez plusieurs boutiques actives, nous vous suggérons de créer un compte PayPal pour chacune.
Paramétrer son compte PayPal
Sur votre compte PayPal, vous devez, en tant que commerçant, autoriser le prestataire de services de paiement (PSP) à appeler l'API de PayPal.
Dans votre compte d'entreprise PayPal, allez dans Paramètres du compte, puis Accès à l'API :
Cliquez sur le lien Solution de paiement pré-intégrée.
La fenêtre Ajouter de nouveaux droits d'accès à un tiers s'ouvre. Dans le champ textuel, entrez le compte technique Sherlock's sips-gestion-services_api1.worldline.com puis cliquez sur Rechercher.
Sélectionnez les options suivantes :
- Utiliser Express Checkout pour traiter les paiements ;
- Émettre un remboursement pour une transaction spécifique ;
- Traiter les paiements par carte bancaire de vos clients;
- Autoriser et collecter vos transactions PayPal ;
- Obtenir des informations concernant une transaction en particulier ;
- Rechercher dans vos transactions les éléments correspondant à des critères spécifiques ;
- Obtenir une autorisation pour les paiements préapprouvés et initier des transactions préapprouvées ;
- Utiliser Express Checkout pour traiter les paiements par mobiles.
Cliquez ensuite sur le bouton Ajouter.
Si vous souhaitez dupliquer des transactions, vous devez également sélectionner l'option "Débiter un client sur la base d'une transaction antérieure".
Clé secrète
Télécharger la clé secrète
Afin d'accéder à l'interface Sherlock’s Téléchargement, vous devez au préalable vous connecter au portail Portail Sherlock's via l'URL : https://sherlocks-extranet.secure.lcl.fr avec l'identifiant qui vous a été retourné par Sherlock's lors de l’inscription de votre boutique .
Si vous avez un utilisateur permettant d'accéder à plusieurs boutiques, l'onglet "Téléchargement" permettant d'accéder à Sherlock’s Téléchargement est grisé. Pour l'activer, vous devez sélectionner une boutique.
Ensuite allez dans l’onglet "Téléchargement" puis "Gestion des clés" :
Vous pouvez télécharger votre clé secrète :
Pour plus de détails sur la gestion des clés secrètes, veuillez consulter la documentation Gestion des clés".
Réglementation des paiements
La solution Sherlock's est conforme à la règlementation en vigueur définie par CB, Visa et Mastercard.
La sécurisation des paiements (PCI)
PCI DSS est un standard de sécurité international dont les objectifs sont d’assurer la confidentialité et l’intégrité des données des porteurs de cartes, et ainsi de sécuriser la protection des données carte et des transactions. Vous et les prestataires de paiement sont tenus de s’y conformer, à des degrés divers en fonction de l’importance de leur activité. La solution Sherlock's est certifiée PCI DSS depuis 2006.
En utilisant Sherlock’s Paypage, vous n’avez pas accès aux données du porteur de carte et n’avez pas besoin d’être certifié PCI DSS. Les données carte sont gérées par LCL.
Le choix de la marque lors du paiement (MIF)
La solution Sherlock's 2.0 est soumise à la réglementation européenne MIF (JO EU 2015/751 L123 du 19/05/2015). Parmi ces règles, la « sélection de la marque » vous impose de proposer au client porteur d’une carte cobadgée le choix de la marque au moment du paiement, ce qui impacte la page de paiement.
Une carte cobadgée est une carte qui supporte au moins deux marques. La plupart des cartes émises en France sont cobadgées avec CB (carte CB/VISA, CB/MASTERCARD, CB/MAESTRO…).
Ainsi vous devez laisser le choix de la marque au client porteur de ces cartes cobadgées. À titre d’illustration, l’écran ci-dessous présente un exemple de carte cobadgée CB + Visa avec CB en marque par défaut. Le client peut changer la marque en cliquant sur le lien en bas de l’écran.
Pour en savoir plus
Si vous souhaitez implémenter d’autres moyens de paiement ou options, veuillez-vous référer aux documentations associées.
Cette liste n’est pas exhaustive mais vous présente les documents complémentaires pour vous aider à aller plus loin dans la mise en œuvre de Sherlock's.
| Guide | Pourquoi le lire ? |
|---|---|
| Dictionnaire des données | Ce guide vous permet de connaître la définition et l’ensemble de valeurs des champs des connecteurs et journaux. |
| Présentation fonctionnelle | Ce guide vous permet d’avoir une vue d’ensemble des fonctionnalités de Sherlock's et des options disponibles auxquelles vous pouvez souscrire. |
| Guide de configuration des fonctionnalités | Ce guide vous explique la mise en œuvre des fonctionnalités Sherlock's. |
| Description des journaux | Ce guide décrit le contenu des journaux envoyés par Sherlock's. |
| Personnalisation de Sherlock’s Paypage pour les boutiques | Ce guide vous explique comment personnaliser les pages de paiement afin qu’elles aient une charte graphique similaire au reste de votre site. |
| OneClick | Ce guide décrit la solution OneClick qui permet à vos clients de payer en un clic sans avoir à ressaisir leurs données cartes. |
| Sherlock's Message | Ce guide explique comment implémenter la solution Sherlock's message qui vous permet d’envoyer à vos clients une notification de paiement par mail ou par SMS . |
| Sherlock’s Téléchargement | Ce guide explique comment télécharger la documentation et votre clé secrète via l’extranet Sherlock’s Téléchargement. |
| Sherlock's Gestion | Ce guide décrit l’ensemble des actions de gestion de caisse que vous pouvez effectuer via Sherlock's Gestion. |
| Gestion de la lutte contre la fraude – Go-no-Go | Ce guide explique le fonctionnement, la configuration et l’utilisation du moteur de lutte contre la fraude Go-No-Go. Il vous permet de définir les règles d’acceptation fraude que vous souhaitez mettre en place lors du paiement. |
| Sherlock’s Paypage POST | Ce guide décrit et explique comment implémenter l’intégralité des options du connecteur . |
| Intégration American Express | Ce guide vous explique comment intégrer les cartes American Express. |
