Vantiv EProtect Integration Guide E Protect V6.6
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 126
| Download | |
| Open PDF In Browser | View PDF |
eProtect™ Integration Guide January 2018 cnpAPI Release: V12.0 eProtect API V2.1 Document Version: 6.6 Vantiv eProtect™ Integration Guide Document Version: 6.6 All information whether text or graphics, contained in this manual is confidential and proprietary information of Vantiv, LLC and is provided to you solely for the purpose of assisting you in using a Vantiv, LLC product. All such information is protected by copyright laws and international treaties. No part of this manual may be reproduced or transmitted in any form or by any means, electronic, mechanical or otherwise for any purpose without the express written permission of Vantiv, LLC. The possession, viewing, or use of the information contained in this manual does not transfer any intellectual property rights or grant a license to use this information or any software application referred to herein for any purpose other than that for which it was provided. Information in this manual is presented "as is" and neither Vantiv, LLC or any other party assumes responsibility for typographical errors, technical errors, or other inaccuracies contained in this document. This manual is subject to change without notice and does not represent a commitment on the part Vantiv, LLC or any other party. Vantiv, LLC does not warrant that the information contained herein is accurate or complete. All trademarks are the property of their respective owners and all parties herein have consented to their trademarks appearing in this manual. Any use by you of the trademarks included herein must have express written permission of the respective owner. Copyright © 2003-2018, Vantiv, LLC - ALL RIGHTS RESERVED. CONTENTS About This Guide Intended Audience ........................................................................................................... vii Revision History ............................................................................................................... vii Document Structure ........................................................................................................ xiii Documentation Set ......................................................................................................... xiv Typographical Conventions ............................................................................................ xiv Contact Information..........................................................................................................xv Chapter 1 Introduction eProtect Overview............................................................................................................. 2 How eProtect Works ......................................................................................................... 4 Getting Started with eProtect ............................................................................................ 6 Migrating From Previous Versions of the eProtect API............................................... 6 From eProtect with jQuery 1.4.2 ........................................................................... 6 From JavaScript Browser API to iFrame ............................................................... 7 Browser and Mobile Operating System Compatibility ................................................. 8 Communication Protocol Requirement ................................................................. 8 eProtect Support for Apple Pay™ / Apple Pay on the Web ........................................ 8 eProtect Support for Android Pay™............................................................................ 9 eProtect Support for Pay with Google™ ................................................................... 10 jQuery Version .......................................................................................................... 10 Certification and Testing Environments .................................................................... 10 Pre-Live Environment Limitations and Maintenance Schedule ........................... 11 Transitioning from Certification to Production ........................................................... 12 eProtect-Specific Response Codes .......................................................................... 12 Creating a Customized CSS for iFrame.......................................................................... 14 CSS iFrame Validation and Customization Features................................................ 14 Using Web Developer Tools ..................................................................................... 18 Reviewing your CSS with Vantiv............................................................................... 18 Chapter 2 Integration and Testing Integrating Customer Browser JavaScript API Into Your Checkout Page ...................... 22 Integration Steps ....................................................................................................... 22 Loading the eProtect API and jQuery........................................................................ 23 Specifying the eProtect API Request Fields ............................................................. 24 Specifying the eProtect API Response Fields........................................................... 25 Handling the Mouse Click ......................................................................................... 25 Intercepting the Checkout Form Submission ............................................................ 27 Document Version: 6.6 — cnpAPI Release: V12.0 © 2017 Worldpay, Inc. - All Rights Reserved. iii eProtect™ Integration Guide Contents Handling Callbacks for Success, Failure, and Timeout............................................. 27 Success Callbacks .............................................................................................. 27 Failure Callbacks................................................................................................. 28 Timeout Callbacks............................................................................................... 29 Detecting the Availability of the eProtect API............................................................ 29 Using the Customer Browser JavaScript API for Apple Pay on the Web.................. 30 Integrating iFrame into your Checkout Page .................................................................. 32 Integration Steps ....................................................................................................... 32 Loading the iFrame ................................................................................................... 32 Configuring the iFrame.............................................................................................. 33 Calling the iFrame for the Registration ID ................................................................. 35 Handling Callbacks ................................................................................................... 36 Handling Errors ................................................................................................... 38 Integrating eProtect Into Your Mobile Application........................................................... 39 Creating the POST Request ..................................................................................... 39 Sample Request.................................................................................................. 40 Sample Response............................................................................................... 40 Using the Vantiv Mobile API for Apple Pay ............................................................... 42 Creating a POST Request for an Apple Pay Transaction ................................... 43 Sample Apple Pay POST Request ..................................................................... 44 Sample Apple Pay POST Response................................................................... 45 Using the Vantiv Mobile API for Android Pay............................................................ 45 Using the Vantiv Mobile API for Pay with Google ..................................................... 48 Collecting Diagnostic Information ................................................................................... 51 Transaction Examples When Using cnpAPI ................................................................... 52 Transaction Types and Examples............................................................................. 52 Authorization Transactions........................................................................................ 53 Authorization Request Structure ......................................................................... 53 Authorization Response Structure ...................................................................... 54 Sale Transactions ..................................................................................................... 56 Sale Request Structure ....................................................................................... 56 Sale Response Structure .................................................................................... 57 Register Token Transactions .................................................................................... 59 Register Token Request ..................................................................................... 59 Register Token Response................................................................................... 60 Force Capture Transactions...................................................................................... 61 Force Capture Request....................................................................................... 61 Force Capture Response .................................................................................... 62 Capture Given Auth Transactions ............................................................................. 63 Capture Given Auth Request .............................................................................. 63 Capture Given Auth Response ........................................................................... 65 iv Document Version: 6.6 — cnpAPI Release: V12.0 © 2017 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Contents Credit Transactions ................................................................................................... 66 Credit Request Transaction ................................................................................ 66 Credit Response ................................................................................................. 67 Testing and Certification ................................................................................................. 69 Testing eProtect Transactions .................................................................................. 69 Appendix A Code Samples and Other Information HTML Checkout Page Examples .................................................................................... 74 HTML Example for Non-eProtect Checkout Page .................................................... 74 HTML Example for JavaScript API-Integrated Checkout Page................................. 75 HTML Example for Hosted iFrame-Integrated Checkout Page................................. 78 Information Sent to Order Processing Systems .............................................................. 82 Information Sent Without Integrating eProtect .......................................................... 82 Information Sent with Browser-Based eProtect Integration ...................................... 82 Information Sent with Mobile API-Based Integration................................................. 83 cnpAPI Elements for eProtect......................................................................................... 84 cardValidationNum.................................................................................................... 85 expDate..................................................................................................................... 86 paypage .................................................................................................................... 87 paypageRegistrationId .............................................................................................. 88 registerTokenRequest............................................................................................... 89 registerTokenResponse ............................................................................................ 90 Appendix B CSS Properties for iFrame API CSS Property Groups ..................................................................................................... 92 Properties Excluded From White List............................................................................ 106 Appendix C Sample eProtect Integration Checklist Index Document Version: 6.6 — cnpAPI Release: V12.0 © 2017 Worldpay, Inc. - All Rights Reserved. v eProtect™ Integration Guide vi Contents Document Version: 6.6 — cnpAPI Release: V12.0 © 2017 Worldpay, Inc. - All Rights Reserved. ABOUT THIS GUIDE This guide provides information on integrating the eProtect™ solution, which, when used together with Vault, may help reduce your risk by virtually eliminating your exposure to sensitive cardholder data and help reduce PCI applicable controls. It also explains how to perform eProtect transaction testing and certification with Vantiv. NOTE: The PayPage product is now known as Vantiv eProtect. The term ‘PayPage’ however, is still used in this guide in certain text descriptions, along with many data elements, JS code, and URLs. Use of these data elements, etc., with the PayPage name is still valid with this release, but will transition to ‘eProtect’ in a future release. Intended Audience This document is intended for technical personnel who will be setting up and maintaining payment processing. Revision History This document has been revised as follows: TABLE 1 Document Revision History Doc. Version Description Location(s) 1.0 Initial Draft All 1.1 Second Draft All 2.0 First full version All 2.1 Added new material (examples, XML reference information) on submitting a PayPage Registration ID with a Token Request. Also added a new Response Reason Code. Chapters 1 and 2, and Appendix A Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. vii eProtect™ Integration Guide About This Guide TABLE 1 Revision History Document Revision History (Continued) Doc. Version Description Location(s) 2.2 Changed product name from ‘Pay Page’ to ‘PayPage’. All 2.3 Changed certification environment URL from https://merchant1.securepaypage.litle.com/litle-api.js to https://cert01.securepaypage.litle.com/litle-api.js. All 2.4 Added information for the support of new transaction types (Capture Given Auth, Force Capture, and Credit), including XML Examples, and XML reference information. Chapter 2 and Appendix A Added information and recommendations for timeout periods and failure callbacks. Updated the Getting Started section. Chapter 1 and 2 Added additional information on components of the SendtoLitle call and recommendations on collecting data in the case of a failed transaction. Chapter 2 Added a new Appendix contained a sample PayPage Integration Checklist. Appendix B Added and updated information due to XML changes in support of CVV2 updates, including coding changes, new test cases, etc. All chapters and appendixes. Updated the sample Litle JavaScript. Appendix A Changed certification environment URL from: Chapter 1 and 2 2.5 2.6 https://cert01.securepaypage.litle.com/litle-api.js. to: https://cert01.securepaypage.litle.com/LitlePayPage/litle-api.js 2.7 Changed the certification and production URLs: All New Testing and Certification URL: https://request.cert01-securepaypage-litle.com New Production URL: (see your Implementation Consultant) viii 2.8 Removed reference to companyname in production URL example. Chapter 2 2.9 Removed references to Production URL. All Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Revision History TABLE 1 Doc. Version 2.10 About This Guide Document Revision History (Continued) Description Location(s) Added and updated information on the updated Litle API (V2), including requirements on loading a jQuery library. All Added information on migrating from previous versions of the PayPage API. Chapter 1 Updated the sample Litle JavaScript. Appendix A Changed certification environment URL from: Chapter 1 and 2 https://cert01.securepaypage.litle.com/LitlePayPage/litle-api.js to: https://cert01.securepaypage.litle.com/LitlePayPage/litle-api2.js 2.11 Added text, notes, and callouts to further emphasize the proper use of the certification environment URL versus the production URL. All 2.12 Changed the certification environment URL from: All https://cert01.securepaypage.litle.com/LitlePayPage/litle-api2.js to: https://request-prelive.np-securepaypage-litle.com/LitlePayPage /litle-api2.js Added information on the new Certification and Testing environments: Pre-live, Post-live (regression testing), and Sandbox. Chapter 1 3.0 Removed sections related to alternative processing. All 3.1 Added information on PayPage capabilities in a native mobile application. All 4.0 Re-branded the entire guide to reflect Litle-Vantiv merger. All Updated to LitleXML version 8.27. Chapter 2 4.1 Added information on new fields returned in the PayPage response; updated JavaScript version (2.1). Chapter 2, Appendix A and B 4.2 Changed the name of the mobile product to native mobile application All 4.3 Updated verbiage related to PCI scope. All Added information on support for Apple Pay™. Chapter 2 Corrected the URL for mobile POST requests. Chapter 2 Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. ix eProtect™ Integration Guide About This Guide TABLE 1 Doc. Version 4.4 Revision History Document Revision History (Continued) Description Location(s) Corrected the URL for in various examples for mobile POST requests from: Chapter 1 and 2 https://request-prelive.np-securepaypage-litle.com/LitlePayPage to https://request-prelive.np-securepaypage-litle.com/LitlePayPage /paypage 4.5 Updated the guide to include information on the Vantiv-Hosted PayPage iFrame solution (many changes and re-arrangement of sections). Also includes the addition of Appendix B, and new HTML and JavaScript samples in Appendix A. All 4.6 Updated callback handling code examples for iFrame. Chapter 2 4.7 Added a link for accessing an example iFrame page. Chapter 1 Added a new parameter for iFrame applications - ‘htmlTimeout,’ as well as two new error codes for failures when the iFrame fails to load (884), or if the CSS fails load (885). Updated the code examples to reflect these additions. Chapter 1 and Chapter 2 Updated information on testing URLs and User Agent examples for Mobile applications. Chapter 2 Updated the Browser and Mobile Operating System Compatibility section (removed support for Android 2.1 and 2.2). Chapter 1 Added a step (Step 7) on creating a style sheet to the section on migrating from JavaScript Browser API to Vantiv-Hosted iFrame. Chapter 1 Updated the Apple Pay™ POST Response to include an expiration date. Chapter 2 Corrected the iFrame URLs in Table 1-1 from: Chapter 1 4.8 4.9 https://request-prelive.np-securepaypage-litle.com/LitlePayPage /payframe-client.min.js to https://request-prelive.np-securepaypage-litle.com/LitlePayPage /js/payframe-client.min.js. 5.0 x Updated product name in applicable areas throughout the guide from PayPage to eProtect (Phase 1). Also updated many instances of PayFrame to iFrame. All Updated the eProtect workflow diagrams and steps. Chapter 1 Updated LitleXML examples to reflect updates to LitleXML V10.0. Chapter 2 Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Revision History TABLE 1 About This Guide Document Revision History (Continued) Doc. Version Description Location(s) 5.1 Added information on obtaining CSS sample files from Vantiv. Chapter 1 and Appendix B Increased recommended transaction timeout value to 15000 (15 seconds) from 5000 (five seconds). Chapter 2, Appendix A and C Added information on maximum length and data type for orderId and id parameters. Chapter 2 Added information on the length of time the CVV values are held (24 hours). Chapter 2 Removed all references to eChecks (not currently supported for eProtect). Chapter 2 Updated/corrected information in the testing sections. Chapter 2 5.3 Removed the sample JavaScripts in Appendix A. Sample scripts are available at the pre-live, post-live, and production eProtect URLs. Chapter 1, Appendix A 5.4 Added information on support for Apple Pay on the Web. Chapters 1, 2, Appendix A Added code and definitions for litleFormFields to the Browser JavaScript API example. Chapter 2 Corrected the reference to ‘Apple PassKit Framework’ to ‘Apple Pay JavaScript API’ in Step 1 of the Apple Pay Web process. Chapter 2 Updated the Apple PKPayment Token documentation URL. Chapter 2 5.6 Added notes to LitleXML transaction examples related to expiration dates (required for eProtect transactions). Chapter 2 5.7 Updated contact e-mails, phone numbers, and hours of operation in the Contact Information section. Preface Added information on loading the JavaScript API (must be loaded daily to your checkout page). Chapter 2 Changed some text instances of ‘PayFrame’ to ‘iFrame.’ Chapter 2 Added notes to recommend eProtect testing using different devices and all browsers. Chapter 1 and 2 5.2 5.5 5.8 Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. xi eProtect™ Integration Guide About This Guide TABLE 1 Document Revision History (Continued) Doc. Version Description Location(s) 5.9 Added information on support for Android Pay. Chapter 1 and 2 Updated the XML examples to reference LitleXML 11.0. Chapter 2 Updated the descriptions of id and orderId fields/elements. Chapter 2 Added recommendation on avoiding ‘Flash of Un-styled Content’ (FOUC) issues. Chapter 2 Updated all URLs (JavaScript library request, submission request, etc.) due to retirement of Litle domain. Chapter 1 and 2 Added note on informing customer of JavaScript requirement. Chapter 2 Updated most instances of ‘PayFrame’ with ‘iFrame.’ All Updated numerous function and object names (due to retirement of Litle name) with Vaniv, Vantivcnp or eProtect, etc. All Updated cnpAPI version to 11.1. Chapter 2 6.1 Added information on new enhancements to iFrame for greater iFrame and CSS customizations, including in-line field validations, tool tip additions and customizations, etc. Chapter 1 and Chapter 2 6.2 Updated the testlitle.com sample page URLs to testvantivcnp.com. Added further information on which sample page URL to view when using the new enhanced iFrame features. Chapter 1 6.3 Corrected the Request Submission URL in Table 1-2 from https://request-eprotect.vantivprelive.com to https://request.eprotect.vantivprelive.com. Chapter 1 Added information on Pre-Live Certification Environment maintenance and limitations. Chapter 1 Updated cnpAPI version to 11.2. Chapter 2 Added information on required communication protocol. Chapter 1 Corrected some instance of ‘eProtect’ in code samples. Appendix A 6.0 6.4 xii Revision History Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Document Structure TABLE 1 Doc. Version 6.5 6.6 About This Guide Document Revision History (Continued) Description Location(s) Updated all cnpAPI element names to replace Litle with cnp. For example, litleToken is now cnpToken, litleOnlineRequest is now cnpOnlineRequest, etc. This includes the namespace: http://www.litle.com/schema is now http://www.vantivcnp.com/schema. Chapter 2 Corrected various eProtect element spelling errors, cleaned up miscellaneous coding in the HTML examples. Chapter 2 and Appendix A Re-worked Section 1.3.8, Creating a Customized CSS for iFrame for clarification. Chapter 1 Added information on new CSS-allowed Appearance properties. Appendix B Re-arranged and relocated the Creating a Customized CCS for iFrame section for better understanding. Chapter 1 Added information on including a ‘Trust Icon’ on your payment page when customizing iFrame CSS files. Chapter 1 Removed workaround information for Flash of Unstyled Content (FOUC) as this issue has been corrected. Chapter 2 Added information on Pay With Google. Chapter 1 and 2 Document Structure This manual contains the following sections: Chapter 1, "Introduction" This chapter provides an overview of the eProtect feature, and the initial steps required to get started with eProtect. Chapter 2, "Integration and Testing" This chapter describes the steps required to integrate the eProtect feature as part of your checkout page, cnpAPI transaction examples, and information on eProtect Testing and Certification. Appendix A, "Code Samples and Other Information" This appendix provides code examples and reference material related to integrating the eProtect feature. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. xiii eProtect™ Integration Guide About This Guide Documentation Set Appendix B, "CSS Properties for iFrame API" This appendix provides a list of CSS Properties for use with the iFrame implementation of eProtect. Appendix C, "Sample eProtect Integration Checklist" This appendix provides a sample of the eProtect Integration Checklist for use during your Implementation process Documentation Set The Vantiv documentation set also include the items listed below. Please refer to the appropriate guide for information concerning other Vantiv product offerings. • Vantiv eCommerce iQ Reporting and Analytics User Guide • Vantiv cnpAPI Reference Guide • Vantiv eCommerce Solution for Apple Pay • Vantiv Chargeback API Reference Guide • Vantiv Chargeback Process Guide • Vantiv PayPal Integration Guide • Vantiv PayFac API Reference Guide • Vantiv PayFac Portal User Guide • Vantiv cnpAPI Differences Guide • Vantiv Scheduled Secure Reports Reference Guide • Vantiv Chargeback XML and Support Documentation API Reference Guide (Legacy) Typographical Conventions Table 2 describes the conventions used in this guide. TABLE 2 Convention . . . xiv Typographical Conventions Meaning Vertical ellipsis points in an example mean that information not directly related to the example has been omitted. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Contact Information TABLE 2 About This Guide Typographical Conventions Convention Meaning ... Horizontal ellipsis points in statements or commands mean that parts of the statement or command not directly related to the example have been omitted. <> Angle brackets are used in the following situations: • • user-supplied values (variables) cnpAPI elements [] Brackets enclose optional clauses from which you can choose one or more option. bold text Bold text indicates emphasis. Italicized text Italic type in text indicates a term defined in the text, the glossary, or in both locations. blue text Blue text indicates a hypertext link. Contact Information This section provides contact information for organizations within Vantiv Implementation - For certification and technical issues concerning your implementation of cnpAPI or issues encountered during the on-boarding process, call your assigned Implementation Consultant or e-mail to the address below. Implementation Contact Information E-mail implementation@vantiv.com Hours Available Monday – Friday, 8:30 A.M.– 5:30 P.M. EST Technical Support - For technical issues such as file transmission errors, e-mail Technical Support. A Technical Support Representative will contact you within 15 minutes to resolve the problem. Technical Support Contact Information E-mail eCommerceSupport@vantiv.com Hours Available 24/7 (seven days a week, 24 hours a day) Relationship Management/Customer Service - For non-technical issues, including questions Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. xv eProtect™ Integration Guide About This Guide Contact Information concerning the user interface, help with passwords, modifying merchant details, and changes to user account permissions, contact the Customer Experience Management/Customer Service Department. Relationship Management/Customer Service Contact Information Telephone 1-844-843-6111 (Option 3) E-mail ecc@vantiv.com Hours Available Monday – Friday, 8:00 A.M.– 6:00 P.M. EST Chargebacks - For business-related issues and questions regarding financial transactions and documentation associated with chargeback cases, contact the Chargebacks Department. Chargebacks Department Contact Information Telephone 1-844-843-6111 (option 4) E-mail chargebacks@vantiv.com Hours Available Monday – Friday, 7:30 A.M.– 5:00 P.M. EST Technical Publications - For questions or comments about this document, please address your feedback to the Technical Publications Department. All comments are welcome. Technical Publications Contact Information E-mail xvi TechPubs@vantiv.com Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 1 INTRODUCTION NOTE: The PayPage product is now known as Vantiv eProtect™. The term ‘PayPage’ however, is still used in this guide in certain text descriptions, along with many data elements, JS code, and URLs. Use of these data elements, etc., with the PayPage name is still valid with this release, but will transition to ‘eProtect’ in a future release. This chapter provides an introduction and an overview of Vantiv eProtect™. The topics discussed in this chapter are: • eProtect Overview • How eProtect Works • Getting Started with eProtect • Migrating From Previous Versions of the eProtect API • eProtect Support for Apple Pay™ / Apple Pay on the Web • eProtect Support for Android Pay™ • Creating a Customized CSS for iFrame NOTE: The eProtect feature of the Vault Solution operates on JavaScript-enabled browsers only. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 1 eProtect™ Integration Guide Introduction 1.1 eProtect Overview eProtect Overview Vantiv's eProtect solution helps solve your card-not-present challenges by virtually eliminating payment data from your systems. The eProtect solution reduces the threat of account data compromise by transferring the risk to Vantiv, reducing PCI applicable controls. The eProtect feature controls the fields on your checkout page that collect sensitive cardholder data. When the cardholder submits their account information, your checkout page calls eProtect to register the account number for a low-value token, returning a Registration ID--a PCI non-sensitive value--in place of the account number. No card data is actually transmitted via your web server. Vantiv provides three integration options for eProtect: • JavaScript Customer Browser API - controls the fields on your checkout page that hold sensitive card data. When the cardholder submits his/her account information, your checkout page calls the eProtect JavaScript to register the provided credit card for a token. The JavaScript validates, encrypts, and passes the account number to our system as the first step in the form submission. The return message includes the Registration ID in place of the account number. No card data is actually transmitted via your web server. • iFrame API - this solution builds on the same architecture of risk- and scope-reducing technologies of eProtect by fully hosting fields with PCI-sensitive values. Payment card fields, such as primary account number (PAN), expiration date, and CVV value, are hosted in our PCI-Compliance environment, rather than embedded as code into your checkout page within your environment. • Mobile API - allows you to use a eProtect-like solution to handle payments without interacting with the eProtect JavaScript in a browser. With Mobile eProtect, you POST an account number to our system and receive a Registration ID in response. You can use it in native mobile applications--where the cross-domain limitations of a browser don't apply--in order to achieve a similar reduction in risk as eProtect. For more information on PCI compliance and the Vantiv eProtect product, see the Vantiv eProtect iFrame Technical Assessment Paper, prepared by Coalfire IT Audit and Compliance. Figure 1-1 and Figure 1-2 illustrate the difference between the Vault and the Vault with eProtect. See the section, How eProtect Works on page 4 for additional details. NOTE: 2 In order to optimally use the eProtect product for the most risk reduction (i.e., to no longer handle primary account numbers), this feature must be used at all times, without exception. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide eProtect Overview Introduction FIGURE 1-1 Vault FIGURE 1-2 eProtect Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 3 eProtect™ Integration Guide Introduction 1.2 How eProtect Works How eProtect Works This section illustrates the eProtect process. Step 1 1. When your customer is ready to finalize a purchase from your website or mobile application, your web server delivers your Checkout Form to the customer’s web browser or mobile device. Step 2 2. If using the iFrame API, the browser loads the iFrame URL hosted by the eProtect server. If using the JavaScript API, the browser loads the eProtect Client code (JavaScript) from the eProtect server. The API validates credit cards, submits account numbers to the eProtect Service, encrypts account numbers, and adds the Registration IDs to the form. It also contains Vantiv' s public encryption key. (continued on next page) 4 Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide How eProtect Works Introduction Step 3 3. After the customer enters their card number and clicks or taps the submit button, the eProtect API (or POST request) sends the card number data to our eProtect service. The eProtect service submits a Vantiv cnpAPI transaction to the Vault to register a token for the card number provided. The token is securely stored in the Vault for eventual processing (when your payment processing system submits an authorization or sale transaction). A Registration ID is generated and returned to the customer’s browser as a hidden field, or to their mobile device as a POST response. Step 4 4. All of the customer-provided information is then delivered to your web server along with the Registration ID. Your payment processing system sends the payment with the Registration ID, and the Vault maps the Registration ID to the token and card number, processing the payment as usual. The cnpAPI response message contains the token, which you store as you would a credit card. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 5 eProtect™ Integration Guide Introduction 1.3 Getting Started with eProtect Getting Started with eProtect Before you start using the eProtect feature of the Vault solution, you must complete the following: • Ensure that your organization is enabled and certified to process tokens, using the Vault solution. • Complete the eProtect Integration Checklist provided by your Implementation Consultant, and return to Implementation. See Appendix C, "Sample eProtect Integration Checklist". • Obtain a PayPage ID from our Implementation department. • If you are implementing the iFrame solution, create a Cascading Style Sheet (CSS) to customize the look and feel of the iFrame to match your checkout page, then submit the Style Sheet to Vantiv for verification. See Creating a Customized CSS for iFrame on page 14 for more information. • Modify your checkout page or mobile native application--and any other page that receives credit card data from your customers--to integrate the eProtect feature (execute an API call or POST to our system). See one of the following sections, depending on your application: • Integrating Customer Browser JavaScript API Into Your Checkout Page on page 22 • Integrating iFrame into your Checkout Page on page 32 • Integrating eProtect Into Your Mobile Application on page 39 for more information. • Modify your system to accept the response codes listed in Table 1-3, eProtect-Specific Response Codes Received in Browsers or Mobile Devices, and Table 1-4, eProtect Response Codes Received in cnpAPI Responses. • Test and certify your checkout process. See Testing and Certification on page 69 for more information. 1.3.1 Migrating From Previous Versions of the eProtect API 1.3.1.1 From eProtect with jQuery 1.4.2 Previous versions of the eProtect API included jQuery 1.4.2 (browser-based use only). Depending on the implementation of your checkout page and your use of other versions of jQuery, this may result in unexpected behavior. This document describes version 2 of the eProtect API, which requires you to use your own version of jQuery, as described within. If you are migrating, you must: 6 • Include a script tag to download jQuery before loading the eProtect API. • Construct a new eProtect API module when calling sendToEprotect. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Getting Started with eProtect 1.3.1.2 Introduction From JavaScript Browser API to iFrame When migrating from the JavaScript Customer Browser API eProtect solution to the iFrame solution, complete the following steps. For a full HTML code example a iFrame eProtect implementation, see the HTML Example for Hosted iFrame-Integrated Checkout Page on page 78. 1. Remove the script that was downloading eProtect-api2.js. 2. Add a script tag to download eprotect-iframe-client.min.js. 3. On your form, remove the inputs for account number, cvv, and expiration date. Put an empty div in its place. 4. Consolidate the three callbacks (submitAfterEprotect, onErrorAfterEprotect and onTimeoutAfterEprotect in our examples) into one callback that accepts a single argument. In our example, this is called eProtectiframeClientCallback. 5. To determine success or failure, inspect response.response in your callback. If successful, the response is ‘870.’ Check for time-outs by inspecting the response.timeout; if it is defined, a timeout has occurred. 6. In your callback, add code to retrieve the paypageRegistrationId, bin, expMonth and expYear. Previously, paypageRegistrationId and bin were placed directly into your form by our API, and we did not handle expMonth and expYear (we’ve included these inside our form to make styling and layout simpler). 7. Create a Cascading Style Sheet (CSS) to customize the look and feel of the iFrame to match your checkout page, then submit the Style Sheet to Vantiv for verification. See Creating a Customized CSS for iFrame on page 14 and Configuring the iFrame on page 33 for more information. 8. See Calling the iFrame for the Registration ID on page 35 to retrieve the paypageRegistrationId. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 7 eProtect™ Integration Guide Introduction Getting Started with eProtect 1.3.2 Browser and Mobile Operating System Compatibility The eProtect feature is compatible with the following (see Table 1-1, "Apple Pay on the Web Compatible Devices" for information on Apple Pay web): Browsers (when JavaScript is enabled): • Mozilla Firefox 3 and later • Internet Explorer 8 and later • Safari 4 and later • Opera 10.1 and later • Chrome 1 and later Native Applications on Mobile Operating Systems: • Chrome Android 40 and later • Android 2.3 and later • Apple iOS 3.2 and later • Windows Phone 10 and later • Blackberry 7, 10 and later • Other mobile OS IMPORTANT: 1.3.2.1 Because browsers differ in their handling of eProtect transactions, Vantiv recommends testing eProtect on various devices (including smart phones and tablets) and all browsers, including Internet Explorer/Edge, Google Chrome, Apple Safari, and Mozilla Firefox. Communication Protocol Requirement If you are using an MPLS network, Vantiv requires that you use TLS 1.2 encryption. 1.3.3 eProtect Support for Apple Pay™ / Apple Pay on the Web Vantiv supports Apple Pay for in-app and in-store purchases initiated on compatible versions of iPhone and iPad, as well as purchases from your desktop or mobile website initiated from compatible versions of iPhone, iPad, Apple Watch, MacBook and iMac (Apple Pay on the Web). If you wish to allow Apple Pay transactions from your native iOS mobile applications, you must build the capability to make secure purchases using Apple Pay into your mobile application. The operation of Apple Pay on the iPhone and iPad is relatively simple: either the development of a new native iOS application or modification of your existing application that includes the use of 8 Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Getting Started with eProtect Introduction the Apple PassKit Framework, and the handling of the encrypted data returned to your application by Apple Pay. See Using the Vantiv Mobile API for Apple Pay on page 42 for more information. For Apple Pay on the Web, integration requires that thefield be included in the sendToEprotect call when constructing your checkout page with the JavaScript Customer Browser API. See Integrating Customer Browser JavaScript API Into Your Checkout Page on page 22 and Using the Customer Browser JavaScript API for Apple Pay on the Web on page 30 for more information on the complete process. Also, see Table 1-1, Apple Pay on the Web Compatible Devices for further information on supported Apple devices. NOTE: TABLE 1-1 Table 1-1 represents data available at the time of publication, and is subject to change. See the latest Apple documentation for current information. Apple Pay on the Web Compatible Devices Apple Device Operating System iPhone 6 and later iPhone SE iOS 10 and later iPad Pro iPad Air 2 and later iPad Mini 3 and later iOS 10 and later Apple Watch Paired with iPhone 6 and later Watch OS 3 and later iMac Paired with any of the above mobile devices with ID Touch for authentication macOS Sierra and later MacBook Paired with any of the above mobile devices with ID Touch for authentication macOS Sierra and later 1.3.4 Browser Safari only eProtect Support for Android Pay™ Android Pay is an in-store and in-app (mobile or web) payment method, providing a secure process for consumers to purchase goods and services. In-store purchases are done by using Near Field Communication (NFC) technology built into the Android Smart phone with any NFC-enabled terminal at the retail POS. For in-app purchases, the consumer need only select Android Pay as the payment method in your application. You will need to modify your application to use Android Pay as a payment method. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 9 eProtect™ Integration Guide Introduction Getting Started with eProtect Vantiv supports two methods for merchants to submit Android Pay transactions from Web/Mobile applications to the eCommerce platform. The preferred method involves you sending certain Vantiv specific parameters to Google®. The response from Google includes a Vantiv paypageRegistrationId, which you use in you payment transaction submission to Vantiv. With the alternate method, you receive encrypted information from Google, decrypt it on your servers, and submit the information to Vantiv in a payment transaction. See Using the Vantiv Mobile API for Android Pay on page 45 for more information. 1.3.5 eProtect Support for Pay with Google™ Pay With Google is an on-line payment method that lets your customers use the cards they've saved to their Google Account to pay quickly and easily in your apps. and on your websites. By clicking the Pay with Google button, customers can choose a payment method saved in their Google Account and finish checkout in a few, simple steps. You can use the Google Payment API to simplify payments for customers who make purchases in Android apps or on Chrome with a mobile device. Vantiv supports two methods for merchants to submit Pay with Google transactions from Mobile applications to the eCommerce platform. The preferred method involves you sending certain Vantiv-specific parameters to Google. The response from Google includes a Vantiv paypageRegistrationId, which you use normally in your payment transaction submission to Vantiv. With the alternate method, you receive encrypted information from Google, decrypt it on your servers, and submit the information to Vantiv in a payment transaction. See Using the Vantiv Mobile API for Pay with Google on page 48 for more information. 1.3.6 jQuery Version If you are implementing a browser-based solution, you must load a jQuery library before loading the eProtect API. We recommend using jQuery 1.4.2 or higher. Refer to http://jquery.com for more information on jQuery. 1.3.7 Certification and Testing Environments For certification and testing of Vantiv feature functionality, including eProtect, Vantiv uses two certification and testing environments: 10 • Pre-Live - this test environment is used for all merchant Certification testing. This environment should be used by both newly on-boarding Vantiv merchants, and existing merchants seeking to incorporate additional features or functionalities (for example, eProtect) into their current integrations. • Post-Live - this test environment is intended for merchants that are already fully certified and submitting transactions to our Production platform, but wish to perform regression or other tests to confirm the operational readiness of modifications to their own systems. Upon Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Getting Started with eProtect Introduction completion of the initial certification and on-boarding process, we migrate merchants that are Production-enabled to the Post-Live environment for any on-going testing needs. Use the URLs listed in Table 1-2 when testing and submitting eProtect transactions. Sample JavaScripts are available at pre-live, post-live, and production eProtect URLs. The following sample scripts are available: • eProtect JavaScript (eProtect-api2.js) • iFrame Client (eprotect-iframe-client.js) • iFrame JavaScript (eProtect-iframe.js) TABLE 1-2 Environme nt Pre-Live (Testing and Certification) Post-Live (Regression Testing) Live Production 1.3.7.1 eProtect Certification, Testing, and Production URLs URL Purpose URL JavaScript Library https://request.eprotect.vantivprelive.com/eProtect/eProtectapi2.js Request Submission (excluding POST) https://request.eprotect.vantivprelive.com iFrame https://request.eprotect.vantivprelive.com/eProtect/js/eProtectiframe-client.min.js POST Request Submission (for Mobile API) https://request.eprotect.vantivprelive.com/eProtect/paypage JavaScript Library https://request.eprotect.vantivpostlive.com/eProtect/eProtectapi2.js Request Submission (excluding POST) https://request.eprotect.vantivpostlive.com iFrame https://request.eprotect.vantivpostlive.com/eProtect/js/eProtectiframe-client.min.js POST Request Submission (for Mobile API) https://request.eprotect.vantivprelive.com/eProtect/paypage Production Contact your Implementation Consultant for the eProtect Production URL. Pre-Live Environment Limitations and Maintenance Schedule When using the pre-live environment for testing, please keep in mind the following limitations and maintenance schedules: Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 11 eProtect™ Integration Guide Introduction Getting Started with eProtect • The number of merchants configured per organization is limited to the number necessary to perform the required certification testing. • Data retention is limited to a maximum of 30 days. NOTE: Depending upon overall system capacity and/or system maintenance requirements, data purges may occur frequently. Whenever possible, we will provide advanced notification. • Merchant profile and data is deleted after seven (7) consecutive days with no activity. • Maintenance window - each Tuesday and Thursday from 4:00-8:00 AM ET. • Daily limit of 1,000 Online transactions. • Daily limit of 10,000 Batch transactions. NOTE: 1.3.8 Due to the planned maintenance windows, you should not use this environment for continuous regression testing. Transitioning from Certification to Production Before using your checkout form with eProtect in a production environment, replace all instances of the Testing and Certification URLs listed in Table 1-2 with the production URL. Contact Implementation for the appropriate production URL. The URLs in Table 1-2 and in the sample scripts throughout this guide should only be used in the certification and testing environment. 1.3.9 eProtect-Specific Response Codes Table 1-3 and Table 1-4 list response codes specific to the eProtect feature, received in the browser or mobile device, and those received via a cnpAPI Response. For information on response codes specific to token transactions, see the Vantiv cnpAPI Reference Guide. TABLE 1-3 12 eProtect-Specific Response Codes Received in Browsers or Mobile Devices Response Code Description Error Type Error Source 870 Success -- -- 871 Account Number not Mod10 Validation User 872 Account Number too short Validation User 873 Account Number too long Validation User Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Getting Started with eProtect TABLE 1-3 Introduction eProtect-Specific Response Codes Received in Browsers or Mobile Devices Response Code Description Error Type Error Source 874 Account Number not numeric Validation User 875 Unable to encrypt field System JavaScript 876 Account number invalid Validation User 881 Card Validation number not numeric Validation User 882 Card Validation number too short Validation User 883 Card Validation number too long Validation User 884 eProtect iFrame HTML failed to load System Vantiv eComm 885 eProtect iFrame CSS failed load System Vantiv eComm 889 Failure System Vantiv eComm TABLE 1-4 Response Code eProtect Response Codes Received in cnpAPI Responses Response Message Response Type Description 877 Invalid PayPage Registration ID Hard Decline A eProtect response indicating that the Registration ID submitted is invalid. 878 Expired PayPage Registration ID Hard Decline A eProtect response indicating that the Registration ID has expired (Registration IDs expire 24 hours after being issued). 879 Merchant is not authorized for PayPage Hard Decline A response indicating that your organization is not enabled for the eProtect feature. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 13 eProtect™ Integration Guide Introduction 1.4 Creating a Customized CSS for iFrame Creating a Customized CSS for iFrame Before you begin using the iFrame solution, you must create a Cascading Style Sheet (CSS) to customize the look and feel of the iFrame to match your checkout page. After creating and customizing your style sheet, you then submit the style sheet to Vantiv, where it will be tested before it is deployed into production. This section describes the various tools and customizations available for creating your CSS for iFrame and submitting your CSS for review: • CSS iFrame Validation and Customization Features • Using Web Developer Tools • Reviewing your CSS with Vantiv NOTE: 1.4.1 If you are evaluating your styling options and/or having trouble creating your own style sheet, Vantiv can provide sample CSS files. Please contact your assigned Implementation Consultant for sample CSS files. CSS iFrame Validation and Customization Features Vantiv offers a set of iFrame validation and customization features to reduce cart abandonment, increase conversions, and help simplify the payment experience for your customers. See Configuring the iFrame on page 33 for further information on placement of these properties in your checkout page. These features include: Real-Time In-line Field Validations - while traditional web forms use submit-and-refresh rules that respond once you click the Submit button, real-time in-line validations can help your customers fill out web forms faster and with fewer errors. By guiding them with real-time feedback that instantly confirms whether the values they input are valid, transactions can be more successful and less error-prone, and customers are more satisfied with their checkout experience. Payment Form Behaviors - customizable behaviors include: • Empty Input - if your customer clicks back after leaving a payment form (for example, if they want to edit their payment information or in the case of a timeout, etc.), eProtect detects whether your customer has attempted to enter new form data. If they have not entered any new values, you can use the original token for the transaction. If your customer attempts to enter new values, eProtect clears the form—instead of leaving the previous entries in place—eliminating the need to erase the old values before re-entering new values. 14 • Disallowed Characters - allows only numeric values to be entered for the Account Number and CVC fields (no alpha or special characters are permitted). • Auto-Formatting of account numbers based on the type of card. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Creating a Customized CSS for iFrame Introduction Client Driven Behaviors - additional capabilities include: • Tooltips - you can add a tool tip for any field (not just security code) activated by hovering, or when clicking 'What's This?’ • Font Library and Icons - Vantiv hosts SVG Icons (Font Awesome, v4.7.0) font library on our servers for you to leverage in your CSS, using an industry standard icon library for all icons. • Trust Badge - you can add a ‘trust’ badge (e.g., a padlock or shield icon) on the payment form to reassure your customers that your site is legitimate and that all their personal data is collected securely through trusted third-party service providers. Note that the trust badge can be displayed in place of the card graphic; your page cannot display both. Table 1-5, "iFrame Checkout Page Customizations - In-Line Field Validations" and Table 1-6, "Style Sheet and iFrame Customizations" show samples of these CSS iFrame customizations and describes the implementation of each. When you set the optional enhancedUxFeatures.inlineFieldValidations property to true when configuring your iFrame, the behaviors listed in Table 1-5 are all included. TABLE 1-5 iFrame Checkout Page Customizations - In-Line Field Validations Field Validation Behavior Card Number The iFrame checks the card number for correct size (too short or too long) and against the Luhn/Mod10 algorithm. Samples In this example, if the consumer’s inputs are valid, you can configure the iFrame to display green field borders and include a green check mark. Red borders and a red ‘X’ can indicate invalid input. The error messages and frame colors are customizable in your style sheet. The iFrame identifies the card type (Visa, MasterCard, Amex, etc.) based on the first few digits entered, and displays the appropriate card graphic. If the card type is unknown, the iFrame displays a generic card graphic. You can configure your style sheet to hide the card graphic. In addition, the iFrame auto-formats the arrangement of the card digits based on the initial entry. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 15 eProtect™ Integration Guide Introduction Creating a Customized CSS for iFrame TABLE 1-5 iFrame Checkout Page Customizations - In-Line Field Validations (Continued) Field Validation Behavior Samples Expiration Date The iFrame checks the expiration month to determine if the selected month is prior to the current month. Security Code The iFrame confirms the logic against the account number type. For example, if the card is an American Express card and the consumer enters only three digits (should be four digits), an error is indicated. The items listed in Table 1-6 are also available as optional features controlled by the your style sheet and via iFrame function. By default, the Tool Tip features are active, but can be suppressed with the CSS. TABLE 1-6 Style Sheet and iFrame Customizations Customization Samples Trust Badge - You can add a ‘trust badge’ (e.g., a padlock or shield icon) to the payment form, using the Font Awesome (V4.7.0) icon library. Note that the trust badge can be displayed in place of the card graphic; your page cannot display both. Tool Tips - you control the following tool tip behavior in your style sheet: You can add a tool tip for any field (not just security code) activated by hovering, or when clicking 'What's This?’ Tool tip displayed after clicking ‘What’s This?’ 16 Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Creating a Customized CSS for iFrame TABLE 1-6 Introduction Style Sheet and iFrame Customizations (Continued) Customization Samples You can configure your style sheet to activate a tool tip by hovering over the ‘?’ icon (rather than clicking). This is useful for short statements. You can also configure a modal dialog to activate on the click of the second ‘?’ icon to display more lengthy CSS content. Modal dialog displayed upon clicking second ‘?’ icon. Tool Tips (continued) You can configure your CSS to display a Security code modal dialog where the tool tip displays generic card art showing the placement of CVC on cards. You can hide this with the CSS, if you choose. You can also remove the scrollbars, as well as direct your CSS to auto-size the dialog based on content. Modal dialog displayed upon clicking first or second ‘?’ icon at the security code field. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 17 eProtect™ Integration Guide Introduction 1.4.2 Creating a Customized CSS for iFrame Using Web Developer Tools By using standard browser-provided web developer tools, you can develop and customize your CSS prior to sending it to Vantiv for boarding. To access the developer tool and to customize your CSS: 1. Go to https://www.testvantivcnp.com/iframe/ to access the demo URL and review the provided style sheet. If you are using the enhanced iFrame features described in the previous section, CSS iFrame Validation and Customization Features, use the following URL: https://www.testvantivcnp.com/checkout/checkout-iframe-enhanced-demo.jsp 2. Right click the Account Number text field, then click Inspect or Inspect Element (depending on your browser). The browser splits the window into two or more browser-specific developer frames. 3. Locate the highlighted HTML section in the developer tool frame of the browser where it shows …. Expand the section with the arrow icon (if it is not already expanded). 5. Locate the HTML section , which is the last child of the element, and expand it. 6. Double click the content, delete it, then paste in your new style sheet. To make the new CSS style effective, simply click somewhere else to exit the editing mode. 7. Copy and paste the CSS file and send it to your Vantiv Implementation Consultant for review. 1.4.3 Reviewing your CSS with Vantiv Vantiv reviews your CSS by an automatic process which has white-listed allowed CSS properties and black-listed, ‘dangerous’ CSS values (such as URL, JavaScript, expression). Properties identified as such have been removed from the white list, and if used, will fail verification of the CSS. See Table B-24, "CSS Properties Excluded From the White List (not allowed)" for those properties not allowed. If an error is detected, Vantiv returns the CSS for correction. If the CSS review is successful, the CSS is uploaded to the your eProtect configuration. Note the following: 18 • If additional properties and/or values are introduced in future CSS versions, those properties and values will be automatically black-listed until Vantiv can review and supplement the white-listed properties and values. • Certain properties allow unacceptable values, including URL, JavaScript, or expression. This includes the content property, which allows you to enter ‘Exp Date’ instead of our provided Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Creating a Customized CSS for iFrame Introduction ‘Expiration Date’ label. If the property contains a URL, JavaScript, expression, or attr(href), Vantiv will fail verification of the CSS. • Any property in the white list also allows its browser’s extended values, where applicable. See https://www.testvantivcnp.com/iframe/ to view a simple iFrame example. To view an iFrame example checkout page using the enhanced features described in CSS iFrame Validation and Customization Features on page 14, use the following URL: https://www.testvantivcnp.com/checkout/checkout-iframe-enhanced-demo.jsp Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 19 eProtect™ Integration Guide Introduction 20 Creating a Customized CSS for iFrame Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 2 INTEGRATION AND TESTING This chapter describes the steps required to integrate the eProtect™ feature as part of your checkout page, transaction examples, and information on eProtect testing and certification. The sections included are: • Integrating Customer Browser JavaScript API Into Your Checkout Page • Integrating iFrame into your Checkout Page • Integrating eProtect Into Your Mobile Application • Collecting Diagnostic Information • Transaction Examples When Using cnpAPI • Testing and Certification NOTE: The PayPage product is now known as Vantiv eProtect. The term ‘PayPage’ however, is still used in this guide in certain text descriptions, along with many data elements, JS code, and URLs. Use of these data elements, etc., with the PayPage name is still valid with this release, but will transition to ‘eProtect’ in a future release. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 21 eProtect™ Integration Guide Integration and Testing 2.1 Integrating Customer Browser JavaScript API Into Your Checkout Page Integrating Customer Browser JavaScript API Into Your Checkout Page This section provides step-by-step instructions for integrating the Customer Browser JavaScript API eProtect solution into your checkout page. This section also provides information on the foon Using the Customer Browser JavaScript API for Apple Pay on the Web See Integrating eProtect Into Your Mobile Application on page 39 for more information on the mobile solution. See Integrating iFrame into your Checkout Page on page 32 for more information on the iFrame solution. 2.1.1 Integration Steps Integrating eProtect into your checkout page includes these steps, described in detail in the sections to follow: 1. Loading the eProtect API and jQuery 2. Specifying the eProtect API Request Fields 3. Specifying the eProtect API Response Fields 4. Handling the Mouse Click 5. Intercepting the Checkout Form Submission 6. Handling Callbacks for Success, Failure, and Timeout 7. Detecting the Availability of the eProtect API The above steps make up the components of the sendToEprotect call: sendToEprotect(eProtectRequest, eProtectFormFields, successCallback, errorCallback, timeoutCallback, timeout) 22 • eProtectRequest - captures the form fields that contain the request parameters (paypageId, url, etc.) • eProtectFormFields - captures the form fields used to set various portions of the eProtect registration response (Registration Id, response reason code, response reason message, etc.). • successCallback - specifies the method used to handle a successful eProtect registration. • errorCallback - specifies the method used to handle a failure event (if error code is received). • timeoutCallback - specifies the method used to handle a timeout event (if the sendToEprotect exceeds the timeout threshold). • timeout - specifies the number of milliseconds before the timeoutCallback is invoked. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Integrating Customer Browser JavaScript API Into Your Checkout Page Integration and Testing JavaScript code examples are included with each step. For a full HTML code example of the eProtect implementation, see the HTML Checkout Page Examples on page 74. 2.1.2 Loading the eProtect API and jQuery To load the eProtect client JavaScript library from the eProtect application server to your customer's browser, insert the following JavaScript into your checkout page. Note that a version of the jQuery JavaScript library must be loaded by your checkout page before loading the eProtect client JavaScript library. NOTE: To avoid disruption to transaction processing, Vantiv recommends you download the latest JavaScript client to your checkout page a minimum of once per day (due to frequent changes to the JavaScript client). Vantiv does not recommend caching the eProtect JavaScript client on your servers. This example uses a Google-hosted version of the jQuery JavaScript library. You may choose to host the library locally. We recommend using version 1.4.2 or higher. ... production environment. ... Contact Implementation for the appropriate production URL. NOTE: The URL in this example script (in red) should only be used in the certification and testing environment. Before using your checkout page with eProtect in a production environment, replace the certification URL with the production URL (contact your Implementation Consultant for the appropriate production URL). Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 23 eProtect™ Integration Guide Integration and Testing 2.1.3 Integrating Customer Browser JavaScript API Into Your Checkout Page Specifying the eProtect API Request Fields To specify the eProtect API request fields, add four hidden request fields to your checkout form for paypageId (a unique number assigned by Implementation), merchantTxnId, orderId, and reportGroup (cnpAPI elements). You have control over the naming of these fields. NOTE: The orderId field must be a text string with a maximum of 25 characters. The values for either the merchantTxnId or the orderId must be unique so that we can use these identifiers for reconciliation or troubleshooting. The values for paypageId and reportGroup will likely be constant in the HTML. The value for the orderId passed to the eProtect API can be generated dynamically. TABLE 2-1 24 eProtectFormFields Definitions Field Description ccNum (Optional) The credit card account number. cvv2Num (Optional) The card validation number, either the CVV2 (Visa), CVC2 (MasterCard), or CID (American Express and Discover) value. paypageRegistrationId (Required) The temporary identifier used to facilitate the mapping of a token to a card number. bin (Optional) The bank identification number (BIN), which is the first six digits of the credit card number. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Integrating Customer Browser JavaScript API Into Your Checkout Page 2.1.4 Integration and Testing Specifying the eProtect API Response Fields To specify the eProtect API Response fields, add seven hidden response fields on your checkout form for storing information returned by eProtect: paypageRegistrationId, bin, code, message, responseTime, type, and vantivTxnId. You have flexibility in the naming of these fields. ... 2.1.5 Handling the Mouse Click In order to call the eProtect JavaScript API on the checkout form when your customer clicks the submit button, you must add a jQuery selector to handle the submission click JavaScript event. The addition of the click event creates a eProtect Request and calls sendToEprotect. The sendToEprotect call includes a timeout value in milliseconds. We recommend a timeout value of 15000 (15 seconds). This value is based on data that only 1% of traffic exceeds five seconds. If you set your timeout value at 5000 (five seconds), we recommend that you follow up with a longer 15-second timeout value. NOTE: The URL in this example script (in red) should only be used in the certification and testing environment. Before using your checkout page with PayPage in a production environment, replace the certification URL with the production URL (contact your Implementation Consultant for the appropriate production URL). ... ... TABLE 2-2 eProtectRequest Fields Field Description paypageId (Required) The unique number assigned by Implementation. reportGroup (Required) The cnpAPI required attribute that defines under which merchant sub-group this transaction will be displayed in eCommerce iQ Reporting and Analytics. orderId The merchant-assigned unique value representing the order in your system (used when linking authorizations, captures, and refunds, and for retries). Vantiv recommends that the values for id and orderId be different and unique so that we can use these identifiers for reconciliation or troubleshooting. If you do not have the order number available at this time, please generate another unique number to send as the orderId (and send it to your servers to map it to the order number that you generate later). id The merchant-assigned unique value representing this transaction in your system. The same value must be used for retries of the same failed eProtect transaction but must be unique between the eProtect transaction, authorization, capture, and refund for the same order. Vantiv recommends that the values for id and orderId must be different and unique so that we can use these identifiers for reconciliation or troubleshooting. 26 applepay (Optional). The Apple Pay PKPaymentToken. Required for Apple Pay on the Web. url (Required) The URL to request submission for eProtect. See Table 1-2, eProtect Certification, Testing, and Production URLs on page 11. Document Version: 6.6 — cnpAPI Release: V12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide Integrating Customer Browser JavaScript API Into Your Checkout Page 2.1.6 Integration and Testing Intercepting the Checkout Form Submission Without the eProtect implementation, order data is sent to your system when the submit button is clicked. With the eProtect feature, a request must be sent to our server to retrieve the Registration ID for the card number before the order is submitted to your system. To intercept the checkout form, you change the input type from submit to button. The checkout button is built inside of a ... ... 2.1.7 Handling Callbacks for Success, Failure, and Timeout Your checkout page must include instructions on what methods we should use to handle callbacks for success, failure, and timeout events. Add the code in the following three sections to achieve this. 2.1.7.1 Success Callbacks The success callback stores the responses in the hidden form response fields and submits the form. The card number is scrubbed from the submitted form, and all of the hidden fields are submitted along with the other checkout information. ... ... 2.1.7.2 Failure Callbacks There are two types of failures that can occur when your customer enters an order: validation (user) errors, and system (non-user) errors (see Table 1-3, "eProtect-Specific Response Codes Received in Browsers or Mobile Devices" on page 12). The failure callback stops the transaction for non-user errors and nothing is posted to your order handling system. NOTE: When there is a timeout or you receive a validation-related error response code, be sure to submit enough information to your order processing system to identify transactions that could not be completed. This will help you monitor problems with the eProtect Integration and also have enough information for debugging. You have flexibility in the wording of the error text. ... ... 2.1.7.3 Timeout Callbacks The timeout callback stops the transaction and nothing is posted to your order handling system. Timeout values are expressed in milliseconds and defined in the sendToEprotect call, described in the section, Handling the Mouse Click on page 25. We recommend a timeout value of 15000 (15 seconds). You have flexibility in the wording of the timeout error text. ... ... 2.1.8 Detecting the Availability of the eProtect API In the event that the eProtect-api2.js cannot be loaded, add the following to detect availability. You have flexibility in the wording of the error text.