Chronicling my experiences with ruby on rails, web application development/management.

Sunday, November 16, 2008

Recurring Payments using PayPal Express and Active Merchant

I needed a payment solution that took recurring payments for my rails app. Most of the tutorials out there use either a US based merchant account provider, or are based in the UK. I guess canadians are out to lunch. Oh, and what's worse was that none of them really touched on subscription based models, or as it turns out, recurring payments.

Caveat: Now i am not here to take credit for what I'm about to write. I only write this post as a 'mashup' of two great men and their tutorials on the subject. I just took these two tutorials and used the good from both of them to come up with what you are about to read.

The fine men who authored these posts

Cody Fauser - Active Merchant extraordinaire

Cody is from all accounts the man, if not only the public face, of Active Merchant. His Active Merchant Peepcode pdf (a must read and only 9 bucks!) is the go to guide for learning all about Active merchant from the man himself.

Jon Baker - Paypal Express Recurring Payments add on for Active Merchant Plugin

From his homepage"As well as leading the Rich internet Application at Trigger Software Ltd, he is CEO and Entrepreneur of Vibrant Apps a small company based in Cornwall that makes useful and useable apps."

On with the show...

Basically, i used the framework from Cody's Paypal Express Payments with Active Merchant for my controller/view actions and I used the plugin extension from Jon's post Paypal Express Recurring Payments using Active Merchant.

The sum of these two parts became what i needed to get a basic subscription for my app, and now for you too.

Gimme the High Level overview nerbie69!

Will do. Oh, and i assume you already know how to create a rails app, and that you are following usual rails behaviour and will know that everything in here is based off of being inside your rails app, when you run any code. This tutorial is probably above beginners so i assume anyone reading this kinda knows what they are doing and are just stuck at how to implement subscription based models easily.

  1. Create your Paypal Sandbox developer account and instantiate an API credential from your seller account

  2. Install Active Merchant from github

  3. Insert Jon Baker's Paypal express Recurring Payments nv . rb file in your new Active Merchant plugin

  4. Create your controller and views

  5. Test your new subscription model in your browser

  6. Pinch yourself... it was that easy.

So there you have it. It's the simple steps version of what you are about to do.

Step One - Create your paypal sandbox developer account

Go to to set up your paypal developer account.
You can find better instructions on the developer site, but it isn't too hard and out of scope for this tutorial. However, make sure you get the api credentials from the Seller account(_biz). I.e., you must log in as the seller, in the sandbox, and follow Cody's instructions on how to set up the API.

Step Two - Install Active Merchant

Go to github and install the Active Merchant plugin: script/plugin install git:// I'm using the plugin here because it's easier to add a file, which is the next step.

Step Three - Adding the paypal_express_recurring_nv.rb file to Active Merchant

Download or copy and paste the following file paypal_express_recurring_nv.rb and put it in the following directory: /vendor/plugins/active_merchant/lib/active_merchant/billing/gateways/

The plan is to get this into active merchant in a future release. We all have a part in making sure this happens, by emailing activemerchant's maintainers and saying how helpful this was. Plus then we can fix any bugs and extend to make it even better.

Step Four - Create your controller and views in your rails app

From here on out is where i mashed the two tutorials together. First create your controller and views: script/generate controller subscriptions index confirm cancel error

Now add the following, as Cody says, to the top of your application.rb controller
include ActiveMerchant::Billing
Also, don't forget to put your ActiveMerchant into test mode, as outlined in his tutorial.

I'll paste the full controller code, so you can see it in all it's glory. Notice, as Cody says, we didn't need a view for checkout, so that is why we didn't add 'it', to the generate code above.class SubscriptionsController < ApplicationController
def index

def cancel

def error


# Confirmation step is the actual step that sends money.
def confirm
response = gateway.create_profile(999, params[:token], :reference => "34")
if !response.success?
@message = purchase.message
render :action => 'error'
# The checkout method used to pass the values to paypal. The description is shown to the user in their paypal account.
def checkout
setup_response = gateway.setup_agreement("Monthly subscription fee $9.99 USD",
:return_url => url_for(:action => 'confirm', :only_path => false),
:cancel_return_url => url_for(:action => 'index', :only_path => false)
redirect_to gateway.redirect_url_for(setup_response.token)
#Here's the gateway info.
def gateway
@gateway ||=
:login => '',
:password => 'W32RW53TE64Y7',
:signature => 'A90EWQRLSDA0SA.SAD0FASWEQ4ls0sl20S0SLD0.223.w'


The views are easy to setup and obviously could say anything. Here is what i did, to get a generic subscription message setup:

# Index.html.erb:

< h1 >Site Subscription< /h1>
< p >Thank you for your decision to subscribe to this site.

< p >Your order total is $9.99 / month

< p >
< % = link_to image_tag(''), :action => 'checkout' % >
< / p >

The error messages can stay the same as what cody has, i believe.

The confirm view really doesn't have to say anything other then Thanks! All the magic happens in the controller when the response comes back. I know that i am probably going to add my own app specific controller functions to this confirm, such as creating their profiles and setting certain site variables, now that they have subscribed to become 'one of the cool kids'

Step Five - Test in your browser and revel at your genius

That heading says it all.

Thanks for reading and enjoy.

I hope that you enjoyed this little tutorial. Subscription handling hasn't been easier thanks to Jon Baker, active merchant and all their hard work.


  1. ok, but what should I do when new month is came? How can I get information is user payed or not in next months?

  2. Great Question. There are a couple of methods i haven't had the opportunity to play with yet that may AID in answering this question, however, i personally would use the paypal interface for this account management stuff.

    Once i launch my new app, i'll be tackling these kinds of questions shortly and will post "Day 2 support" or "How to administer your paying customers after the first month".

  3. So, good questions. that got me thinking i need to write a day two support system for subscription based apps.

    how to handle a client with an expired credit card #, after the Paypal profile is created. (say five months, a year and a half from now). I think that is where IPN comes in and i have some ideas on letting new IPN messages log in an app... or worse, would be to run a profile_id lookup on all of the id's at once...

    I still like using the paypal management link to manage the credit card/day to day stuff, it just would be nice to suspend users upon certain IPN notifications.

  4. @nerbie69

    Just to let you know I am having to re-write my extension to Active Merchant as Cody and the guys have deprecated the base classes used for connection to the PayPal API. I have some new ones in the works that will work over SOAP and hopefully these will be officially accepted into the ActiveMerchant framework.

    You can keep up with this here:

  5. thanks for the update jon. when the dust settles, (i get the emails from lighthouse on this ticket), i'll write a followup post based on your new work. I've got one or two more ideas on how to establish views etc, that i'd like to incorporate in the new post too. Best of luck/skill!

  6. Payolee offer simple recurring payments.