Getting Started with WorldPay eProtect

Blog Post created by scottfitzpatrick on Apr 23, 2019

Financial account data is considered to be some of the most important and sensitive data in existence. And in today’s world, it is also among the most commonly requested data on the Internet. Let’s face it — everybody shops online. And online shopping requires merchants to request payment data from the shopper. This presents inherent risks associated with providing financial data using online forms. It is due to these risks that a high importance has been placed on protecting user payment data.




So, how can we reduce the risk of compromising account data and ensure a positive experience for users visiting an online store? WorldPay has the solution in the form of eProtect.


WorldPay eProtect provides merchants with a solution for card-not-present processing risks, allowing the merchant to protect shopper payment data, and providing application developers with several API solutions that are both secure and easy to implement.


This article walks through what eProtect does and how it works.

What is eProtect and how does it protect account data?


As mentioned above, WorldPay eProtect is a solution for reducing the risks associated with card-not-present (cnp) payment processing. But you may be wondering exactly how it reduces these risks. WorldPay eProtect assumes the responsibility for protecting payment data through several solutions. These include hosting the fields that hold this payment data, as done through use of the iFrame API, or through calls on form submit to the eProtect JavaScript API that passes the payment information from form fields hosted on the application web server to the eProtect server for processing. In short, through the use of an eProtect API, the transmission of sensitive data by the application web server is rather limited.


For our purposes, let’s take a closer look at the eProtect iFrame API. Through the use of this API, the fields that will hold sensitive account data are embedded on the page using an iFrame. This iFrame is hosted by the eProtect server. When the user submits the account data (card number, CVV value, expiration date), this data is submitted to the eProtect server rather than transmitted via your own web server.

This eProtect server is a PCI-compliant environment to ensure data security. The moment eProtect receives the card data, it triggers a cnpAPI call to register a token with the Vault where the account data is securely stored. It is this token that will be used for retrieving account data when the payment is processed. The eProtect server then returns a registration ID to the web page. Finally, when the actual payment has been authorized, the registration ID and payment information is sent to the Vault. The Vault then uses this registration ID to efficiently find the token and card number, and processes the payment securely. This transaction simply returns the previously registered token that can be stored by the client as they would card data. This ensures that no actual account data is stored by the client, significantly reducing the risk of an issue due to compromised user account information.


Implementing eProtect from WorldPay


One of the most encouraging parts of utilizing eProtect from WorldPay is the ease in which the solution can be implemented in a web application. Sticking with the iFrame API solution that we discussed above, let’s take a look at some sample code where an iFrame running code hosted by the eProtect server is embedded in a payment page in a web application to allow account data to be processed via the secure, PCI-compliant eProtect environment.


The first step in implementing the iFrame solution from eProtect is to include the jQuery library. After that, we also need to ensure that we have included the client JavaScript for the eProtect iFrame API. This is done by adding a script tag to download the JS from the following URL:


It should be noted that this URL is not for production use. For the sake of this example, I utilized the “pre-live” URL from the eProtect documentation.


The final steps from an HTML perspective are as follows. We will need to include the div element representing the iFrame to be embedded on the web page. In the screenshot of the sample code, you can see that it is assigned the ID attribute iFrameElem. This will be important when configuring the iFrame via custom JavaScript. In addition, we need to include form fields for holding attributes of the response from the eProtect service. Hidden fields such as that shown below in the screenshot (input with ID attribute response$paypageRegistrationId) are added to the form to assign values with the JavaScript. And finally, we need to provide ourselves with a spot to write some custom JS for instantiating the iFrame and handling the response. We do so by creating impl.js to properly configure the iFrame.  Finally, we download this custom JS file as represented by the last script tag in the head container of our HTML file.


eProtect code 1


In the custom JavaScript associated with the example, two important actions need to take place. First, the iFrame needs to be configured so that it can be properly added to the checkout page. Next, the response from the eProtect server must be handled to retrieve what is known as the paypageRegistrationId — the registration ID that will be sent with payment information to the Vault post-authorization to map to the account data and process the payment.


In configuring the iFrame, several properties are required. These required properties include the following:

  • paypageId - ID value provided by WorldPay
  • reportGroup - required by cnpAPI for reporting purposes
  • style - Custom CSS for styling the iFrame
  • timeout - Allotted time in milliseconds before the call times out
  • div - ID value of the HTML div where the iFrame is embedded (in our case: iFrameElem)
  • callback - the function to call for handling the response from the eProtect server


Please see the screenshot below for the portion of impl.js representing the configuration of the iFrame. Notice the line that instantiates iFrameElem passing the configuration JSON to construct the iFrameElem object.


 eProtect 2


The next step in the process is to handle the response from eProtect in our callback function. In our particular example, this is the function called iFrameElemCallback. A key element in the callback response is the paypageRegistrationId as that is what will be used by the cnpAPI to locate the associated token and card information in the Vault when processing the actual payment.


In the screenshot below, you will see the defined callback function. This is used to check the response code, handle the response data, and submit the form. The snippet below shows the first two steps. The hidden form field for paypageRegistrationId has the value set after we check and find that the call to eProtect has been successful. Other attributes of the response object can be handled in the same manner. This success response is defined by the response code 870, which we check for prior to setting the hidden form field value and submitting the form. Additional response codes and additional information on the response object from the eProtect service can be found in the eProtect online documentation.


 eProtect 3



Storing payment data that is later compromised is among the worst possible events that can happen to an Internet merchant. It damages the trust necessary for a merchant to be successful. WorldPay eProtect can help in mitigating the risks associated with collecting payment data, ensuring that shoppers have a positive experience and feel comfortable engaging in future transactions.