Recurring billing with Rails and ActiveMerchant: Best practices, pitfalls, gotchas?

Question

We are prepping for the release of a large web application that has been in development for the past year. We are about to start the process of integrating ActiveMerchant to handle recurring subscription fees for the service.

I am looking for any advice regarding best practices considering our requirements (listed below) and any additional heads-up for common pitfalls or specific issues I should be giving special consideration. The payment gateway we will be using is PaymentExpress as it's one of the few supported gateways that has recurring billing and doesn't have any special conditions for companies operating outside of the USA. The business behind this application is based out of the UK.

Users of the application create an account with a sub-domain where they can access and customise the application and their data. Below are some of the requirements/features that might have an effect on how billing works:

• All users get a 30 day trial
• There are different plans, including a free one
• Higher priced plans have larger limits on the amount of data (e.g. users, projects, etc) they can have in their account
• Billing period will be monthly, beginning after trial
• There will be discounts/coupon codes to get a percentage off the normal price for a year on plans, etc.
• Plan pricing will change as features are added

Specific hurdles I can foresee will be things including the following:

• How to handle downgrading when they violate the plan limits for lower level plans.
• Behaviour when credit cards expire or payments don't go through (a read-only mode enforced, perhaps)
• When plan pricing changes, we want to honour previous prices for existing users for a time period (such as 6 months), then start charging higher rates. If the plan price decreases, it will take effect immediately.

Other advice that would be helpful would be anything regarding flow of the application. How should billing forms be presented to the user? When should credit card information be required? How should invoices be sent, stored, and accessible?

I should disclose that we plan to base a lot of the code base off SaaSy. SaaSy is designed to be used as a separate Rails app that handles all the signup and account management side of things. However, this doesn't work for us since we never planned for this from the beginning and it would be a tedious process to adapt our application to work like that. Consequently, we'll be pulling code and ideas from SaaSy and merging them into our app, a considerably less tedious task.

Answer 1

One thing I wanted to add: keep in mind you don't need to use the recurring billing feature that is built into the gateway. In general these systems are legacy and very difficult to deal with, we get spoiled in the rails world.

You get a lot more flexibility just using them for one purpose (to bill a credit card, and perhaps also store credit cards for PCI compliance). Then roll your own recurring billing in your rails app with a cron job, a date field for when they are paid through, and amount each person is paying (in case they used a coupon) etc.

One small example: sometimes people will cancel a monthly subscription in the middle of the month. They want to make sure they don't forget to cancel before the next payment. Most gateway recurring billing that I've seen will instantly terminate the account (or send you a message indicating this). In reality, the user has paid through the end of the month and should be given 2 more weeks of access. You can do this if you have rolled your own recurring billing in rails, but not if you are using the gateway recurring billing. Just a small example.

Answer 2

RailsKits has a Software as a Service kit that should do what you need. It has built-in support for free trials, upgrading, downgrading, plan limits, etc., and it supports PaymentExpress (and some others).

I've researched it a bit for a project I'm doing, but I haven't purchased it yet so I can't vouch for it. However, I have seen a few blog posts praising this kit.

While the RailsKit is relatively inexpensive when compared what it would cost you to implement all of its features yourself, there are a couple open source versions out there that aim to accomplish the same thing. The one I remember off the top of my head is called Freemium.

EDIT: I forgot to mention that Ryan Bates said in his most recent Railscast that his next episode or two will deal with recurring billing, so keep an eye out for that. He usually does one episode per week, and the five he's done since December 22 all cover handling payments of different types.

Answer 3

Peepcode has a PDF for sale(70 pages) that details various aspects of payment processing and industry practices for this. It may be worth checking out:

http://peepcode.com/products/activemerchant-pdf

Answer 4

I'm also in the middle of setting up a subscription based website and these are our current requirements. They may help you regarding best practice:

• Users will be able to choose one of the subscription plans.
• Users will be required to enter their credit card details to sign up to their chosen plan.
• All major credit and debit cards must be accepted including Maestro and American Express.
• Each plan will have a 30-day free trial so users' credit cards should only be charged after the 30-day period expires. However, the validity of credits cards should be checked at the time of sign up.
• Users will be emailed a few days before their credit card is charged to notify them that they will be charged soon unless they cancel their account. If they cancel their account within their 30 day free trial, their credit card should not be charged.
• After any free trial period, users will be charged in advance for their use of the system - ie they will pre-pay.
• Users will be charged automatically every month for their chosen plan. Each month, users will be sent an email a few days in advance to notify them that they will be charged. Once payment has been made, users will be emailed an invoice showing that their payment has been received.
• Users will be able to upgrade or downgrade their accounts at any time. When users upgrade/downgrade, their next subscription charge will be at the new rate. Users will only be able to downgrade their accounts to a plan that can handle their data. For example, if they currently have 10 active projects they can't downgrade to the Basic plan because the Basic plan only allows 5 projects. They will have to delete or archive 5 projects before you they can downgrade to Basic.
• Users will be able to log in to their account and change or update their credit card details.
• Users will be able to cancel their account at any time. There will be no further subscription charges after a user has canceled their account. However, users will not be refunded for part of the month they have already paid for.
• All parts of the payment system must be 100% PCI DSS compliant; including any 3rd party systems.
• The payment system must support automated notification and retry of failed subscription renewals.
• The payment system must support discount vouchers with expiry dates.
• Credit card details must not be processed by or stored on our servers
• they should always be processed/stored by our 3rd party payment processing partner. We do not want responsibility for securing these details and complying with legal rules and regulations.
• Users will be able to log into their accounts and see a full billing history including dates and amounts paid. We will also need to be able to log in to a system to see customer payment plans and payment history. This will be essential for customer service.

We've also been looking at http://chargify.com/ which looks like it could save a lot of coding time.