Rails 3.2 example application with recurring billing using Stripe. Use for a Rails membership site, subscription site, or SaaS site (software-as-a-service). Using:
- Devise authentication and user management
- CanCan authorization for administrator access
- Twitter Bootstrap front-end framework for CSS styling
- Stripe for recurring billing and subscription management
Best of all, there’s a detailed tutorial to show how it’s built.
You can build this application in only a few minutes using the Rails Composer tool.
Follow the project on Twitter: @rails_apps. Please tweet some praise if you like what you’ve found.
An in-depth tutorial is available (subscription required). Subscriptions provide financial support for the RailsApps project.
You can use the starter app without getting the tutorial. The tutorial provides a detailed explanation of the code:
The tutorial documents each step to follow to create the application. Every step is documented concisely, so a complete beginner can create this application without any additional knowledge. However, no explanation is offered for any of the steps, so if you are a beginner, you’re advised to look for an introduction to Rails elsewhere. See a list of recommended resources for Rails.
Membership sites restrict access to content such as articles, videos, or user forums. Software-as-a-service (SaaS) sites limit use of web-based software to paid subscribers. The revenue model is the same whether the site provides high-value content or software as a service: A visitor purchases a subscription and gains access to restricted areas of the site. Typically, the subscription is repurchased monthly through a service that provides recurring billing.
The example application provides a complete and fully functional membership site.
- tiered pricing for multiple subscription plans
- optional “free trial” subscription as well as free accounts using Stripe
- uses Stripe for no local credit card storage
- Stripe accepts credit card payments from customers in any country or currency
- PCI compliance using the Stripe JavaScript library
- Stripe handles recurring billing, retries if payment fails, and cancels subscription if retries fail
- paid subscriptions are created only after a successful credit card transaction
- subscribers can upgrade or downgrade subscription plans
- subscribers can cancel subscription plans
- configurable subscription renewal period (defaults to one month)
- administrator can change subscription plan or delete user
There are additional features you may want for a SaaS application, such as:
- Basecamp-style subdomains (each user gets their own subdomain)
- multitenancy database segmentation
These features are not included in this application. See the rails3-subdomains example application for help with subdomains. For multitenancy, try Brad Robertson’s Apartment gem.
This is one in a series of Rails example apps and tutorials from the RailsApps Project. See a list of additional Rails examples, tutorials, and starter apps.
This example application is based on the rails3-bootstrap-devise-cancan starter application. This example application uses ActiveRecord and a SQLite database with RSpec and Cucumber for testing.
This application is similar to the rails-recurly-subscription-saas application which provides recurring billing using the Recurly billing service.
You might also be interested in the rails-prelaunch-signup example and tutorial from the RailsApps project.
- Andrew Culver’s koudoku Rails generator to create a subscription application with Stripe
- Bruno Bornsztein’s striped_rails subscription site as a Rails engine
- Alex Peachey’s striped_rails starter app for a subscription site
- Stripe’s monospace-rails sample application
Before generating your application, you will need:
- The Ruby language (version 1.9.3 or 2.0.0)
- The Rails gem (version 3.2.13)
See the article Installing Rails for advice about updating Rails and your development environment.
You have several options for getting the code. You can fork, clone, or generate.
If you’d like to add features (or bug fixes) to improve the example application, you can fork the GitHub repo and make pull requests. Your code contributions are welcome!
If you want to copy and customize the app with changes that are only useful for your own project, you can clone the GitHub repo. You’ll need to search-and-replace the project name throughout the application. You probably should generate the app instead (see below). To clone:
$ git clone git://github.com/RailsApps/rails-stripe-membership-saas.git
You’ll need git on your machine. See Rails and Git.
If you want to use the project as a starter app, use the Rails Composer tool to generate a new version of the example app. You’ll be able to give it your own project name when you generate the app. Generating the application gives you additional options.
To build the example application, run the command:
$ rails new rails-stripe-membership-saas -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb -T
Use the -T flag to skip Test::Unit files.
The $ character indicates a shell prompt; don’t include it when you run the command.
This creates a new Rails app named rails-stripe-membership-saas on your computer. You can use a different name if you wish.
You’ll see a prompt:
question Install an example application?
1) I want to build my own application
2) membership/subscription/saas
3) rails-prelaunch-signup
4) rails3-bootstrap-devise-cancan
5) rails3-devise-rspec-cucumber
6) rails3-mongoid-devise
7) rails3-mongoid-omniauth
8) rails3-subdomains
Choose membership/subscription/saas.
Then choose Stripe:
question Billing with Stripe or Recurly?
1) Stripe
2) Recurly
The application generator template will ask you for additional preferences:
question Web server for development?
1) WEBrick (default)
2) Thin
3) Unicorn
4) Puma
question Web server for production?
1) Same as development
2) Thin
3) Unicorn
4) Puma
question Template engine?
1) ERB
2) Haml
3) Slim
extras Set a robots.txt file to ban spiders? (y/n)
extras Use or create a project-specific rvm gemset? (y/n)
extras Create a GitHub repository? (y/n)
We recommend Thin in development for speed and less noise in the log files.
If you plan to deploy to Heroku, select Thin as your production webserver.
The example application uses the default “ERB” Rails template engine. Optionally, you can use another template engine, such as Haml or Slim. See instructions for Haml and Rails.
Set a robots.txt file to ban spiders if you want to keep your new site out of Google search results.
It is a good idea to use rvm, the Ruby Version Manager, and create a project-specific rvm gemset (not available on Windows). See Installing Rails.
If you choose to create a GitHub repository, the generator will prompt you for a GitHub username and password.
If you get an error “OpenSSL certificate verify failed” or “Gem::RemoteFetcher::FetchError: SSL_connect” see the article OpenSSL errors and Rails.
If you get an error like this:
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
composer Running 'after bundler' callbacks.
The template [...] could not be loaded.
Error: You have already activated ..., but your Gemfile requires ....
Using bundle exec may solve this.
It’s due to conflicting gem versions. See the article Rails Error: “You have already activated (…)”.
If you’re storing the app in a GitHub repository, please edit the README files to add a description of the app and your contact info. If you don’t change the README, people will think I am the author of your version of the application.
See the article Installing Rails to make sure your development environment is prepared properly.
The application implements recurring billing using Stripe. Before you start, go to the Stripe website and set up an account. You don’t need a credit card merchant account or payment gateway. There’s no approval process to delay getting started.
I recommend using rvm, the Ruby Version Manager, to create a project-specific gemset for the application. If you generate the application with the Rails Composer tool, you can create a project-specific gemset.
Check the Gemfile to see which gems are used by this application.
If you generate the application with the Rails Composer tool, all gems will be installed.
Otehrwise, run the bundle install command to install the required gems on your computer:
$ bundle install
You can check which gems are installed on your computer with:
$ gem list
Keep in mind that you have installed these gems locally. When you deploy the app to another server, the same gems (and versions) must be available.
You must configure the application for your email account. See the article Send Email with Rails.
You can modify the configuration file for Devise if you want to use something other than the defaults:
- config/initializers/devise.rb
The application uses the figaro gem to set environment variables. Credentials for your administrator account and Stripe API keys are set in the config/application.yml file. The .gitignore file prevents the config/application.yml file from being saved in the git repository so your credentials are kept private. See the article Rails Environment Variables for more information.
Modify the file config/application.yml:
# Add account credentials and API keys here. # See http://railsapps.github.io/rails-environment-variables.html # This file should be listed in .gitignore to keep your settings secret! # Each entry sets a local environment variable and overrides ENV variables in the Unix shell. # For example, setting: # GMAIL_USERNAME: Your_Gmail_Username # makes 'Your_Gmail_Username' available as ENV["GMAIL_USERNAME"] # Add application configuration variables here, as shown below. # GMAIL_USERNAME: Your_Username GMAIL_PASSWORD: Your_Password ADMIN_NAME: First User ADMIN_EMAIL: [email protected] ADMIN_PASSWORD: changeme ROLES: [admin, silver, gold, platinum] STRIPE_API_KEY: Your_Stripe_API_key STRIPE_PUBLIC_KEY: Your_Stripe_Public_Key
Set the user name and password needed for the application to send email.
If you wish, set your name, email address, and password for an administrator’s account. If you prefer, you can use the default to sign in to the application and edit the account after deployment. It is always a good idea to change the administrator’s password after the application is deployed.
The roles you specify in the configuration file are the subscription plans that will be available to the application’s users. You will need an “admin” role. Keep the “silver”, “gold”, and “platinum” roles while you are testing the application. You can change these roles later, after you familiarize yourself with the application and begin to customize it for your own needs.
The Stripe gem requires an API key to operate. You also need to supply a public key when initiating a transaction. You can find both keys on your Stripe account page. Two sets of keys are available: one for testing, one for live transactions. Use the testing keys on your development machine. When you deploy, use the live keys.
All configuration values in the config/application.yml file are available anywhere in the application as environment variables. For example, ENV["GMAIL_USERNAME"] will return the string “Your_Username”.
If you prefer, you can delete the config/application.yml file and set each value as an environment variable in the Unix shell.
The db/seeds.rb file initializes the database with default values. To keep some data private, and consolidate configuration settings in a single location, we use the config/application.yml file to set environment variables and then use the environment variables in the db/seeds.rb file.
puts 'ROLES'
YAML.load(ENV['ROLES']).each do |role|
Role.find_or_create_by_name({ :name => role }, :without_protection => true)
puts 'role: ' << role
end
puts 'DEFAULT USERS'
user = User.find_or_create_by_email :name => ENV['ADMIN_NAME'].dup, :email => ENV['ADMIN_EMAIL'].dup, :password => ENV['ADMIN_PASSWORD'].dup, :password_confirmation => ENV['ADMIN_PASSWORD'].dup
puts 'user: ' << user.name
user.add_role :admin
user2 = User.find_or_create_by_email :name => 'Silver User', :email => '[email protected]', :password => 'changeme', :password_confirmation => 'changeme'
user2.add_role :silver
user3 = User.find_or_create_by_email :name => 'Gold User', :email => '[email protected]', :password => 'changeme', :password_confirmation => 'changeme'
user3.add_role :gold
user4 = User.find_or_create_by_email :name => 'Platinum User', :email => '[email protected]', :password => 'changeme', :password_confirmation => 'changeme'
user4.add_role :platinum
puts "users: #{user2.name}, #{user3.name}, #{user4.name}"
The db/seeds.rb file reads a list of roles from the config/application.yml file and adds the roles to the database. In fact, any new role can be added to the roles datatable with a statement such user.add_role :superhero. Setting the roles in the db/seeds.rb file simply makes sure each role is listed and available should a user wish to change roles.
You can change the administrator name, email, and password in this file but it is better to make the changes in the config/application.yml file to keep the credentials private. If you decide to include your private password in the db/seeds.rb file, be sure to add the filename to your .gitignore file so that your password doesn’t become available in your public GitHub repository.
Note that it’s not necessary to personalize the db/seeds.rb file before you deploy your app. You can deploy the app with an example user and then use the application’s “Edit Account” feature to change name, email address, and password after you log in. Use this feature to log in as an administrator and change the user name and password to your own.
The application handles the administrator’s account and any “example.com” email addresses as a special case. Users with an “example.com” domain will not be added to Stripe as subscribers; they will only be added to the application database. This makes it possible to run rake db:seed to add the administrator and set up sample users for development and testing.
If you want to see Stripe’s response when subscribing a new user (using a fake credit card number such as 4242424242424242), don’t use an “example.com” email address.
Two statements in the update_stripe method in the app/models/user.rb file implement the special case so that the Stripe server is not contacted:
def update_stripe
return if email.include?(ENV['ADMIN_EMAIL'])
return if email.include?('@example.com') and not Rails.env.production?
.
.
.
end
As you can see from the code, the “example.com” email addresses will not be special cased in production. That means rake db:seed will fail with errors if you attempt to run it after deployment. See advice below about deploying to Heroku. You should remove the sample users (but not the administrator) from the db/seeds.rb file before deploying to production.
Prepare the database and add the default user to the database by running the commands:
$ rake db:migrate $ rake db:seed
Use rake db:reset if you want to empty and reseed the database.
Set the database for running tests:
$ rake db:test:prepare
If you’re not using rvm, the Ruby Version Manager, you should preface each rake command with bundle exec. You don’t need to use bundle exec if you are using rvm version 1.11.0 or newer.
The file config/initializers/stripe.rb sets the Stripe API key and public key from environment variables:
Stripe.api_key = ENV["STRIPE_API_KEY"] STRIPE_PUBLIC_KEY = ENV["STRIPE_PUBLIC_KEY"]
You could hardcode the Stripe API key and public key in the config/initializers/stripe.rb file but instead, we advise to set the Stripe API key and public key in the config/application.yml file. Recording sensitive information in the config/initializers/stripe.rb file might expose it publicly on a GitHub repo. The Stripe API key should be kept secret; the Stripe public key can be revealed without consequence.
Before you can use the application, you must prepare your Stripe account to recognize the subscription plans you’ll offer.
This step is necessary if you’re going to use Stripe to automatically handle recurring billing. To match the example application, tell Stripe that you have three plans named “Silver”, “Gold”, and “Platinum” that will be billed monthly at rates of $9, $19, and $29. Once a customer is created and assigned a plan, Stripe will do all the work of notifying the user, initiating monthly billing, and contacting the user when a credit card is declined or expires.
Go to the Stripe plan management page to create a subscription plan. Stripe offers documentation about creating a plan and additional detail about plans.
Look for the toggle switch “Live/Test” and set it to “Test.” Click the button to “Create your first plan.”
Create three different plans with the following values:
| ID | Name | Amount | Interval |
|---|---|---|---|
| silver | Silver | 9.00 | monthly |
| gold | Gold | 19.00 | monthly |
| platinum | Platinum | 29.00 | monthly |
“ID” is a unique string of your choice that is used to identify the plan when subscribing a customer. In our application, each plan should have an ID that corresponds to the roles we’ve created to manage access. “Name” is displayed on invoices and in the Stripe web interface. “Amount” is the subscription price in US dollars. “Interval” is the billing frequency. Optionally, you can specify a trial period (in days). If you include a trial period, the customer won’t be billed for the first time until the trial period ends. If the customer cancels before the trial period is over, she’ll never be billed at all.
When a credit card expires or a monthly transaction is declined, Stripe will automatically retry a recurring payment after it fails. After a number of attempts (set in your Stripe account settings), Stripe will cancel the subscription. Your application needs to know to deny access for a subscriber with an expired account. Stripe provides webhooks to communicate events to you (for details, see the Stripe webhooks documentation).
A Stripe webhook is an HTTP request from Stripe’s servers to your site, containing JSON data that provides data about the event, plus an event id that can be used to retrive the data from the Stripe server. The example application responds to Stripe webhooks, using an implementation provided by Danny Whalen’s stripe_event gem. The stripe_event gem is a Rails engine that responds to webhook requests at http://localhost:3000/stripe (you can change the URL by modifying the engine mounting in the config/routes.rb file).
The example application only responds to “customer.subscription.deleted” events. You can customize the application to respond to other events (such as sending a thank you email in response to an “invoice.payment_succeeded” event).
For webhooks to work, you must visit your Stripe dashboard at https://manage.stripe.com/#account/webhooks and add the URL for your application, such as http://example.com/stripe.
If you’ve used the Rails Composer tool to generate the application, the application’s secret token will be unique, just as with any Rails application generated with the rails new command.
However, if you’ve cloned the application directly from GitHub, it is crucial that you change the application’s secret token before deploying your application in production mode. Otherwise, people could change their session information, and potentially access your SaaS or membership site as a premium user or administrator. Your secret token should be at least 30 characters long and completely random.
Get a unique secret token:
rake secret
Edit your config/initializers/secret_token.rb file to add the secret token:
RailsStripeMembershipSaas::Application.config.secret_token = '...some really long, random string...'
You can check that your app runs properly by entering the command:
$ rails server
To see your application in action, open a browser window and navigate to http://localhost:3000/.
If you are using the default values from the config/application.yml file, you can sign in as the administrator using:
- email: [email protected]
- password: changeme
You’ll see a navigation link for Admin. Clicking the link will display a page with a list of users at
http://localhost:3000/users.
To sign in as the second user, use
- email: [email protected]
- password: changeme
The second user will not see the Admin navigation link and will not be able to access the page at
http://localhost:3000/users.
You should be able to create additional users using the fake credit card number 4242424242424242. You’ll see the new users listed when you log in as an administrator. And you’ll see the new users listed as customers when you visit your Stripe dashboard. As explained above, users with “example.com” email addresses will not be added to Stripe in development or testing.
Stop the server with Control-C.
If you test the app by starting the web server and then leave the server running while you install new gems, you’ll have to restart the server to see any changes. The same is true for changes to configuration files in the config folder. This can be confusing to new Rails developers because you can change files in the app folders without restarting the server. Stop the server each time after testing and you will avoid this issue.
For your convenience, here is a Tutorial for Rails on Heroku. Heroku provides low cost, easily configured Rails application hosting.
Be sure to set up SSL before you make your application available in production. See the Heroku documentation on SSL.
Prior to deployment, change your db/seeds.rb file. Remove the “example.com” sample users.
puts 'ROLES'
YAML.load(ENV['ROLES']).each do |role|
Role.find_or_create_by_name({ :name => role }, :without_protection => true)
puts 'role: ' << role
end
puts 'DEFAULT USERS'
user = User.find_or_create_by_email :name => ENV['ADMIN_NAME'].dup, :email => ENV['ADMIN_EMAIL'].dup, :password => ENV['ADMIN_PASSWORD'].dup, :password_confirmation => ENV['ADMIN_PASSWORD'].dup
puts 'user: ' << user.name
user.add_role :admin
You’ll need to set the configuration values from the config/application.yml file as Heroku environment variables. See the article Rails Environment Variables for more information.
With the figaro gem, just run:
rake figaro:heroku
Alternatively, you can set Heroku environment variables directly with heroku config:add.
$ heroku config:add GMAIL_USERNAME='[email protected]' GMAIL_PASSWORD='secret' $ heroku config:add 'ROLES=[admin, silver, gold, platinum]' $ heroku config:add ADMIN_NAME='First User' ADMIN_EMAIL='[email protected]' ADMIN_PASSWORD='changeme' $ heroku config:add STRIPE_API_KEY=secret STRIPE_PUBLIC_KEY=secret
If you don’t remove the “example.com” sample users, rake db:seed will fail with errors if you attempt to run it on Heroku after deployment, since you are not supplying a credit card for Stripe for these users.
Prepare your application assets for Heroku.
Add this configuration parameter to the config/application.rb file:
# Heroku requires this to be false config.assets.initialize_on_precompile=false
Then precompile assets, commit to git, and push to Heroku:
$ rake assets:precompile $ git add -A $ git commit -m "assets compiled for Heroku" $ git push heroku master Complete Heroku deployment with: <pre> $ heroku run rake db:migrate $ heroku run rake db:seed
See the Tutorial for Rails on Heroku for details.
This application provides a fully functional membership site that is ready to take credit card payments and serve access to restricted content.
It uses Stripe for payment processing, allows users to change credit cards or subscription plans, and uses Stripe webhooks to delete users who have expired or declined credit cards.
You might consider a few enhancements. For example, you might want the application to respond to a Stripe webhook event when a credit card payment is successful by sending a “paid” invoice. Or you might respond to Stripe webhook events when credit card payments are unsuccessful by sending a friendly note encouraging the user to check for an expired credit card before the subscription is cancelled.
If you have suggestions for additional features, please create an issue on GitHub.
The application provides a suite of RSpec unit tests and Cucumber scenarios and step definitions.
After installing the application, run rake -T to check that rake tasks for RSpec and Cucumber are available.
Run rake spec to run RSpec tests.
Run rake cucumber (or more simply, cucumber) to run Cucumber scenarios.
Please send the author a message, create an issue, or submit a pull request if you can contribute improved RSpec or Cucumber files.
Problems? Check the issues.
The tutorial provides additional documentation.
Please create a GitHub issue if you identify any problems or have suggestions for improvements.
Your best source for help with problems is Stack Overflow. Your issue may have been encountered and addressed by others.
You can also try Rails Hotline, a free telephone hotline for Rails help staffed by volunteers.
If you make improvements to this application, please share with others.
Send the author a message, create an issue, or fork the project and submit a pull request.
If you add functionality to this application, create an alternative implementation, or build an application that is similar, please contact me and I’ll add a note to the README so that others can find your work.
Daniel Kehoe implemented the application and wrote the tutorial.
Taylor Mock contributed tests and feature improvements.
Is the app useful to you? Follow the project on Twitter: @rails_apps
and tweet some praise. I’d love to know you were helped out by what I’ve put together.
Copyright © 2012 Daniel Kehoe