Implementing eProtect to secure payments

Document created by gjsissons on Apr 11, 2016Last modified by gjsissons on May 12, 2016
Version 5Show Document
  • View in full screen mode

Vantiv’s eProtect is a solution to help secure payments by avoiding the need for applications to be exposed to sensitive cardholder data at the point of data capture.


There are multiple approaches to implementing eProtect:

  • For developers integrating directly with Vantiv’s Enterprise Payment Platform, Vantiv implementation consultants can help deploy eProtect as a part of a reliable, high-volume payment solution suitable for tier-one merchants.
  • Developers can also implement eProtect themselves using Vantiv's eCommerce APIs, and test applications against the eCommerce sandbox.


How Vantiv eProtect iFrame Works


  1. When customers are ready to enter their cardholder data into a merchant's web page, the merchant web server presents a form to the customer's web browser and loads the iframe containing content hosted by the Vantiv eProtect server.
  2. Customers enter their PAN, optional security code, and optional expiration date into the iframe fields and click the submit button on the merchant's page calling the eProtect server, and returning a non-sensitive, single-use token called a Registration ID in place of the Primary Account Number (PAN).
  3. The merchant page submits the Registration ID and non-cardholder data elements to its web server for order processing.
  4. Once the authorization request arrives at Vantiv, the Registration ID is converted to an OmniToken, and returned to the merchant in the authorization response.


No cardholder data is ever transmitted to a merchant’s server, since this page never had access to the information submitted via the Vantiv eProtect iFrame.


Vantiv eProtect Benefits:


Risk Transference – By properly implementing Vantiv’s data security solutions, merchants can transfer the risk of handling sensitive cardholder data to Vantiv.


Making Compliance Easier - Tokenization reduces the merchant's cardholder data footprint as those systems are not exposed to clear cardholder data.


Seamless Integration – Token values are seamlessly integrated with all payment acceptance and value added services including account updating, authorization recycling, fraud toolkit, fraud chargeback prevention services (FCPS), and customer insight data services. Vantiv’s reporting is fully integrated with Tokenization features allowing for easier reporting and reconciliation.


Vantiv provides developers with three integration options for eProtect depending on their needs and preferred approach.


  • Vantiv-Hosted 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-Compliant 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 PayPage Registration ID in place of the account number. No card data is actually transmitted via your web server.
  • Mobile API The eProtect Mobile Native Application allows you to use eProtect 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 PayPage Registration ID in response. You can use it in native mobile applications where the cross-domain limitations of a browser don't apply, to avoid handling card data in your application.




In the example below, we show how this functionality is implemented using the Vantiv-Hosted iFrame API. In this example fields containing sensitive data are hosted by Vantiv and exposed via an iFrame.


Load the eProtect code

The eProtect code depends on jQuery. The correct jQuery libraries can either be stored on the customer’s web-server or loaded from Vantiv’s secure servers. The eProtect interface exposed via an iFrame is referred to as the PayFrame.

To load the PayFrame from the application server to your customer's browser, insert the following script tag into header section of the checkout page. The PayFrame client code in this example is being loaded from Vantiv’s pre-live server.


  <script src=""></script>


Configure the iFrame

The next step is to configure the iFrame code loaded above. After the page is loaded, specify required properties (some properties shown in the example below, are optional). Define a callback for errors, time-outs, and to retrieve the paypageRegistrationId. In this example, this is called payframeClientCallback. This is also where developers can style elements in the iFrame so that fields blend in seamlessly with other fields on the page.


$( document ).ready(function() { 
     var configure = { "paypageId":document.getElementById("request$paypageId").value, 
                              "div": "payframe", "callback": payframeClientCallback, 
                              "showCvv": true, 
                              "months": { "1":"January", "2":"February", "3":"March", "4":"April", "5":"May", "6":"June", "7":"July", "8":"August",
                                                   "9":"September", "10":"October", "11":"November", "12":"December" }, 
                              "numYears": 8, 
                              "tooltipText": "A CVV is the 3 digit code on the back of your Visa, MasterCard and Discover or a 4 digit code on the front of your American Express",
                          "tabIndex": { "cvv":1, "accountNumber":2, "expMonth":3, "expYear":4 }, 
                    "placeholderText": { "cvv":"CVV", "accountNumber":"Account Number" } }; 
     if(typeof LitlePayframeClient === 'undefined') { 
          alert("We are experiencing technical difficulties. Please try again or call us to complete your order"); 
          //You may also want to submit information you have about the consumer to your servers to facilitate debugging like customer ip address, user agent, and time
     } else { 
          var payframeClient = new LitlePayframeClient(configure); payframeClient.autoAdjustHeight();


Calling the iFrame for the eProtect Registration ID

After the customer clicks the Submit/Complete Order button, the checkout page must call the iFrame to get a Registration ID. In the onsubmit event handler of your button, add code to call eProtect to get a Registration ID for the credit card and CVV as shown:


document.getElementById("fCheckout").onsubmit =  function(){
  var message = {
 payframeClient.getPaypageRegistrationId(message); return false; }


Handling Callbacks


After the iFrame has received the paypageRegistrationId, or has received an error or timed out, the iFrame calls the callback specified when the client was constructed. In your callback, you can determine success or failure by inspecting response.response (870 indicates success). You can check for a timeout by inspecting response.timeout (if it is defined, a timeout has occurred)


Additional details and code examples are provided in the eProtect Integration Guide and the eProtect Enterprise Integration Guide available to Vantiv ONE members in the eCommerce documentation.