JavaScript integration

This page explains the steps to integrate Client Side Encryption with your payment pages using JavaScript.

If you're using require.js, clickhere.

  1. Create your RSA key pair, and access your key

  2. Include the Worldpay CSE JavaScript Library

  3. Set the public key

  4. Implement a callback function to handle errors

  5. Set up the encryption function

  6. Implement the form

Note: View our JavaScript terms of usehere.

Create your RSA key pair

CSE works using a 2048 bit RSA key pair which is made up of a public key and a private key. The public key must be supplied to the CSE library, and is used to encrypt the sensitive card details.

The private key exists within a secure environment at Worldpay. It is never transmitted and is not visible to any member of staff at Worldpay.

To create a key pair:

  1. Log in to the Merchant Admin Interface (MAI) and click Client Side Encryption in the left panel.

  2. Enter the description of the key, and then click Generate key.

    The key pair has now been generated, and you'll be able to use the public key to encrypt card details.

Note: You can create more than one key. This is useful, for example, if you want to roll your keys to change them after a period of time. You can also disable a disused key. To learn more seeKey Rotation.

Access your key

To build the key into your payment page, you must view it:

  1. Click View key on the key you wish to view. You'll be taken to a page which shows the key in two different formats:

    1. Public key

      This is the whole key in its entirety.

    2. JavaScript formatted key

      This is your formatted key. It has been formatted to allow you to simply copy it into your payment page.

  2. Click the Client Side Encryption button at the bottom of the page to return to the main page.

Note: Although sensitive information is encrypted, there is no change in the way Worldpay processes a payment.

Include the Worldpay CSE JavaScript Library

For CSE to work, reference the Worldpay CSE JavaScript library. There are two ways to do this:

  • Automatically reference the latest version of the current major release:
Copied!
<script src="https://secure.worldpay.com/resources/cse/js/worldpay-cse-1.latest.min.js"></script>
  • Reference the specific version:
Copied!
<script src="https://payments.worldpay.com/resources/cse/js/worldpay-cse-1.0.1.min.js"></script>

Note: Information about our CSE JavaScript library is available on [Github](https://github.com/Worldpay/worldpay-cse-lib-javascript/).

Set the public key

To set your public key (to identify you on our server):

Copied!
Worldpay.setPublicKey([YOUR PUBLIC KEY]);

Implement a callback function to handle errors

Warning: We strongly recommend that you use an error handler with your JavaScript integration. If you do not, unseen errors can stop the form from working.

The error handler is a callback function that can be supplied to the useForm or encrypt functions. It takes one argument and does not need to return any value. The argument supplied to the function is an array of error codes that represent which validation errors have occurred. Here is an example of the function:

Copied!
function errorHandler(errorCodes) {

// This should be handled in a way that is relevant to your payment pages

}

For example, if a credit card number is invalid and the cardholder name is missing, then this function will get called with the argument [102, 401]. If no validation errors occur, then this function will not get called. Descriptions of the possible error codes can be found inTroubleshoot.

Note: The Worldpay error callback function is designed as a final additional check, and is not intended to replace your own validation. For example, we perform validation on the CVC value only if the shopper enters one. If you require the CVC field to be mandatory, you must check this yourself.

Performed validation

These are the validations performed on the cardholder data fields:

'data-worldpay' attributeValidation checks and resulting errors
numberIf blank or contains white space = 101
Otherwise, if anything other than 12-20 digits = 102
Otherwise, if a luhn check fails = 103
cvcIf blank or contains white space, treated as valid
Otherwise, if anything other than 3 or 4 digits = 201
exp-monthIf blank or contains white space = 301
Otherwise, if anything other than 2 digits = 302
Otherwise, if less than 1 or greater than 12 = 303
exp-yearIf blank or contains white space = 304
Otherwise, if anything other than 4 digits = 305
exp-month and exp-year togetherIf date is in the past = 306
Note: Only applies if the exp-month and exp-year are separately valid, but together produce a date in the past
nameIf blank or contains white space = 401
Otherwise, if greater than 30 characters = 402
Note: No explicit restriction is applied to the characters themselves

Set up the encryption function

The encryption function can be set up in a number of ways. To set up the encryption function in a typical way:

Copied!
Worldpay.useForm(errorHandler);

Other options

Implement the form

For the form to work, use the data-worldpay attribute for each item of cardholder data. A typical example is:

Copied!
<body> 
    <form action="[YOUR FORM ACTION]" method="post" data-worldpay="payment-form"> 
        <input data-worldpay="name"> <!-- This is the card holder name field --> 
        <input data-worldpay="number"> <!-- This is the card number field --> 
        <input data-worldpay="exp-month"> <!-- This is the expiry month field --> 
        <input data-worldpay="exp-year"> <!-- This is the expiry year field --> 
        <input data-worldpay="cvc"> <!-- This is the CVC field--> 
        <input type="hidden" name="[YOUR DATA PARAMETER]" data-worldpay="encrypted-data"> 
        <input type="submit"> 
    </form> 
</body>

In this example the data-worldpay="encrypted-data" attribute sends the encrypted data to your server using [YOUR DATA PARAMETER]. If it isn't present, a new hidden input field will be created as below:

Copied!
<input type="hidden" name="encryptedData" data-worldpay="encrypted-data" value="[YOUR ENCRYPTED DATA]">

Warning: Do not use the "name" HTML attribute in your form post unless you want to pass data to your server unencrypted.

How it all fits together

Here's a example of one way to do a JavaScript integration:

Copied!
<html>
<head>
    <script src="https://secure.worldpay.com/resources/cse/js/worldpay-cse-1.latest.min.js"></script&gt;
    <script>        window.onload = function() {            function errorHandler(errorCodes) {
                // This should be handled in a way that is relevant to your payment pages
            }
            Worldpay.setPublicKey([YOUR PUBLIC KEY]);
            Worldpay.useForm(errorHandler);
        }
    </script>
</head>
<body>
    <form action="[YOUR FORM ACTION]" method="post" data-worldpay="payment-form">
        <input data-worldpay="name">      <!-- This is the card holder name field -->
        <input data-worldpay="number">    <!-- This is the card number field      -->
        <input data-worldpay="exp-month"> <!-- This is the expiry month field     -->
        <input data-worldpay="exp-year">  <!-- This is the expiry year field      -->
        <input data-worldpay="cvc">       <!-- This is the cvc field              -->
        <input type="hidden" name="[YOUR DATA PARAMETER]" data-worldpay="encrypted-data">
        <input type="submit">
    </form>
</body>
</html>

Terms of use

You can find the terms of use for JavaScript inWorldpay Developer Terms of Use for Javascript.