David J Rice

As promised in my previous article, I would be releasing the Realex code for ActiveMerchant, a gracious thanks to Ticketsolve who funded this development. So, the code currently resides in my fork of ActiveMerchant at github which you can clone and use in your applications straight away, it should hopefully make it’s way back into the official ActiveMerchant repository soon enough.

gateway = ActiveMerchant::Billing::RealexGateway.new

credit_card = ActiveMerchant::Billing::CreditCard.new({
  :name => "John Smith", 
  :month => "9", 
  :year => "2009", 
  :type => :visa, 
  :number => "1111222233334444", 
  :verification_value => "xxx"
})

response = gateway.purchase(100, credit_card, {})

For further usage documentation;

• See the main Realex gateway class
• The unit tests
• The remote integration test

Enjoy.

View Comments

This article has been ammended to clarify and expand on some of my initial thoughts after receiving more of an in-depth response than I thought the article would provoke, from David Lowry of webpayments.ie (also, previously a developer at Realex).

Recently one of the projects I’ve been working on has involved writing a fuller implementation of the Realex Payment Gateway to work with Active Merchant. If you haven’t heard of it, Active Merchant is a Payment Gateway abstraction library written in Ruby. The aim is to provide a universal set of methods to interact with a whole host of different implementations. The library revolves around 5 key methods of interaction, they are;

• purchase (money, creditcard, options = {})
• authorize (money, creditcard, options = {})
• capture (money, authorization, options = {})
• void (identification, options = {})</tt>
• credit (money, identification, options = {})

There are also two additional methods for working with recurring payments but there is less support for this among merchants. The original implementation of the Realex Gateway for Active Merchant was written by John Ward and included the ability to perform purchase requests. I have since added to it to allow the other core methods, I’ll be releasing this update to Active Merchant soon. If you ask nicely, I might add in support for taking recurring payments.

After finishing this work, I’m not 100% happy with it. Why? Because Realex do things differently than most of the other gateway services. For no good reason either, as in my opinion none of the differences I’m going to list below give any benefit to the customer. I would say, this is from the standpoint of someone integrating payment solutions into a SaaS application with the goal of it being easily used with a different merchant per client. This is especially necessary as they have a global market.

Your needs may vary, if your business is selling directly to customers, thus all transactions go direct to you then there is less benefit in being able to use multiple gateways. However I do think the same principles of abstraction that make ORM libraries and frameworks a staple of modern software development should also apply to cloud computing services and APIs. Of course security is definitely a major concern when dealing with payments (which is why we use merchants in the first place) but I believe strongly that the security should be inherent and that the merchant should do as much as possible to make their interface as simple as possible and extra features optional. So, here’s my list of differences between Realex and other gateways that I have used with ActiveMerchant that make it not possible to provide a good, abstracted solution;

1. Unique Transaction Identifiers
2. Requiring Extra Identifiers
3. Requiring a Secondary Password for Credits
4. Public Developer Information Portal
5. Test Gateway
6. Industry Standard Valid Test Card Numbers

Unique Transaction Identifiers

Okay, so a merchant should always generate a unique identifier at their end for the transaction and so should the application that is talking to it (as we most likely want to save that Order to the database before it is paid for, I do however agree with the implementation of ActiveMerchant which states that specifying an order identifier should be optional. At the end of the day it’s all about minimum requirements there would definitely be no loss of functionality in simply saving the auto generated identifier from Realex and doing lookups that way, or providing your own order id back as extra trackability.

Requiring Extra Identifiers

So as I mentioned above I agree that you should only need one key to uniquely identify a transaction. With most of the other gateway implementations in ActiveMerchant you need only give them the transaction identifier (or authorization code) and that is good enough. However with Realex you are required to send back to them;

• The unique transaction identifier you specified
• The unique transaction identifier from Realex
• The authorization code

So this would be quite against the essence of abstraction, surely one of these is enough after all the point of a unique identifier is that it is the key required to retrieve a result. David Lowry quite rightly pointed out in his article that the authorization code (being generally around 4 digits) is not a unique identifier, however it would be a unique identifier for a given batch. Seeing as it would only be possible to Capture a previously authorized transaction before the batch is processed. So, considering that I think it is fair to say this is all that should be required to identify it. Voiding or Crediting a transaction, as they could take place further down the line should require a unique id.

Requiring a Secondary Password for Credits

Previously I had stated that Realex require you to send them an extra element in your request for a Credit a password specifically for performing refunds. As David Lowry pointed out in his article that this is to prevent attacks specifically "such attacks could be as simple as a rogue employee carrying out refunds to a card of their choice.". I would definitely agree that it is an important aspect of application security to prevent possible theft within your organisation. In the context of a back office application I think that encapsulating this as part of your own application logic and only allowing certain users to perform refunds is better from a usability standpoint, from talking to people working with this exact scenario actually making the users of the backend office system enter a password created a lot more support requests because of forgotten passwords or confusion between it and their login to the application itself.

Anyway after more research this appears to be an optional feature and is only required if it has been enabled on a given account.

Public Developer Information Portal

In my opinion it is generally a good business move if you are providing software as a service to give as much information to potential customers to increase customer aquisition through awareness and knowledge of your service. This also has another benefit of reducing the ammount of support requests that staff have to be available to provide answers for. Even if you wish to capture customer details initially you could still allow users to get to step one without needing to get a staff member on the line. The feeling of progress is always a good thing to create a good customer experience.

Test Gateway

Another vitally important part of SaaS is integration testing. Unless you are maintaining all the libraries for using your service in different programming languages, I think it is essential to enable easy integration testing to ensure the robustness of the implementations. So allowing users to at least sign up for a test account straight away and get the unit tests for an implementation running is a good thing, this is especially useful for libraries that are open source.

I also think it’s a good idea to have this hosted at a different server especially as it’s in the sensitive data category. This way any access to sensitive data or communication with banks can be completely removed, the test service effectively becoming a mock implementation of the real thing providing a full range of different responses for all input data and also a list of test input data.

David Lowry points out that "why should an organization allow unkown parties to access their test servers?", security is an issue but I believe that segregating the test service from the live service plus having other server side functionalities such as monitoring API requests, IP addresses and creating warnings based on rate limits etc. is an acceptable solution, this is only a small example of the many paths to increasing security and monitorability of a web service. He also mentions that not having a separate test service "eliminates the risk of possible differences between test and live environments." in my opinion it shouldn’t be a big issue to ensure that the interfaces behave the same, it would be the merchants perogative to ensure quality of their code among builds. He also says that "switching from test mode to live mode is greatly simplified" I would say that point is moot as if anything changing the base url for your payment gateway i.e. changing the value of a string is arguably easier than adding an xml node and therefore shouldn’t factor into why a company doesn’t provide test access.

Industry Standard Valid Test Card Numbers

So, there are many card numbers that work across many other merchants for testing purposes. They’re generally well documented in the gateway’s developer site and can therefore be used in your unit tests, for your open source library or your application that’s integrating with it… you are writing unit tests right? Anyway, unfortunately Realex provide test card numbers on a per account basis so it makes things more awkward to write tests for a library that other people will use.

• They need to get a merchant account
• They need to get their set of test card numbers
• Copy and paste their card numbers into a test fixture file
• Run the unit tests

Again, it’s down to the user experience again. When I’m taking the time to create workflows I always like to see if there is a way to improve and simplify them. If we have 4 steps, could we get that down to 1 or 2?

Conclusion

The combined effect of those differences, make for a user experience as a potential customer of theirs that could be improved quite a bit. Also, it means that the end result implementation for Active Merchant needs to work slightly differently for Realex gateways therefore going against the whole aim of the library. If it sounds like these things aren’t that big a problem? Consider the scenario that you are an Irish SaaS provider and have a new client in the US you want to release your e-commerce site to.

With a well abstracted implementation of the Realex gateway, they would be able to simply add a configuration setting to use any other merchant they wish for this new customer and still allow their existing customers to use Realex. The quality and testability of code would be excellent as both backend gateways are receiving the same data, not to mention the ease of the change. However without abstraction the application needs another layer of code to handle the differences for the Realex gateway.

This is certainly not useful for a potential customer who would wish to utilise Realex & other merchants as well as the extra layer of code is just more to maintain and in my opinion doesn’t need to be there. However you could say that it isn’t really in the interest of any business to enable them to easily switch to their competitors… but I doubt that’s the reason for Realex’s differences. Actually this is an interesting point that I will cover at some point but I do believe there is great benefit for a company to show people how easy it is to get out of the service they are signing up for.

So in the interest of finding a gateway for Irish customers that would allow a well abstracted solution, I’ve looked into a lot of the competitors and have found that Sagepay is probably the best looking I found (formerly Protx, they recently moved fully support transactions in Ireland). They also appear to tick the boxes for the right way of doing things for every point I’ve raised above so I’m very interested in seeing how they compare.

Anyway, happy payment systems integration. Check back soon if you want to get at the Realex Active Merchant code I promised.

View Comments