Vantiv EProtect Integration Guide Enterprise E Protect V2.7
User Manual: Pdf
Open the PDF directly: View PDF .
Page Count: 150
Download | |
Open PDF In Browser | View PDF |
eProtect™ Integration Guide - Enterprise January 2018 cnpAPI Release V12.0 eProtect API V3.0 Document Version: 2.7 Vantiv eProtect™ Integration Guide Document Version: 2.7 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 .............................................................................................................v Revision History .................................................................................................................v Document Structure ..........................................................................................................xi Documentation Set ...........................................................................................................xi Typographical Conventions ............................................................................................. xii Contact Information.......................................................................................................... xii 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 eProtect Support for Visa Checkout™ ...................................................................... 10 Getting Started with Visa Checkout .................................................................... 10 Requirements for Using Visa Checkout .............................................................. 11 jQuery Version .......................................................................................................... 12 Certification and Testing Environment ...................................................................... 12 Pre-Live Environment Limitations and Maintenance Schedule ........................... 13 Transitioning from Certification to Production ........................................................... 14 eProtect-Specific Response Codes .......................................................................... 14 eProtect Registration ID Duplicate Detection............................................................ 15 Creating a Customized CSS for iFrame.......................................................................... 16 CSS iFrame Validation and Customization Features................................................ 16 Using Web Developer Tools ..................................................................................... 20 Reviewing your CSS with Vantiv............................................................................... 20 Chapter 2 Integration and Testing Integrating Customer Browser JavaScript API Into Your Checkout Page ...................... 24 Integration Steps ....................................................................................................... 24 Loading the eProtect API and jQuery........................................................................ 25 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. iii eProtect™ Integration Guide - Enterprise Contents Specifying the eProtect API Request Fields ............................................................. 26 Specifying the eProtect API Response Fields........................................................... 27 Handling the Mouse Click ......................................................................................... 27 Intercepting the Checkout Form Submission ............................................................ 29 Handling Callbacks for Success, Failure, and Timeout............................................. 30 Success Callbacks .............................................................................................. 30 Failure Callbacks................................................................................................. 31 Timeout Callbacks............................................................................................... 32 Detecting the Availability of the eProtect API............................................................ 32 Using the Customer Browser JavaScript API for Apple Pay on the Web.................. 33 Using the Customer Browser JavaScript API for Visa Checkout .............................. 35 Adding Visa Checkout to the eProtect Customer Browser JavaScript API ............... 36 Requesting and Configuring the API Key and externalClientId........................... 36 Sending Vantiv the Required Fields .................................................................... 37 Integrating iFrame into your Checkout Page .................................................................. 38 Integration Steps ....................................................................................................... 38 Loading the iFrame ................................................................................................... 38 Configuring the iFrame.............................................................................................. 39 Calling the iFrame for the Registration ID ................................................................. 41 Calling the iFrame for the Checkout ID ..................................................................... 42 Notes on the PCI Non-Sensitive Value Feature .................................................. 43 Handling Callbacks ................................................................................................... 43 Handling Errors ................................................................................................... 44 Integrating eProtect Into Your Mobile Application........................................................... 46 Creating the POST Request ..................................................................................... 46 Sample Request.................................................................................................. 47 Sample Response............................................................................................... 48 Using the Vantiv Mobile API for Apple Pay ............................................................... 48 Creating a POST Request for an Apple Pay Transaction ................................... 51 Sample Apple Pay POST Request ..................................................................... 52 Sample Apple Pay POST Response................................................................... 53 Using the Vantiv Mobile API for Visa Checkout ........................................................ 53 Sending Vantiv the Required Fields .................................................................... 55 Sample Visa Checkout POST Request............................................................... 55 Sample Visa Checkout POST Response ............................................................ 56 Using the Vantiv Mobile API for Android Pay............................................................ 56 Using the Vantiv Mobile API for Pay with Google ..................................................... 59 Collecting Diagnostic Information ................................................................................... 62 Transaction Examples When Using ISO 8583, 610, HHMI, and PWS ........................... 63 Vantiv Online Systems - Acquirer ISO 8583 Message Format ................................. 64 Vantiv Online Systems - 610 Message Format......................................................... 67 iv Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Contents Response ............................................................................................................ 68 (HHMI) Host-to-Host Format ..................................................................................... 70 Payment Web Services (PWS) External Payments .................................................. 71 Transaction Examples When Using cnpAPI ................................................................... 75 Transaction Types and Examples............................................................................. 75 Authorization Transactions........................................................................................ 76 Authorization Request Structure ......................................................................... 76 Authorization Response Structure ...................................................................... 77 Sale Transactions ..................................................................................................... 79 Sale Request Structure ....................................................................................... 79 Sale Response Structure .................................................................................... 80 Register Token Transactions .................................................................................... 82 Register Token Request ..................................................................................... 82 Register Token Response................................................................................... 83 Force Capture Transactions...................................................................................... 84 Force Capture Request....................................................................................... 84 Force Capture Response .................................................................................... 85 Capture Given Auth Transactions ............................................................................. 86 Capture Given Auth Request .............................................................................. 86 Capture Given Auth Response ........................................................................... 88 Credit Transactions ................................................................................................... 89 Credit Request Transaction ................................................................................ 89 Credit Response ................................................................................................. 90 Testing and Certification ................................................................................................. 92 Testing eProtect Transactions .................................................................................. 93 Appendix A Code Samples and Other Information HTML Checkout Page Examples .................................................................................... 98 HTML Example for Non-eProtect Checkout Page .................................................... 98 HTML Example for JavaScript API-Integrated Checkout Page................................. 99 HTML Example for Hosted iFrame-Integrated Checkout Page............................... 102 Information Sent to Order Processing Systems ............................................................ 106 Information Sent Without Integrating eProtect ........................................................ 106 Information Sent with Browser-Based eProtect Integration .................................... 106 Information Sent with Mobile API-Based Application Integration ............................ 107 cnpAPI Elements for eProtect....................................................................................... 108 cardValidationNum.................................................................................................. 109 checkoutId............................................................................................................... 110 expDate................................................................................................................... 111 paypage .................................................................................................................. 112 paypageRegistrationId ............................................................................................ 113 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. v eProtect™ Integration Guide - Enterprise Contents registerTokenRequest............................................................................................. 114 registerTokenResponse .......................................................................................... 115 token ....................................................................................................................... 116 Appendix B CSS Properties for iFrame API CSS Property Groups ................................................................................................... 118 Properties Excluded From White List............................................................................ 132 Appendix C Sample eProtect Integration Checklist Index vi Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. ABOUT THIS GUIDE This guide provides information on integrating eProtect, which, when used together with Omnitoken, will reduce your exposure to sensitive cardholder data and significantly reduce your risk of payment data theft. 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 Release All 1.1 Updated with revised URL for sample POST. 2.2 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. v eProtect™ Integration Guide - Enterprise About This Guide TABLE 1 Doc. Version 1.2 Revision History Document Revision History (Continued) Description Location(s) Updated to include Vantiv-Hosted PayPage iFrame solution (many changes and re-arrangement of sections). Also includes addition of Appendix B, and new HTML and JavaScript samples in Appendix A, PayPage iFrame Solution (many changes and re-arrangement of sections). All ‘Migrating From Previous Versions of the PayPage API.’ ‘PayPage Certification, Testing, and Production URLs for mobile POST.' Example for credit response code mappings for ISO 8583. 1.3 Support for PCI Non-Sensitive values through PayPage. Updating Handling Callbacks section for handling errors differently depending on whether they are user error (recoverable) and non-user error (non-recoverable). 1.4 Added link for iFrame CSS demo site. Added PayPage iFrame-Specific Response Codes. Added new optional Common Property parameters for configuring iFrame. Sections 2.1.5, 2.2.4, 2.2.5, 2.3.1, 2.3.1.1 Sections 1.3.6, 1.3.7, 2.2.3, 2.2.5, 2.3.1 Updated code to reflect revisions. Updated information on testing URLs and User Agent examples. 1.5 Added new Native Applications on Mobile Operating Systems. Added step for JavaScript Browser API to Vantiv-Hosted iFrame on creating cascade style sheet. 1.6 Updated product name in applicable areas throughout the guide from PayPage to eProtect (Phase 1). Updated many instances of PayFrame to iFrame. Updated the eProtect workflow diagrams and steps. Sections 1.3.2, 1.3.1.2 ALL, Sections 1.1, 1.3.4, Documentation Set, Chapter 2 Change term to iFrame from Vantiv-Hosted. Update with applicable support & contact information. 1.3.4 - Corrected iFrame link in Certification and Testing Environments. Added Online Developer Platform (ODP). vi Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Revision History TABLE 1 About This Guide Document Revision History (Continued) Doc. Version Description Location(s) 1.7 Added information on obtaining CSS sample files from Vantiv. Chapter 1, Appendix B Increased recommended transaction timeout value to 15000 (15 seconds) from 5000 (five seconds). Chapter 2, Appendix A and C 'CC Num - Token Generated' field has '1' value replaced with '' to avoid PCI sensitive values within document. Appendix A, Section 1.3 Updated the paypageRegistrationId value to ‘1111222233330001.’ Section 2.3.1.2 Added information on using the pciNonSensitive value in the iFrame and POST requests. Sections 2.2.4 and 2.3.1 1.9 Added information on maximum length and data type for orderId and id parameters. Sections 2.1.3, 2.2.4, and 2.3.1 1.10 Added additional information on the PCI non-sensitive value. Section 2.2.4. 1.11 Re-arranged the example section and added a note related to eProtect and PWS (only available to existing PWS customers). Section 2.6 Removed the sample JavaScripts in Appendix A. Sample scripts are available at the pre-live, post-live, and production eProtect URLs. Section 1.3.4, Appendix A.3 Added information on LitleXML elements, example transactions, response codes used for eProtect. Section 1.3, 2.6, 2.7, Appendix A Added notes to LitleXML transaction examples related to expiration dates (required for eProtect transactions). Section 2.7 1.13 Added information on loading the JavaScript API (must be loaded daily to your checkout page). Chapter 2 1.14 Added notes to recommend eProtect testing using different devices and all browsers. Chapter 1 and 2 1.8 1.12 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. vii eProtect™ Integration Guide - Enterprise About This Guide TABLE 1 Doc. Version Document Revision History (Continued) Description Location(s) Added information on API V3 JavaScript (updated URLs and code examples); updated the XML examples to reference LitleXML 11.0. Chapter 1 and 2 Updated testing information with card numbers; added information on testing on multiple devices and browsers. Chapter 2 Updated the descriptions of id and orderId fields/elements. Chapter 2 Added a table of TPS Response Codes to the example section for the 610 messaging format. Chapter 2 Added recommendation on avoiding ‘Flash of Un-styled Content’ (FOUC) issues. Chapter 2 1.16 Added information on new support for Apple Pay and Android Pay. Chapter 1 and 2 2.0 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 Added additional information on using the eCommerce option in 610 messages. 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.; also changed instances of ‘LitleXML’ to ‘’ due to change in product name. All Updated cnpAPI version to 11.1. Chapter 2 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 Added information on support for Visa Checkout™. Note: the new sections are for information purposes only, as Visa Checkout is not generally available with this release. Chapter 1 and Chapter 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 1.15 2.1 2.2 viii Revision History Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Revision History TABLE 1 Doc. Version About This Guide Document Revision History (Continued) Description Location(s) Added information on the new CVV low-value token (checkoutId) feature for iFrame and JS Customer Browser API, including new response codes, checkoutIdMode and the getCheckoutId function. Chapter 1 and 2 Added information on the new cnpAPI element,. Appendix A Removed information and the URL for post-live regression testing as it is not applicable to Enterprise merchants. Chapter 1 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 Removed notes on non-general availability for Visa Checkout; it is now generally available to all merchants. Chapter 1 and 2 Added information on eProtect Registration ID Duplicate Detection. Chapter 1 Added information on required communication protocol. Chapter 1 Corrected some instances of ‘eProtect’ in code samples. Appendix A 2.5 Minor correction to code examples in section A.1.3. Appendix A 2.6 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.9, Creating a Customized CSS for iFrame for better clarification. Chapter 1 Added information on new CSS-allowed Appearance properties. Appendix B 2.3 2.4 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. ix eProtect™ Integration Guide - Enterprise About This Guide TABLE 1 Doc. Version 2.7 x Revision History Document Revision History (Continued) Description Location(s) Re-arranged and relocated the Creating a Customized CSS 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 Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Document Structure About This Guide 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, 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. 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 For additional information, see the following Vantiv documentation: • Acquirer ISO 8583 Message Format (Effective 02.15.2017) • Vantiv Online Systems 610 Interface Reference Guide (Effective 02.15.2017) • HHMI: Host-To-Host Format Specification (Effective Date 02.15.2017) "" NOTE: • Using eProtect in combination with PWS is available to existing PWS customers only. Payment Web Services (PWS) External Payments Developers' Guide (V6.1.2) – Payment Web Services (PWS) Release Notes v6.1.2 and higher – Payment Web Services (PWS) Frequently Asked Questions • Vantiv cnpAPI Reference Guide Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. xi eProtect™ Integration Guide - Enterprise About This Guide Typographical Conventions Typographical Conventions Table 2 describes the conventions used in this guide. TABLE 2 Typographical Conventions Convention . . . Meaning Vertical ellipsis points in an example mean that information not directly related to the example has been omitted. ... 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) XML 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 technical assistance related to eProtect issues encountered during the testing and certification process, please contact your assigned Vantiv Conversion Manager or eProtect Implementation Consultant. If you do not have an assigned Implementation Consultant, please contact your Relationship Manager. Vantiv Contact Center - For technical issues related to eProtect in production. Contact 1-866-622-2390 Hours Available 24/7 (seven days a week, 24 hours a day) Relationship Management- For non-technical issues, please contact your Vantiv Relationship Manager. xii Document Version: 2.7 — cnpAPI Release: 12.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™ • eProtect Support for Pay with Google™ • eProtect Support for Visa Checkout™ • Creating a Customized CSS for iFrame Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 1 eProtect™ Integration Guide - Enterprise Introduction 1.1 eProtect Overview eProtect Overview Vantiv's eProtect and OmniToken solutions help solve your card-not-present challenges by virtually eliminating payment data from your order handling systems, transferring the ownership to Vantiv and reducing PCI applicable controls. The eProtect feature controls the fields on your checkout page that hold sensitive card data. When the cardholder submits their account information, your checkout page calls the eProtect JavaScript to register the provided credit card for a token. The JavaScript API 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. Vantiv ensures high service availability for eProtect by implementing primary and secondary endpoints (i.e., routing to a secondary site if the primary site is unavailable). High availability is supported when using the eProtect JavaScript API V.3; it is not available for the Mobile API option. Vantiv provides three integration options for eProtect: • iFrame API - this solution builds on the same architecture of risk- and PCI 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 CVV2 values are hosted from our PCI-Compliance environment, rather than embedded as code into your checkout page within your environment. • 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. • Mobile API - eProtect Mobile Native Application allows you to use the eProtect solution to handle payments without interacting with the eProtect JavaScript in a browser. With Mobile Native Application, 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--to replace payment card data from your web servers. 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 illustrates eProtect with Omnitoken. See the section, How eProtect Works on page 4 for additional details. NOTE: 2 In order to optimally use the eProtect feature for risk reduction, this feature must be used at all times, without exception. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise eProtect Overview FIGURE 1-1 Introduction eProtect Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 3 eProtect™ Integration Guide - Enterprise 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise How eProtect Works Introduction Step 3 3. After the customer enters their card number and clicks or taps the submit button, the eProtect APIs sends the card number data to our eProtect service which calls our Security Services vault or submits a cnpAPI transaction to register an OmniToken for the card number provided. The token is securely stored in Enterprise Security Services for 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 for web processing, 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 Enterprise Security Services vault maps the Registration ID to the OmniToken and card number, processing the payment as usual. The response message from the applicable Vantiv front end contains the OmniToken value, which you store as you would a credit card. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 5 eProtect™ Integration Guide - Enterprise Introduction 1.3 Getting Started with eProtect Getting Started with eProtect Before you start using the eProtect feature, you must complete the following: • Ensure that your organization is enabled and certified to process OmniTokens, using the OmniToken solution. • Complete and return 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 your eProtect Implementation Consultant. • 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 16 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 24 • Integrating iFrame into your Checkout Page on page 38 • Integrating eProtect Into Your Mobile Application on page 46 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 Transaction Examples When Using ISO 8583, 610, HHMI, and PWS on page 63 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise 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 102. 1. Remove the script that was downloading eProtect-api3.js. 2. Add a script tag to download eprotect-iframe-client3.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 16 and Configuring the iFrame on page 39 for more information. 8. See Calling the iFrame for the Registration ID on page 41 to retrieve the paypageRegistrationId. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 7 eProtect™ Integration Guide - Enterprise 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise 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 the field 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 9 eProtect™ Integration Guide - Enterprise 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 56 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 59 for more information. 1.3.6 eProtect Support for Visa Checkout™ Visa Checkout™ is a digital payment service in which consumers can store card information for Visa, MasterCard, Discover, and American Express cards. Visa Checkout provides quick integration for merchants that want to accept payments from these card holders. Visa Checkout is flexible and imposes only a few requirements for its use, leveraging your existing environments--web site and mobile applications--where you add Visa Checkout buttons to existing pages and implement business and event logic using programming languages, tools, and techniques in the same way you currently do. Vantiv supports Visa Checkout purchases from your website or mobile app. initiated from compatible devices. 1.3.6.1 NOTE: 10 Getting Started with Visa Checkout Parts of this section are excerpts from Visa Checkout documentation and represents data available at the time of publication of this document, and is therefore subject to change. See the latest Visa documentation (https://developer.visa.com/products/visa_checkout/reference) for current information. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Getting Started with eProtect Introduction The simplest approach to integrating Visa Checkout takes three steps and can be done entirely from your web page (with the exception of decrypting the consumer information payload on a secure server). Figure 1-2 illustrates the main steps for getting started with Visa Checkout. FIGURE 1-2 Getting Started with Visa Checkout 1. Place a Visa Checkout button on your web page and include the necessary JavaScript to handle events associated with the button. 2. Handle the payment event returned by Visa Checkout by decrypting the consumer information payload. 3. Update Visa Checkout with the final payment information after the payment has been processed. All integration options require that you perform step 1. Sections in this document describes the method using Vantiv eProtect. 1.3.6.2 Requirements for Using Visa Checkout This section describes the various requirements for using Visa Checkout. • Usage and Placement of Visa Checkout Buttons: You are required to implement the Visa Checkout branding requirements on all pages where the consumer is presented payment method options, such as Visa Checkout or another payment method. Common examples include shopping cart page, login page, product page, and payment page. Your actual implementation depends on your specific flow. You can use Visa Checkout on any web page or in any flow on your site or native mobile application where a consumer is asked to type in their billing and payment information. Common examples include cart pages (both full and mini) pages, payment pages, card-on-file management pages, or immediately before a flow where a consumer is prompted for personal information, which may be available, at least partially, within Visa Checkout. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 11 eProtect™ Integration Guide - Enterprise Introduction Getting Started with eProtect See the latest Visa Checkout Integration Guide for more information and to learn how placing Visa Checkout buttons on the shopping cart page and your login page might work. • Clickjacking Prevention Steps: To prevent clickjacking of your pages, each page must contain JavaScript to verify that there are no transparent layers, such as might be the case if your page was loaded as an iFrame of a page containing malicious code, and that only your site can load your pages. See the latest Visa Checkout Integration Guide for more information on preventing clickjacking. • Obtaining the externalClientId from Vantiv: During the on-boarding process, Vantiv Implementation assigns an externalClientId to denote the relationship between Vantiv, your organization and Visa. • Updating Visa Checkout with the Payment Information: After you finish making a payment (and perhaps using the information from the payload), you must update the payment information in Visa Checkout. To update Visa Checkout from a Thank You page (next page to load after making the payment), you add a one-pixel image to the page. For more information about the Update Payment Info pixel image, see the latest Visa Checkout Integration Guide. See additional information on Using the Customer Browser JavaScript API for Visa Checkout on page 35 and Using the Vantiv Mobile API for Visa Checkout on page 53. 1.3.7 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.8 Certification and Testing Environment For certification and testing of Vantiv feature functionality, Vantiv uses the Pre-Live testing environment. 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. Use the URLs listed in Table 1-2 when testing and submitting eProtect transactions. Sample JavaScripts are available at pre-live and production eProtect URLs. The following sample scripts are available: 12 • eProtect JavaScript (eProtect-api3.js) • iFrame Client (eprotect-iframe-client3.js) • iFrame JavaScript (eProtect-iframe.js) Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Getting Started with eProtect TABLE 1-2 Introduction eProtect Certification, Testing, and Production URLs Environment URL Purpose URL Pre-Live (Testing and Certification) JavaScript Library https://request.eprotect.vantivprelive.com/eProtect/eProtectapi3.js Request Submission (excluding POST) https://request.eprotect.vantivprelive.com iFrame https://request.eprotect.vantivprelive.com/eProtect/js/eProtectiframe-client3.min.js POST Request Submission (for Mobile API) https://request.eprotect.vantivprelive.com/eProtect/paypage API Key Request (Visa Checkout only) https://request.eprotect.vantivprelive.com/eProtect/keys.json Production Contact your Implementation Consultant for the eProtect Production URL. Live Production 1.3.8.1 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: • 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 - every other Thursday from 10:00 PM to 6:00 AM ET. • Daily limit of 1,000 Online transactions. • Daily limit of 10,000 Batch transactions. NOTE: Due to the planned maintenance windows, you should not use this environment for continuous regression testing. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 13 eProtect™ Integration Guide - Enterprise Introduction 1.3.9 Getting Started with eProtect 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 the above table and in the sample scripts throughout this guide should only be used in the certification and testing environment. 1.3.10 eProtect-Specific Response Codes Table 1-3 lists response codes specific to the eProtect feature, received in the browser or mobile device, and those received via the applicable Vantiv message specification responses. Table 1-4 lists those received via a cnpAPI Response. For further information on response codes specific to token transactions, see the publications listed in Documentation Set on page xi. TABLE 1-3 14 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 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 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Getting Started with eProtect NOTE: TABLE 1-4 Response Code Introduction For information on response codes specific to OmniToken transactions, see the applicable Vantiv message interface specification. eProtect Response Codes Received in cnpAPI Responses Response Message Response Type 826 Checkout ID was invalid Soft Decline An eProtect response indicating that the Checkout ID submitted was too long, too short, non-numeric, etc. 827 Checkout ID was not found Soft Decline An eProtect response indicating that the Checkout ID submitted was expired, or valid but not found. 828 Generic Checkout ID error Soft Decline There is an unspecified Checkout ID error; contact your Relationship Manager. 877 Invalid PayPage Registration ID Hard Decline An eProtect response indicating that the Registration ID submitted is invalid. 878 Expired PayPage Registration ID Hard Decline An 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. 1.3.11 Description eProtect Registration ID Duplicate Detection Vantiv performs duplicate detection reviews on all form fields such as the card number, CVV, order ID, and Transaction ID. In the event that multiple eProtect registrations are submitted within a five-minute period containing identical form fields, subsequent requests are flagged as duplicates, and processed by returning the originating callback response and Registration ID value. With this, false positives may occur if your organization has not implemented a policy that provides a unique Order ID and Transaction ID for every request. If not implemented, you could potentially receive an incorrect CVV value, which could be disruptive to chargeback processing. Vantiv strongly recommends that the order ID and transaction ID data elements be unique for every registration request. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 15 eProtect™ Integration Guide - Enterprise 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. 16 • 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 17 eProtect™ Integration Guide - Enterprise 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?’ 18 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 19 eProtect™ Integration Guide - Enterprise 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: 20 • 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise 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 16, use the following URL: https://www.testvantivcnp.com/checkout/checkout-iframe-enhanced-demo.jsp Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 21 eProtect™ Integration Guide - Enterprise Introduction 22 Creating a Customized CSS for iFrame Document Version: 2.7 — cnpAPI Release: 12.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 ISO 8583, 610, HHMI, and PWS • 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 23 eProtect™ Integration Guide - Enterprise 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 following payment methods: • Using the Customer Browser JavaScript API for Apple Pay on the Web • Using the Customer Browser JavaScript API for Visa Checkout See Integrating eProtect Into Your Mobile Application on page 46 for more information on the mobile solution. See Integrating iFrame into your Checkout Page on page 38 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) 24 • 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, Checkout 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). Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Integrating Customer Browser JavaScript API Into Your Checkout Page Integration and Testing • 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. 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 98. 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: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 25 eProtect™ Integration Guide - Enterprise 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 hidden request fields to your checkout form for paypageId (a unique number assigned by eProtect Implementation), merchantTxnId, orderId, and reportGroup (cnpAPI elements). Optionally, you can include the checkoutId when CheckoutIdMode is set to true. 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 26 eProtectFormFields Definitions Field Description ccNum (Optional) The credit card account number. Not applicable when checkoutIdMode is set to true. 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. Not applicable when checkoutIdMode is set to true. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Integrating Customer Browser JavaScript API Into Your Checkout Page TABLE 2-1 Integration and Testing eProtectFormFields Definitions Field Description checkoutId (Optional) The low-value token ID exchanged for the CVV value, when checkoutIdMode is set to true. (Checkout Id Mode can be used when you store the high-value token (Registration Id) on file for a consumer, but still want that consumer to populate the CVV with each eProtect transaction.) bin (Optional) The bank identification number (BIN), which is the first six digits of the credit card number. Not applicable when checkoutIdMode is set to true. 2.1.4 Specifying the eProtect API Response Fields To specify the eProtect API Response fields, add hidden response fields on your checkout form for storing information returned by eProtect: paypageRegistrationId, checkoutId, 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. If the response from the primary server takes more than five (5) seconds, the request is automatically sent to our Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. 27 eProtect™ Integration Guide - Enterprise Integration and Testing Integrating Customer Browser JavaScript API Into Your Checkout Page secondary server. To ensure the secondary server has time to respond, we recommend a timeout value of 15000 (15 seconds). 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). ... ... TABLE 2-2 28 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. Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Integrating Customer Browser JavaScript API Into Your Checkout Page TABLE 2-2 Integration and Testing eProtectRequest Fields (Continued) Field Description 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). 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. id 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. checkoutIdMode (Optional) Determines whether checkoutId mode is activated. Setting the value to true causes only the cvv2 form field to be exchanged with eProtect, and returns a checkoutId upon a successful callback (instead of the paypageRegistrationId). 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 13. 2.1.6 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. ... ... 30 Document Version: 2.7 — cnpAPI Release: 12.0 © 2018 Worldpay, Inc. - All Rights Reserved. eProtect™ Integration Guide - Enterprise Integrating Customer Browser JavaScript API Into Your Checkout Page 2.1.7.2 Integration and Testing 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 14). 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 27. 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-api3.js cannot be loaded, add the following to detect availability. You have flexibility in the wording of the error text.