WL SIPS DOCS

Release 21.4

go directly to content
Search by keywords

Sips CSE

To search in the page use Ctrl+F on your keyboard

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

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)

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.

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.

Upon your subscription, Worldline provides a secret key on the MEX 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
  • rever 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 MEX.

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

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

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

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.

schema

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.

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, cardCheckEnrollment, addCard functions when the panType field is set to CSE and for walletOrder, walletCheckEnrollment functions when the cscType field is set to CSE

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.comscripts/cse/latest/sdpx.encrypt'
        }
      });
      require(['sdpx.encrypt'], function(sdpx) {
        // ...
      });
    </script>

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.


<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);
  }
}

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 3
CSE key 00AA519EC129B375E8E30DCA7018251433907DF339439 DF0402ABADDD20F3198AB4EC152D830E48ED9B3402660 5BB614897176ECD15DF887A6A79A7392E81BEB2C3CA8D 33FB5E9F9B31DA7809EF1D4EE0B02F3DA15F39B003548 9B53030E2D73AFF4D75433E72C7B614C8852F6E1B99A8 4B50973CD3ACAC642270E636C74739D08C75F11CB9716 8FC23EEFCEACD375BED6C2EE3B826D787F80B282DEC63 EC61FFBCBEC5426E26F423A783D6585865439153E1AF7 23F132933CA7671F8D6A9E9C3AF351081D1465EA20689 2F8D7E1ABBA53373BB4D370A7E02E374E394A8FA20481 C2A121BF7F0300007B7DAD4E69CD66CD99C344D3EC6E7 359EED51D9C6326C01D|010001

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>
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());
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>]')

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>

This site uses cookies to improve your experience, perform analysis and researches on your use of WL Sips documentation website.
You have several options:
Closing this banner you refuse the use of cookies on your device.

Configuration