Client-side encryption SmartPay
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 2
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 dataencrypted-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. Integration methods: full flexibility in look and feel no card details passing your system supports all features including 3D Secure secure and proven solution. 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. Client-side encryption Page 3
Fast implementation, minimal PCI requirements 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 ws@company.yourcompanyname. 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. 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-toserver 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 u se s 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. 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 4
Complete payment support including 3D Secure Integration examples A full integration example along with the Javascript lib: https://github.com/adyenpayments/ techevent2013/tree/master/javascript/ clientencryptionjs Identify 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 /> 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 submitted Changing 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(); } }); Client-side encryption Page 5
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 paymentrequest.shopperemail=john.doe@example.com \ --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 6
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 recurringdetailsrequest.shopperemail=john.doe@example.com \ ------------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 paymentrequest.shopperemail=john.doe@example.com \ --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 7
Main benefits: the credit card data is never readable to you stateless, synchronous processing - the solution does not rely on a session token. uses existing Barclaycard SmartPay APIs, therefore all features are available: 3D Secure recurring risk/fraud detection. Find out more To see the latest versions of our Barclaycard SmartPay support manuals, please refer to our resource centre website: barclaycard.com/smartpay/documentation To contact our support team email: Support.SmartPay@barclaycard.co.uk call 01604 269518 * or from abroad +441604 269518. * Support hours are Monday Friday 09:00 to 18:00 GMT. This information is available in large print, Braille or audio format by calling 0844 811 6666 ** *Calls may be monitored or recorded to maintain high levels of security and quality of service. **For BT business customers, calls to 0844 811 numbers will cost no more than 5.5p per minute, min call charge 6p (current at January 2014). The price on non-bt phone lines may be different. Calls may be monitored and/or recorded. Barclaycard is a trading name of Barclays Bank PLC. Barclays Bank PLC is authorised by the Prudential Regulation Authority and regulated by the Financial Conduct Authority and the Prudential Regulation Authority (Financial Services Register Number: 122702) and subscribes to the Lending Code which is monitored and enforced by the Lending Standards Board. Registered in England No: 1026167. Registered Office: 1 Churchill Place, London E14 5HP. BCD100962SP04. Created 01/14. 34366BD v1.0 Client-side encryption Page 8