Introduction

WL Sips is a secure multi-channel e-commerce payment solution that complies with the PCI DSS standard. It allows you to accept and manage payment transactions by taking into account business rules related to your activity (payment on dispatch, deferred payment, recurring payment, payment in instalments, …).

Document purpose

This document purpose is to explain the implementation of the Client Side Encryption solution until production starts.

Client Side Encryption functionally allows sensitive information (card number and csc code) to be encrypted and to process them throw Sips Office .

This functionality allow you to lower PCI requirement and therefore to only be subject to SAQ A-EP type impacts (see : https://www.pcisecuritystandards.org/pci_security/completing_self_assessment )

Who does this document target?

This document is intended for the merchants who want to integrate the WL Sips solution in a quick, simple way. Client Side Encryption allows to manage payment pages having data card that doesn't transit on your server and therefore lower the PCI requirement.

For an overview of the WL Sips solution, it's recommended to consult following documentation

  • Functional presentation.
  • Feature configuration guide.

Prerequisites

A good knowledge of one industry standard web programming language such as Java, PHP or .Net is required.

Note: all code sections in this document are provided as samples, you will need to adapt them to your website for them to be fully operable.

Secret key management

Upon your subscription, Worldline provides a secret key on the Sips Download extranet that will allow you to secure exchanges between your website and the WL Sips server.

You are responsible for looking after this key and should take all measures to:

  • Restrict access to the key
  • Safeguard it by encrypting it
  • Never copy it onto a non-secure disc or device
  • Never send it (via e-mail or regular mail) in a non-secure method.

A secret key compromised (and used by a malicious third party) might disrupt the regular operation of your shop and might in particular generate unauthorised sales or cash transactions (e.g. refunds).

IMPORTANT: in the event that a secret key is compromised, you are required to ask as quickly as possible for its revocation then for its renewal via the Sips Download extranet (please refer to the "Secret key revocation and renewal" section in the Quick start guide).

The very same secret key is used on the various Sips Paypage , Sips Office , Sips In-App and Sips Walletpage connectors.

IMPORTANT: a secret key is associated with a version. After getting a new secret key, you must modify your request and populate the keyVersion field with the new version, otherwise you will get an answer code 34 (suspected fraud).

CSE key managment

WL Sips Client Side Encryption require an encryption key. Like the Secret key, the CSE key is provided on the Sips Download extranet.

Contacting the support

For any technical question or request for assistance, our services are available:

  • by telephone at: +33 (0) 811 10 70 33
  • by e-mail: sips@worldline.com

In order to facilitate the processing of your requests, please provide your merchantId (15-digit number).

Understanding payment using Client Side Encryption

Client Side Encryption consists of Javascript library embedded on your payment page. It encrypts sensitive data before the web form is submitted to your server.

Encrypted data are then used to make a call to Sips Office card payment services in order to be processed

CSE functionality brings you following advantages:

  • It's not mandatory to redirect customers to an external payment page
  • PCI requirement is lowered since no plain sight sensitive data transits on your server.

1. The payment form included the CSE Javascript library and the public key. Card data are processed by the library and encrypt using the key.

2. The merchant collect payment details.

3. Payment data are sent to the card payment services to process the transaction.

4. Payment services decipher encrypted data using the CSE private key part and process the payment.

5. The service send a response to allows you to display the payment result.

Implementing Client Side Encryption in 4 steps

IMPORTANT:

Implementing CSE is an optional Sips Office (SOAP/JSON) feature.

In order to start with Sips Office , please refer to its dedicated documentation.

The CSE feature is available for cardOrder , cardCheckEnrolment , addCard functions when the panType field is set to CSE and for walletOrder , walletCheckEnrolment functions when the cscType field is set to CSE

Include SDPX CSE library

In order to use CSE functionality, you should include the WL Sips encryption library in the <head> tag of your payment page.

There are two ways to proceed:

  1. Standard JavaScript inclusion

          
    <script type="text/javascript" src="      
            https://office-server.sips-services.com
          
    /scripts/cse/latest/sdpx.encrypt.js"></script>
        

  2. Inclusion using the AMD module

    The encryption library is compatible with AMD and can be used with any AMD module or library like RequireJS.

    RequireJS recommend to include you script this way:

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

    This will guaranty you a single entry point for your application since the your script data-main will be load async

    Then, inside main.js , you can use the function require in order to load the encryption library.

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

    In the following example, the first require function parameter is an array of dependency modules needed for your applicaiton. The module name (i.e scripts/sdpx.encrypt ) represents the JS file without the filename extension.

    If wanted, you can configure RequireJS in order for it to map the path for practicalness:

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

Implement the payment HTML form

Create a payment form and tag field that need to be encrypted with 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: what fields should be encrypted?

Currently WL Sips card payment services support card number and csc code field.

Link the payment form validation event to the CSE library

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

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

onSubmitEncryptForm should be called after the page loading.

This means that the above script should be inserted at the end of the <body> section or differed using, either, the onload property on the <body> element, or a listener addition in order to detect the end of the DOM loading of the page (see DOMContentLoaded and readystatechange ).

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

Testing on the customer's test environment

The test and integration steps can be implemented using the test environment.

The URL for the test environment is: https://office-server.test.sips-services.com

The following IDs must be used to carry out this test:

Merchant ID 201040040170001
Secret key version 1
Secret key rxSP61eeP_oNi5TxCD7Ngy9YcwC8MLw6OlmFGGcsY54
CSE key version 2
CSE key 00CE1A815AA0E970EB6E709CD0E19B3B758E474183AAA 53632A9CC3333DB3C1C2073AB6CD64F00AE9B2DC0EB25 63D802BDF1F9C127274DDDEA1CDF2739323D7F5D04BB5 319B6AAB75E47639E6CB59A709C7B4107C134F197ED74 6DEFE7B97AB76E4625296D901E69D0E9BAC97AEDA4BA1 A4253961B5BB3B708E941DB76FFCECA5D0B9271F024B5 8E7EC2B50ADB7D8B040502C2B89EDD48FED8F55D0CA6C 4A00A78C168BFEDD33E9B3354B294CD55CC9C4649F3AC 19EFFFCB52B487DC3B0756BF3617C7C7ED552471B734A 2C4B285A2A9AC18C2BFFC007377C9C861C9880E6EA1D3 0E87548E15950A6921D0C8A6C8BE83D13DB4E275A9943 4E9578F000308AD1E1B|010001

Advanced implementation

Fields validation activation

The SDPX CSE library can be used to validate input fields on the client side. The functionality is not activated by default, but it can be useful since encrypted data can't by validated on your server.

In order to activate client side field validation an array including fields definition to be checked can be embedded within the object returning be the function onSubmitEncryptForm . An array cell is a JSON structure with the following properties:

Property Mandatory Description
id yes Id of the HTML to be checked
validator yes default validator or custom function to be used to check the field value
onSuccess no callback triggered on a successful field validation
onError no callback triggered on erroneous field validation

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

Default field validator

Reference Description Source code
@CardNumber Check that card number is between 6 and 19 digits return /^[0-9]{6,19}$/.test(val);
@CscValue Check that csc code is between 3 and 4 digits return /^[0-9]{3,4}$/.test(val);
@ExpiryMonth Check that the month is in range 1 to 12. return /^[0-9]{2}$/.test(val) && (val > 0) && (val <= 12);
@ExpiryYear Check to the year is valid return /^[0-9]{4}$/.test(val) && (val >= (new Date()).getFullYear());

JSON object description reminder

Reference Description Exemple
message error message('is invalid!') card-number is invalid!
validator validator reference or custom function name used to validation @CardNumber, customCardExpiryValidator, ...
element HTML element to be checked HTMLElement
reason JavaScript error object describing the validation failure Error:* Error('Validation returns false')* Error('No validator found for element [<field-id>]')

Error management

By default, when facing an incident linked to the library usage, a JavaScript error is intercepted and the form submission is canceled.

In order to be able to deal with it, a callback function can be attached to the object returned by onSubmitEncryptForm .

Tip: it is strongly recommended to implement such function in order to deal with error. This way, you will be able to inform the final user that the payment can't be processed and you will be able to log error information on your server.
      
<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>