Introduction

WL Sips 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 Sips CSE jusqu’au démarrage en production.

Objectif de ce document

L’objectif du présent document est d’expliquer la mise en œuvre de la solution de chiffrement côté client (CSE) jusqu’au démarrage en production.

Le chiffrement côté client est une fonctionnalité qui vous permet de chiffrer les informations de paiements sensibles (numéro de carte et code csc) et de les traiter par la passerelle de paiement Sips Office .

Cette fonctionnalité vous permettra de réduire les contrainte PCI et ainsi n’être soumis qu’aux impacts de type SAQ A-EP (cf : https://www.pcisecuritystandards.org/pci_security/completing_self_assessment)

A qui s'adresse ce document ?

Ce document s’adresse aux commerçants qui souhaitent souscrire à l’offre WL Sips en réduisant leurs contraintes PCI DSS. Le chiffrement coté client permet d'héberger les pages chez le commerçant sans que les données cartes ne transitent en clair.

Pour avoir une vue d'ensemble de la solution WL Sips , nous vous conseillons de consulter les documents suivants

  • Présentation fonctionnelle.
  • Guide de configuration des fonctionnalités.

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 à Sips CSE .

Note: toutes les portions de code de ce document sont fournies à titre d’exemple, il convient de les adapter à votre site Web afin qu’elles soient pleinement exploitables.

Gestion de la clé secrète

Lors de votre inscription, Worldline met à disposition sur Sips Download (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 WL Sips .

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).

IMPORTANT: en cas de compromission d’une clé secrète, vous êtes tenu d’en demander au plus vite la révocation puis le renouvellement via Sips Download (voir l'annexe « Révocation et demande de renouvellement de la clé secrète » du guide de démarrage rapide).

C’est la même clé secrète qui est utilisée sur les différents connecteurs Sips Paypage , Sips Office , Sips In-App et Sips Walletpage .

IMPORTANT: une clé secrète est associée à une version. Après avoir obtenu une nouvelle clé secrète, vous devez impérativement modifier votre requête et indiquer la nouvelle version dans le champ keyVersion , sans quoi vous obtiendrez un code réponse 34 (suspicion de fraude).

Gestion de la clé CSE

La fonctionnalité WL Sips Client Side Encryption requiert l’utilisation d’une clé de chiffrement. De la même manière que la clé Secrète, la clé CSE est mise à disposition sur l’extranet Sips Download .

Comprendre le paiement avec Client Side Encryption

Le chiffrement côté client consiste en une bibliothèque JavaScript intégrée à votre page de paiement. Elle chiffre les données sensibles avant que le formulaire Web ne soit soumis à votre serveur.

Les données chiffrées obtenues sont ensuite utilisées pour appeler les services de paiement par carte Sips Office pour traitement.

La fonctionnalité CSE offre les avantages suivants:

  • Les clients ne sont pas obligés d'être redirigés vers une page hébergée chez WL Sips ( Sips Paypage )
  • Les impacts PCI sont réduits car aucune donnée sensible ne passe en clair sur votre serveur.

1. Le formulaire permettant de saisir les informations relatives de paiement inclus la librairie Java Script CSE ainsi que la clé publique. Les données de carte sont interceptées par la librairie et chiffrées grâce à la clé.

2. Le marchand enregistre les détails du paiement.

3. Vous envoyez les informations relatives au paiement vers le serveur de paiement WL Sips pour qu’il prenne en charge la transaction.

4. Les serveurs WL Sips déchiffrent les données en récupérant la clé privé CSE et effectue le paiement.

5. Le serveur envoie une réponse pour que vous puissiez afficher le résultat du paiement.

Implémenter Client Side Encryption en 4 étapes

IMPORTANT: l’implémentation de CSE est une option supplémentaire du mode Sips Office (SOAP/JSON).

Pour compendre comment démarrer avec Sips Office , merci de vous reporter à la documentation dédiée.

Le mode CSE est disponible pour les fonctions cardOrder , cardCheckEnrolment , addCard lorsque le champ panType est positionné à CSE et pour walletOrder , walletCheckEnrolment lorsque le champ cscType est positionné à CSE .

Inclure la librairie SDPX CSE

Pour utiliser le mode CSE, il vous faut inclure la librairie de chiffrement WL Sips dans la balise <head> de votre page de paiement.

Il y a deux façons de procéder:

  1. Chargement standard JavaScript
          
    <script type="text/javascript" src="      
            https://office-server.sips-atos.com
          
    /scripts/cse/latest/sdpx.encrypt.js"></script>
        
  2. Chargement avec le module AMD

    La librairie de chiffrement SDPX est compatible avec AMD et peut être utilisée avec tout module AMD ou librairie telle que RequireJS.

    RequireJS recommande d’inclure votre script de cette façon :

          
    <script data-main="scripts/main" src="scripts/require.js"></script>
        

    Cela garantit un seul point d'entrée pour votre application, car le data-main du script que vous spécifiez sera chargé de manière asynchrone.

    Ensuite, dans main.js , vous pouvez utiliser la fonction require pour charger la bibliothèque de chiffrement SDPX.

          
    <script>
    require(['      
            https://office-server.sips-atos.com
          
    /scripts/cse/latest/sdpx.encrypt.js'], function(sdpx) {
      // ...
    });
    </script>
        

    Dans l'exemple ci-dessus, le premier paramètre de la fonction require est un tableau de modules dépendants pour votre application. Le nom du module (i.e scripts/sdpx.encrypt représente le nom du fichier JS sans l’extension).

    Si vous le souhaitez, vous pouvez configurer RequireJS pour qu’il mappe le chemin par souci de commodité:

          
    <script>
        requirejs.config({
        baseUrl: './',
        paths: {
          'sdpx.encrypt': '      
            https://office-server.sips-atos.com
          
    /scripts/cse/latest/sdpx.encrypt'
        }
      });
      require(['sdpx.encrypt'], function(sdpx) {
        // ...
      });
    </script>
        

Implémenter le formulaire HTML de paiement

Créez un formulaire de paiement et marquez les champs sensibles avec la balise sdpx-encrypted :
      
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Merchant payment page</title>
  </head>
  <body>
    <form id="payment-form">
      <input type="text" id="card-number" sdpx-encrypted />
      <input type="text" id="card-expiry-month" />
      <input type="text" id="card-expiry-year" />
      <input type="text" id="card-csc-value" sdpx-encrypted />
      <input type="submit" value="Checkout"/>
    </form>
  </body>
</html>

    
Tip: quels champs chiffrer ?

Actuellement, les services de paiement par carte Sips Office prennent en charge le chiffrement pour le numéro de carte et le code CSC.

Lier l'évènement de validation du formulaire de paiement à la bibliothèque CSE

      
<script>
var paymentFormId = 'payment-form';
var merchantCseKeyValue = '00CE1A815AA0E970EB6E70...9434E9578F000308AD1E1B|010001'; 
var merchantCseKeyVersion = '2';

var paymentForm = sdpx.encrypt.onSubmitEncryptForm(paymentFormId, merchantCseKeyValue, merchantCseKeyVersion);
</script>
    

onSubmitEncryptForm doit être appelée après le chargement de la page.

Cela signifie que le script ci-dessus doit être inséré à la fin de la section <body> ou différé en utilisant, soit la propriété onload sur l'élément <body>, soit l’ajout d'un listener pour détecter la fin du chargement du DOM de la page (voir DOMContentLoaded et readystatechange ).

      
document.onreadystatechange = function () {
  if (document.readyState === "interactive") {
    var paymentForm = sdpx.encrypt.onSubmitEncryptForm(paymentFormId, merchantCseKeyValue, merchantCseKeyVersion);
  }
}
    

Tester sur l’environnement de recette client

Les étapes de test et d'intégration peuvent être réalisées à l’aide de l'environnement de recette.

L’URL de l’environnement de recette est : https://office-server.test.sips-atos.com

Pour effectuer ce test, il faut utiliser ces identifiants :

ID du Commerçant 201040040170001
Version de la clé sécrète 1
Clé sécrète rxSP61eeP_oNi5TxCD7Ngy9YcwC8MLw6OlmFGGcsY54
Version de la clé CSE 2
Clé CSE 00CE1A815AA0E970EB6E709CD0E19B3B758E474183AAA 53632A9CC3333DB3C1C2073AB6CD64F00AE9B2DC0EB25 63D802BDF1F9C127274DDDEA1CDF2739323D7F5D04BB5 319B6AAB75E47639E6CB59A709C7B4107C134F197ED74 6DEFE7B97AB76E4625296D901E69D0E9BAC97AEDA4BA1 A4253961B5BB3B708E941DB76FFCECA5D0B9271F024B5 8E7EC2B50ADB7D8B040502C2B89EDD48FED8F55D0CA6C 4A00A78C168BFEDD33E9B3354B294CD55CC9C4649F3AC 19EFFFCB52B487DC3B0756BF3617C7C7ED552471B734A 2C4B285A2A9AC18C2BFFC007377C9C861C9880E6EA1D3 0E87548E15950A6921D0C8A6C8BE83D13DB4E275A9943 4E9578F000308AD1E1B|010001

Usage avancé

Activation de la validation des champs

La bibliothèque SDPX CSE peut être utilisée pour valider des champs côté client. Par défaut, cette fonctionnalité n'est pas activée, mais elle peut être utile car les champs chiffrés ne peuvent être validés côté serveur.

Pour activer la validation des champs côté client, un tableau contenant les définitions des champs à valider peut être ajouté à l'objet renvoyé par la fonction onSubmitEncryptForm . Une entrée du tableau est une structure JSON avec les propriétés suivantes:

Propriété Obligatoire Description
id oui Id de l’élément HTML à valider
validator oui Référence du validateur par défaut ou fonction personnalisée utilisée pour valider la valeur du champ
onSuccess non Fonction de rappel invoquée lorsque la valeur du champ a été validée avec succès
onError non Fonction de rappel invoquée lorsque la valeur du champ n'a pas été validée avec succès
      
<script>
var paymentForm = sdpx.encrypt.onSubmitEncryptForm(paymentForm, merchantCseKeyValue, merchantCseKeyVersion);

var fieldValidationDefs = [
            { id: 'card-number', validator: '@CardNumber', onSuccess: successValidationHandler, onError: errorValidationHandler },
            { id: 'card-csc-value', validator: '@CscValue', onSuccess: successValidationHandler, onError: errorValidationHandler },
            { id: 'card-expiry-month', validator: '@ExpiryMonth', onSuccess: successValidationHandler, onError: errorValidationHandler },
            { id: 'card-expiry-year', validator: '@ExpiryYear', onSuccess: successValidationHandler, onError: errorValidationHandler }

            /*
            // Custom validator example:
            { id: 'card-expiry', validator: customCardExpiryValidator, onSuccess: successValidationHandler, onError: errorValidationHandler }
            */
        ];
paymentForm.setValidations(fieldValidationDefs);

/**
 * Custom validator example: check the card expiry value (format 'mm/yyyy')
 *
 * @param {value} the HTML input element value to validate
 * @return {boolean} true if the value is valid, false otherwise
 */
function customCardExpiryValidator(val) {
  // Validate the card expiry value
  return /^[0-9]{2}\/[0-9]{4}$/.test(val);
}

/**
 * Handle success validation
 *
 * @param {element} the HTML element that has been successfully validated
 * @return {void}
 */
function successValidationHandler(element) {
  // Do sthg if needed
}

/**
 * Handle error validation
 *
 * @param {Error} a JSON object containing error information
 * @return {void}
 */
function errorValidationHandler(error) {
  // Handle error
}
</script>
    

Validateur de champ par défaut

Reference Description Code source
@CardNumber Vérifie que le numéro de carte est compris entre 6 et 19 chiffres return /^[0-9]{6,19}$/.test(val);
@CscValue Vérifie que le code csc est compris entre 3 et 4 chiffres return /^[0-9]{3,4}$/.test(val);
@ExpiryMonth Vérifie que le mois est compris entre 1 et 12. return /^[0-9]{2}$/.test(val) && (val > 0) && (val <= 12);
@ExpiryYear Verifie que l'année est valide return /^[0-9]{4}$/.test(val) && (val >= (new Date()).getFullYear());

Rappel de la structure de l'objet JSON

Reference Description Exemple
message Message d’erreur ('is invalid!') card-number is invalid!
validator Nom de la référence du validateur ou de la fonction personnalisée utilisée pour la validation @CardNumber, customCardExpiryValidator, ...
element Elément HTML qui est validé HTMLElement
cause Objet d'erreur JavaScript décrivant l'échec de la validation Error:* Error('Validation returns false')* Error('No validator found for element [<field-id>]')

Gestion des erreurs

Par défaut, en cas d'incident lié à l'utilisation de la bibliothèque CSE, une erreur JavaScript est interceptée et la soumission du formulaire est annulée.

Pour être prévenu de l'erreur JavaScript, une fonction de rappel peut être fournie à l'objet renvoyé par la fonction onSubmitEncryptForm .

Tip: il est fortement recommandé d'implémenter une fonction de rappel pour gérer les erreurs. En faisant cela, vous pourrez informer l'utilisateur final que le paiement ne peut pas être effectué et vous pourrez envoyer des informations sur l'erreur sur votre serveur.
      
<script>
var paymentForm = sdpx.encrypt.onSubmitEncryptForm(paymentForm, merchantCseKeyValue, merchantCseKeyVersion);

paymentForm.setErrorHandler(errorHandler);

function errorHandler(error) {
  // Display an error message to the end user and send information to your server
}
</script>