Implementing Barclaycard’s ePDQ CPI in the Zend Framework

We are working on an e-commerce project at the moment (built in Zend), which at it’s commercial core, involves selling digital products to consumers. Our client is using Barclaycard’s ePDQ Cardholder Payment Interface (CPI) to take secure payments from their customers.

ePDQ is well documented by Barclaycard and we had no trouble designing the transaction process for our client. However, when it came to the actual Zend development I was surprised not to be able to locate any existing Zend or even PHP classes online, over and above the simple CURL examples Barclaycard provide in their documentation. Subsequently, when designing the technical ePDQ integration I decided to put my reusability hat on and looked to write a set of Zend assets which we could add to our ever growing UVd Zend library.

The following article outlines how I developed these assets in the context of the ePDQ process. I will make the code available in uvd Labs as well.

User Flow

The diagram below illustrates the user flow when interacting with ePDQ from a generic application.

1. User is presented with a checkout screen in the application, which along with an order summary includes a ‘Continue to payment’ button. When pressed, the user is redirected to the first of two ePDQ CPI screens (CPI 1) to securely input their billing information
2. User inputs their details and presses ‘Submit’
3. User sees result of validation on CPI 2 and is presented with a ‘Continue’ button
4. When pressed, the user is redirected back to the application where they continue with the sales process accordingly

Application Flow

The application logic required to implement the user flow is prescribed by the ePDQ process itself.

1. To access CPI 1, an HTTP POST request must be made which contains a strict set of variables. These are both supplier specific (e.g. the application’s merchant ID) and transaction specific (i.e. order number or total value). These must be sent to the CPI encrypted, so before the checkout screen is outputted to the user, a server side call must be made to ePDQ to encrypt the details. The configuration of the CPI, (including client Logo, whether delivery address is required, currency, pre-populated fields etc) is all based on the data supplied in this POST request; the most straight forward way to implement this being an HTML form.
2. Once the user enters their details and presses submit, two things happen. The CPI performs its verification on the transaction itself. The CPI performs a callback to the application via a POST request to a specific script. This URL must be the same for every transaction (it can’t contain OID for example) and must be protected behind the HTTP Basic authentication mechanism. It also must NOT require a port number to be specified (as I found out the hard way). The callback body contains the results of the user’s credit card verification and allows the application to perform the necessary processing such as write to a log file or database. The user will not be presented with CPI 2 until ePDQ has received a response from the application, so it is preferable to perform a minimum amount of processing here.
3. Once the user presses continue on CPI 2, they will be redirected to a URL on the application (this URL can be transaction specific). As far as ePDQ is concerned the transaction is now complete, so the application can handle the user’s return based on the results of the callback function.

Implementing ePDQ in Zend

Based on the application and user flows of the ePDQ process, what areas lend themselves to generating reusable assets? Its clear that anything application specific such as models (i.e. sales orders or products), views (such as the checkout) should be left to the specific application to implement. Similarly, once a user is directed back to the application, any ePDQ involvement is now over so there wouldn’t be much in terms of reusable code at (3) above. However, the initial encryption request and the callback are specifically controlled by the ePDQ process, making them good candidates.

So, in terms of building reusable assets in a Zend application, what options do you have?

• Controllers
• Modules
• Library Classes
• Services
• Action Helpers
• View Helpers

From my experience of building assets in Zend you want something that:

• is fairly self contained (whereas controllers perhaps are not so good, modules are self contained)
• suits all types of implementations (our Services provide our Doctrine integration so wouldn’t suit all applications)
• are easy to make application agnostic (plugins and classes are)
• can be developed with caching in mind

Having digested the technical documentation from Barclaycard and after thinking long and hard about Zend, I decided the best approach would be to develop:

1. A library class – UVd_Commerce_Epdq_Service (Epdq_Service)
2. A plugin – UVd_Commerce_Epdq_Plugin (Epdq_Plugin)

Zend Application Integration

The following diagram outlines how these assets integrate into a Zend implementation of the ePDQ process.

1. Generating the checkout view

In order to render the checkout view, the checkout controller instantiates Epdq_Service. This collects application specific variables (merchant Id) from an epdq .ini file and all transaction specific variables are passed by the controller. Epdq_Service makes the server side HTTP request (I used Zend_Http_Request, using CURL). Once this is received the Checkout controller can call htmlify() on the object and an html form will be generated.

2. Processing the callback

ePDQ needs the URL of the callback function (which you configure in the ePDQ admin interface). This URL is stored in the epdq.ini as a collection of module, controller and action names, however the actual controller does not need to exist in your application. Epdq_Plugin looks at the ini file and intercepts any calls made to this combination; this is checked using the dispatchLoopStartup hook. The plugin provides the HTTP authentication mechanism and then calls Epdq_Service to perform basic processing on the results, which is a simple log to a text file. Each application will want to process this result differently so the advantage of this approach is that all application specific code can be put into an actual controller with the same name.

3. User exits ePDQ

The user will then press continue and will be redirected to a URL on your application that is transaction specific. It makes sense to include the OID in here so the application knows how to continue with the user flow. I am also storing this in a session to prevent URL tampering.
I hope this has proven a useful resource for anyone using ePDQ with Zend. I will also make my final code available in uvd Labs so look out for that!

This entry was posted on June 23rd, 2011 and is filed under Tips & Tricks, Tutorials and tagged as: e-commerce, frameworks, PHP, Zend.

You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response or Trackback from your own site.