Client-side
encryption
Client-side encryption Page 2
Contents
Client-side encryption 3
How does it work? 3
Integration methods 3
Fast implementation, minimal PCI requirements 4 Where can I find my public key? 4 Is client-side encryption secure? 4
Key features 4
Completing payment support including 3D Secure 5
Integration examples 5 Identify your form with an ‘ID’ attribute 5 Input fields 5 Generationtime field 5 The Javascript 5 Changing form post behaviour using AJAX 5 Integration example server side 6 Submit a charge 6 Submit initial charge and store customer 6 List recurring details/cards for customer 7 Submit a recurring charge 7 Main benefits 8
Client-side encryption Page 3
Client-side encryption
Barclaycard SmartPay client-side encryption is a P2PE (Point-to-Point Encryption) solution
for Card-Not-Present (CNP) payments which takes the headache out of PCI compliance. With
this solution, you can take credit card payments directly on your own website by encrypting
the card in the browser (client) so that the card data is never visible to your server.
How does it work?
All that is required are the following simple steps. 1. Build your credit card form as you normally would. 2.
Make sure the card fields have the attribute ‘data-encrypted-name’ instead of ‘name’.
3. Include the ‘adyen.encrypt.min.js’ client encryption library. 4. Set the public key and tie the library to your form.
The client encryption library will:
1. intercept the form submission event before it hits your server 2. encrypt the card fields in-browser using a per transaction unique AES key 3. encrypt the unique AES key with your RSA public key 4. send the encrypted data (containing the card and encrypted AES key) with the other fields in the form.
Integration methods:
– full flexibility in look and feel – no card details passing your system – supports all features including 3D Secure – secure and proven solution.Client-side encryption Page 4
Fast implementation,
minimal PCI requirements
Key features:
– the Public Key (RSA) can be downloaded from the Barclaycard SmartPay back office – the Secret Key (RSA) is only known to Barclaycard and stored only in encrypted form – all Card data is End-To-End encrypted and is never visible to merchants – the payment authorisation is done over the server-to-server Barclaycard SmartPay API using the encrypted card. – the encrypted data is only valid for a period of 24 hours and tied to your public key. It is of no use outside of this context – uses RSA and ECC in JavaScript: the jsbn library is a fast,portable implementation of large number mathematics in pure JavaScript, enabling public-key crypto and other applications on desktop and mobile browsers
– uses Stanford Javascript Crypto Library (AES): the Stanford Javascript Crypto Library is a project by the Stanford Computer Security Lab to build a secure, powerful, fast, small, easy-to-use, cross-browser library for cryptography in Javascript.
Where can I find my public key?
The public key is tied to the WebService user you will be submitting the API payment request with. It is available in the back office under ‘Settings’ > ‘Users’ and will be of the form ‘[email protected]’. If no key has been generated yet, you will see an option to ‘Generate’ the key first. It is displayed in ‘pre-formatted’ form so you can simply copy and paste it into your page.
Is client-side encryption secure?
The client-side encryption solution uses only PCI/NIST approved cryptographic algorithms. The RSA key is 2048 bits and unique to your user account. Per transaction the client will generate a unique AES (256bit) key which is used in CCM mode for both encryption and authentication.
Client-side encryption Page 5
Complete payment support
including 3D Secure
Generationtime field
Add a hidden generationtime field with the current time on server: The format of this should be in the ISO 8601 standard format for XML as YYYY-MM-DDTHH:mm:ss.sssZ, e.g. 2013-04-26T14:02:30.668Z. It is important not to rely on the client’s time (for production) which may be incorrect as the encrypted data is only usable within a 24-hour period of this time. <input type=”hidden” value”= ”GENERATE_ON_SERVER id=”generationtime ” data−encrypted−name=”generationtime” />The Javascript
<script src=”js/adyen.encrypt.min.js”></script> var form = document.getElementById(’adyen− encrypted−form’); // the form element to encrypt var key = ”10001j80C7821...6BC3458E2788” + ”5 F024B3294....6A2D”; // the public key adyen.encrypt.createEncryptedForm( form, key ); // the form will be encrypted before it is submittedChanging form post behaviour using AJAx
You can change the behaviour of the library by adding options to the ‘createEncryptedForm()’. For example, change the name of the encrypted data and submit the form using AJAX rather than the default: var name = ’fieldnameofyourchoosing’; adyen.encrypt.createEncryptedForm( form, key { name : name, onsubmit : function(e) { ... Your AJAX Code Here ... e.preventDefault(); } });
Integration examples
A full integration example along with the Javascript lib: https://github.com/adyenpayments/ techevent2013/tree/master/javascript/ clientencryptionjsIdentify your form with an ‘ID’ attribute
<form method=”POST” action=”posthandler. action” id=”adyen−encrypted−form”>
Input fields
Input fields for the card data should have no ‘name’ attribute: <input type=”text” value=”” size=”20” autocomplete=”off” data−encrypted−name =”number” />Client-side encryption Page 6
Integration example server side
Here are some examples of how to use the Barclaycard SmartPay client-side encryption API. We use command-line Curl for the sake of simplicity, but the principle remains the same regardless of the tool or programming language used.
Submit a charge
curl --user ‘username:password’ https://pal-test.adyen.com/pal/adapter/httppost \ --data-urlencode ‘action=Payment.authorise’ \ --data-urlencode ‘paymentRequest.amount.currency=EUR’ \ --data-urlencode ‘paymentRequest.amount.value=1234’ \ --data-urlencode ‘paymentRequest.merchantAccount=YourAccountCode’ \ --data-urlencode ‘paymentRequest.reference=Example Order 1’ \ --data-urlencode ‘paymentRequest.additionalData.card.encryptedjson= adyenjs_0_1_1$eGcJxidHkg5LYQ...6LUio9RipqyTBu11MJIC+ rlMYxituYCT7A9yDeF2Rlv2I56KOAap66tTm2uZkto4PKRW4YCA8dZYQ==’Submit intial charge and store customer
curl --user ‘username:password’ https://pal-test.adyen.com/pal/adapter/httppost \ --data-urlencode ‘action=Payment.authorise’ \ --data-urlencode ‘paymentRequest.amount.currency=EUR’ \ --data-urlencode ‘paymentRequest.amount.value=1234’ \ --data-urlencode ‘paymentRequest.merchantAccount=YourAccountCode’ \ --data-urlencode ‘paymentRequest.reference=Example Order 1’ \ --data-urlencode ‘paymentRequest.recurring.contract=RECURRING’ \ --data-urlencode ‘paymentRequest.shopperReference=user123’ \ --data-urlencode ‘[email protected]’ \ --data-urlencode ‘paymentRequest.additionalData.card.encrypted.json= adyenjs_0_1_1$kj7nlobE1rlC2...iaE/cY878H+Op’ ---Response ----paymentResult.authCode=98356 paymentResult.pspReference=9913642236790892 paymentResult.resultCode=Authorised
---Client-side encryption Page 7
List recurring details/cards for customer
curl --user ‘username:password’ https://pal-test.adyen.com/pal/adapter/httppost \ --data-urlencode ‘action=Recurring.listRecurringDetails’ \ --data-urlencode ‘recurringDetailsRequest.merchantAccount=YourAccountCode’ \ --data-urlencode ‘recurringDetailsRequest.recurring.contract=RECURRING’ --data-urlencode ‘recurringDetailsRequest.shopperReference=user123’ \ --data-urlencode ‘[email protected]’ \ ---Response ----recurringDetailsResult.shopperReference=user123 recurringDetailsResult.creationDate=2013-03-25T13:23:14+01:00 recurringDetailsResult.lastKnownShopperEmail=john.doe@example.com recurringDetailsResult.details.0.variant=mc recurringDetailsResult.details.0.recurringDetailReference=9913642141960010 recurringDetailsResult.details.0.creationDate=2013-03-25T13:23:16+01:00 recurringDetailsResult.details.0.card.number=1111 recurringDetailsResult.details.0.card.expiryMonth=6 recurringDetailsResult.details.0.card.expiryYear=2016 recurringDetailsResult.details.0.card.holderName=John Doe
---Submit a recurring charge
curl --user ‘username:password’ https://pal-test.adyen.com/pal/adapter/httppost \ --data-urlencode ‘action=Payment.authorise’ \ --data-urlencode ‘paymentRequest.amount.currency=EUR’ \ --data-urlencode ‘paymentRequest.amount.value=1234’ \ --data-urlencode ‘paymentRequest.merchantAccount=YourAccountCode’ \ --data-urlencode ‘paymentRequest.reference=Example Order 2’ \ --data-urlencode ‘paymentRequest.shopperReference=user123’ \ --data-urlencode ‘[email protected]’ \ --data-urlencode ‘paymentRequest.shopperInteraction=ContAuth’ \ --data-urlencode ‘paymentRequest.recurring.contract=RECURRING’ \ --data-urlencode ‘paymentRequest.selectedRecurringDetailReference=9913642141960010’ ---Response ----paymentResult.authCode=75682 paymentResult.pspReference=9913642244711617 paymentResult.resultCode=Authorised
---Client-side encryption Page 8
