ActiveMerchant is a very useful library for connecting to payment gateways. However it is also quite dated, with many flaws, and lack of proper documentation in one part (offsite-payment). In my experience, I feel it can be improved in the following ways:

The name “integration” in confusing, and makes it diffcult to search online. The gem should be split into two, one for on-site payment (gateway/billing module), and one for off-site payment (integration/Billing::Integration module). This is because the two are very different ways of paying. It can be confusing when you search for solutions but it turns out to be not what you want. Seems Shopify is alreadying doing that, splitting the offsite-payment module into its own gem. Good move!

The semantic of common fields in form helper need to be defined. Otherwise implementors will choose different names for the same concept, greatly reducing the interchangeability between gateways. Some consistency issues should also be fixed. For example in Paypal we pass our order id as the “order” field, and Paypal notification will return that as item_id attribute. This mismatch is confusing.

The gross() currently does not specify a return type. Paypal returns a string. Base class says it should “the money amount we received in X.2 decimal”. Though there is a amount() method for returning a money object, the gross() method should still specify the return type to avoid inconsistencies when switching gateways.

The base framework code should be separated from gateway implementations. Users usually just want two or three gateways out of the 50 implementations. Having a separate repository per gateway also makes it easier to document gateway specific changes and settings in separate readme files.

There should be a check() method in the notification. It acts as the central method to check if the notification is valid. Currently there are many which implemented the acknowledge() function. However not all providers provide an API to verify the notification. With the generalized check() method it can call acknowledge() if it is implemented.

Adding hooks for form helper would be helpful. Many gateways require post-processing such as adding a checksum field. A hook would allow the interface to automatically call these post-processing instead of the developer having to remember calling them in view.