diff --git a/HostedCSE.md b/HostedCSE.md new file mode 100644 index 0000000..0f25bae --- /dev/null +++ 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 + + +```` + +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); + +```` + +# Known limitations +- Currently the hosted CSE does not offer a AMD style. We will update this page when it does. \ No newline at end of file diff --git a/Options.md b/Options.md new file mode 100644 index 0000000..0f71c99 --- /dev/null +++ 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 index 7be8295..dfb5c75 100644 --- 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 +
+```` + +### 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 + +```` +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 + +```` +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 ); +}); + +```` + +## 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 + + +```` + + +# 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 new file mode 100644 index 0000000..a6685fd --- /dev/null +++ b/adyen.encrypt.nodom.html @@ -0,0 +1,102 @@ + + + +