JavaScript version 0_1_11

------- * Introduce `adyen.encrypt.createEncryption(key, options)` to split out the DOM handling from the encryption. Allowing easier integration for UI frameworks like Angular or Backbone. * Add a first structure of behavior tracking to the client side encryption which will be embedded as meta data to the encrypted object and use for fraud detection. * Add `options.cvcIgnoreBins` to allow CVC validation to be skipped for certain bins. * Add reference to `adyen.createEncryption(form, options)` which can be used with the [Adyen Hosted Form Based Integration](HostedCSE.md).
Adyen · Apr 14, 2015 · acd3f21 · acd3f21
1 parent 825c685
commit acd3f21
Show file tree

Hide file tree

Showing 11 changed files with 1,105 additions and 129 deletions.
diff --git a/HostedCSE.md b/HostedCSE.md
@@ -0,0 +1,38 @@
+# Adyen Hosted Form Based Integration
+
+A variant to the HTML / Form based integration is to have the library hosted by Adyen, after which you do no longer need to take care of keeping your codebase and encryption key in sync with adyen systems as it will be injected by Adyen.
+
+The syntax is similar to the HTML integration, but instead of downloading and hosting the `adyen.encrypt.min.js` on your own servers, you use a CSE url that is unique for the webservice user you use to post to Adyen. The CSE url can be retrieved from the webservice user page, where you also retrieve your CSE public key. 
+
+*The script URL of the CSE library differs per webservice user. You can retrieve yours from the Edit Webservice User in the Adyen Customer Area. Please note that the url is only visible in the Edit Webservice user page when there is a CSE key generated. If there is none, save the webservice user once to have one generated.*
+
+The HTML template is the same as the HTML based integration shown earlier. However instead of hosting `adyen.encrypt.min.js` on your own server, you include a reference to the Adyen hosted Client-side encryption library. 
+
+
+
+```` html
+<script type="text/javascript" src="https://test.adyen.com/hpp/cse/js/{your Test Webservice user's CSEToken}.shtml"></script>
+<!-- For live: 
+   <script type="text/javascript" src="https://live.adyen.com/hpp/cse/js/{your Live Webservice user's CSEToken}.shtml"></script>
+   
+   Note that the token is not your CSE key, but a newly introduced numeric token.
+-->
+````
+
+Initialze the clientside encryption form as in the normal HTML Form based integration. *Note that the AMD style is not yet available for the hosted CSE library.*
+
+```` javascript
+// the form element to encrypt
+var form    = document.getElementById('adyen-encrypted-form');
+
+// See adyen.encrypt.simple.html for details on the options to use
+var options = {}; 
+
+// Create the form.
+// Note that the method is on the Adyen object, not the adyen.encrypt object.
+adyen.createEncryptedForm( form, options); 
+</script>
+````
+
+# Known limitations
+- Currently the hosted CSE does not offer a AMD style. We will update this page when it does.
diff --git a/Options.md b/Options.md
@@ -0,0 +1,43 @@
+  # Options
+
+  The `createEncryption ( key , `*`options`*` )` and `createEncryptedForm ( form, key, `*`options`*` )` methods currently support the following fields.
+
+
+* **boolean `[enableValidations = true] `**  
+
+  Enable basic field validations. Disable the submit button when the form is not valid 
+
+* **boolean `[submitButtonAlwaysEnabled = false]`**
+
+  Force the submit button to be enabled, even when the front-end validation fails.
+
+* **boolean `[numberIgnoreNonNumeric = true]`**
+
+  When validating the credit card number, ignore non numeric characters like spaces
+
+* **string `[fieldNameAttribute = 'data-encrypted-name']`**
+
+  Configure the attribute to identify fields to be encrypted. Useful when you have multiple payment options within the same form, and want to bind each set to it's own CSE handler.
+
+* **function `[onsubmit]`**
+
+  Custom handler to be called on submit of the form.
+
+* **HTMLElement `[cardTypeElement]`**
+
+  Placeholder element to place card type detection results on, when the card type detection addon is enabled.
+
+* **string `[cvcIgnoreBins = '']`**
+
+  A comma separated string of bins for which the CVC code validation should be ignored.
+
+  For example `cvcIgnoreBins = '6703'`) to ignore CVC validation for BCMC.
+
+
+## Option in createEncryptedForm()
+Supported fields: `enabledValidations`, `numberIgnoreNonNumeric`, `cvcIgnoreBins`, `submitButtonsAlwaysEnabled`, `fieldNameAttribute`, `onsubmit`
+
+When the card type detection addon is being enabled, the `cardTypeElement` option is also supported.
+
+## Option in createEncryption()
+Currently  `enabledValidations`, `numberIgnoreNonNumeric` and `cvcIgnoreBins` are supported.
diff --git a/README.md b/README.md
@@ -1,8 +1,142 @@
-client-side-encryption
-==========
-Sample code for client-side encryption
-
-[![Build Status](https://travis-ci.org/Adyen/CSE-iOS.svg)](https://travis-ci.org/Adyen/CSE-iOS)
+# Client-Side Encryption (CSE)
+
+This repository contains sample code for adding Adyen Payments using Client-side encryption (CSE).
+
+The library currently offers two integration methods:
+
+- [HTML based integration]() in which a HTML form is enriched, encrypting data on submit
+- [JavaScript only integration]() in which data can be encrypted using a JavaScript only API.
+
+The library currently has three inclusion / loading styling:
+- Download `adyen.encrypt.min.js`  and host it yourself. Both HTML based as JavaScript only integration is supported.
+- Download `adyen.encrypt.nodom.min.js` and host it yourself. Only supports JavaScript only integration.
+- Adyen Hosted version in which the public key is embedded in the JavaScript. This integration makes sure you always have the latest security patches, and don't have to keep your public key in sync with the Adyen servers manually. See [Adyen Hosted Form Based Integration](HostedCSE.md) for more details. 
+
+
+## HTML based integration
+
+This integration binds to existing HTML in the page, adding a hidden input containing the encrypted card data to the form on the moment the form is submitted.
+
+The complete integration requires HTML markup to be present in the page, as well as accompanying JavaScript to enable the behavior.
+
+### HTML Template
+
+Create your payment form, and make sure to add a way to reference to your form from JavaScript. For example by adding `id="adyen-encrypted-form"`.
+
+Note that card input fields should not have a `name=` attribute, but are annotated by the `data-encrypted-name=` attribute, to mark them for encryption. This makes sure that the input values are never send to the server.
+````html
+<form method="POST" action="#handler" id="adyen-encrypted-form">
+    <input type="text" size="20" autocomplete="off" data-encrypted-name="number" />
+    <input type="text" size="20" autocomplete="off" data-encrypted-name="holderName" />
+    <input type="text" size="2" maxlength="2" autocomplete="off" data-encrypted-name="expiryMonth" />
+    <input type="text" size="4" maxlength="4" autocomplete="off" data-encrypted-name="expiryYear" />
+    <input type="text" size="4" maxlength="4" autocomplete="off" data-encrypted-name="cvc" />
+    <input type="hidden" value="generate-this-server-side" data-encrypted-name="generationtime" />
+    <input type="submit" value="Pay" />
+</form>
+````
+
+### JavaScript
+Accompanying the above the HTML template, there are two variants to including the CSE library. The original plain JavaScript variant relies on a global `adyen.encrypt` object, while on popular demand a AMD style module has been added.
+
+#### Plain JavaScript
+Include the Adyen Clientside Encryption Library to your page
+````html
+<script type="text/javascript" src="js/adyen.encrypt.min.js"></script>
+````
+Enricht a form in your page with the CSE onSubmit and (optionally) validation behaviors
+````javascript
+// The form element to encrypt
+var form    = document.getElementById('adyen-encrypted-form');
+// The public key
+var key     =   "your key as retrieved from the Adyen Customer Area Web Service User page"; 
+// Form and encryption options. See adyen.encrypt.simple.html for details
+var options = {};
+// Bind encryption to the form
+adyen.encrypt.createEncryptedForm( form, key, options);
+````
+
+#### RequireJS
+Make sure you include requirejs or a alternative AMD module loader in your page
+````html
+<script src="path/to/libs/require.js/2.1.17/require.min.js"></script>
+````
+You can either rename the `adyen.encrypt.min.js` into `adyen/encrypt.js`, or add a paths configuration:
+````javascript
+// Your paths config, or rename the adyen.encrypt.min.js to adyen/encrypt.js
+require.config({
+    paths: {
+        'adyen/encrypt' : '../simple/js/adyen.encrypt.min'
+    }
+});
+````
+
+In the `main.js` or similar file, enrich the form using a `require` call.
+
+````javascript
+require(['adyen/encrypt'], function(adyenEncrypt) {
+    // The form element to encrypt
+    var form    = document.getElementById('adyen-encrypted-form');
+    // The public key
+    var key     =   "your key as retrieved from the Adyen Customer Area Web Service User page"; 
+    // Form and encryption options. See adyen.encrypt.simple.html for details
+    var options = {};
+    // Bind encryption to the form
+    adyenEncrypt.createEncryptedForm( form, key, options );
+});
+</script>
+````
+
+## JavaScript only integration
+
+In case the HTML integration is troublesome in your setup, the library has been split up into two parts since release V0_1_11. The newly introduced part is a HTML independant encryption.
+
+*As with all CSE integrations, make sure that no card data is send to your server unencrypted*
+
+````html
+<script type="text/javascript" src="js/adyen.encrypt.nodom.min.js"></script>
+<script type="text/javascript">
+(function() {
+    var key     =   "your key as retrieved from the Adyen Customer Area Web Service User page"; 
+    var options = {}; // See adyen.encrypt.nodom.html for details
+
+    var cseInstance = adyen.encrypt.createEncryption(key, options);
+
+    function encryptMyData() {
+    
+        var postData = {};
+        
+        var cardData = {
+            number : cardNumber,
+            cvc : cvc,
+            holderName : holderName,
+            expiryMonth : expiryMonth,
+            expiryYear : expiryYear,
+            generationtime : generationtime
+        };
+        
+        postData['adyen-encrypted-data'] = cseInstance.encrypt(cardData);
+        
+        // Ajax Call or different handling of the post data
+    }
+    
+})();
+</script>
+````
+
+
+# Version History
+
+JavaScript version 0_1_11
+-------
+
+* Introduce `adyen.encrypt.createEncryption(key, options)` to split out the DOM handling from the encryption. Allowing easier integration for UI frameworks like Angular or Backbone.
+
+* Add a first structure of behavior tracking to the client side encryption which will be embedded as meta data to the encrypted object and use for fraud detection.
+
+* Add `options.cvcIgnoreBins` to allow CVC validation to be skipped for certain bins.
+
+* Add reference to `adyen.createEncryption(form, options)` which can be used with the [Adyen Hosted Form Based Integration](HostedCSE.md).
 
 JavaScript version 0_1_10
 ---

diff --git a/adyen.encrypt.nodom.html b/adyen.encrypt.nodom.html
@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Example Payment Form</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <link rel="stylesheet" href="css/cse-example-form.css" type="text/css" />
+  </head>
+  <body>
+
+        <div id="adyen-encrypted-form">
+            <input type="button" onclick="encryptExample()" value="Encrypt" />
+            <input type="button" onclick="validateExample()" value="Validate" />
+        </div>
+
+
+        <!-- How to use the Adyen encryption client-side JS library -->
+        <!-- N.B. Make sure the library is *NOT* loaded in the "head" of the HTML document -->
+
+        <script type="text/javascript" src="js/adyen.encrypt.nodom.min.js?0_1_11"></script>
+        <script type="text/javascript">
+
+            // the public key
+            var key     =   "10001|80C7821C961865FB4AD23F172E220F819A5CC7B9956BC3458E2788"
+                            + "F9D725B07536E297B89243081916AAF29E26B7624453FC84CB10FC7DF386"
+                            + "31B3FA0C2C01765D884B0DA90145FCE217335BCDCE4771E30E6E5630E797"
+                            + "EE289D3A712F93C676994D2746CBCD0BEDD6D29618AF45FA6230C1D41FE1"
+                            + "DB0193B8FA6613F1BD145EA339DAC449603096A40DC4BF8FACD84A5D2CA5"
+                            + "ECFC59B90B928F31715A7034E7B674E221F1EB1D696CC8B734DF7DE2E309"
+                            + "E6E8CF94156686558522629E8AF59620CBDE58327E9D84F29965E4CD0FAF"
+                            + "A38C632B244287EA1F7F70DAA445D81C216D3286B09205F6650262CAB415"
+                            + "5F024B3294A933F4DC514DE0B5686F6C2A6A2D"; 
+
+            var options = {};
+
+            // Enable basic field validation (default is true)
+            // The submit button will be disabled when fields
+            // proof to be invalid. The form submission will be
+            // prevented as well.
+            // options.enableValidations = true;
+
+            // Ignore non-numeric characters in the card number field (default
+            // is true)
+            // The payment handling ignores non-numeric characters for the card
+            // field.
+            // By default non-numeric characters will also be ignored while
+            // validating
+            // the card number field. This can be disabled for UX reasons.
+            // options.numberIgnoreNonNumeric = true;
+
+            // Ignore CVC validations for certain bins. Supply a comma separated
+            // list.
+            // options.cvcIgnoreBins = '6703'; // Ignore CVC for BCMC
+
+
+            var cseInstance = adyen.encrypt.createEncryption(key, options);
+
+            function getEncryptedFormData(cardNumber, cvc, holderName, expiryMonth, expiryYear, generationtime) {
+
+                var postData = {};
+
+                var cardData = {
+                    number : cardNumber,
+                    cvc : cvc,
+                    holderName : holderName,
+                    expiryMonth : expiryMonth,
+                    expiryYear : expiryYear,
+                    generationtime : generationtime
+                };
+
+                postData['adyen-encrypted-data'] = cseInstance.encrypt(cardData);
+
+                return postData;
+            }
+
+            function encryptExample() {
+                var generationTime = new Date().toISOString(); // Note:
+                                                                // Generate this
+                                                                // serverside!
+
+                var postData = getEncryptedFormData("5555 4444 3333 1111", "737", "John Doe", "06", "2016", generationTime);
+
+                var p = document.createElement("p");
+
+                p.innerHTML = "Post data: " + JSON.stringify(postData);
+
+                document.body.appendChild(p);
+            }
+
+            function validateExample() {
+
+                var valid = cseInstance.validate({"number": "5555 4444 3333 1111", "cvc" : "737", "month": "06", "year": "2016"});
+
+                var p = document.createElement("p");
+
+                p.innerHTML = "Validation response: " + JSON.stringify(valid);
+
+                document.body.appendChild(p);
+            }
+
+        </script>
+    </body>
+</html>