Skip to content

Latest commit

 

History

History
252 lines (181 loc) · 10.2 KB

README.rdoc

File metadata and controls

252 lines (181 loc) · 10.2 KB
Raw

SaasRamp ↑

notice: not yet used in production

SaasRamp is an open source Rails plugin which enables subscription billings in your application. I decided to take a somewhat different approach than others I have seen. It is built as a wrapper on ActiveMerchant, stores credit cards in the gateway, handles its own daily processing, and is completely independent of the authorization and authentication you choose.

Key Features ↑

Built as a wrapper to ActiveMerchant

  • Uses the AM gateways

  • Uses the AM credit card validation

  • Requires gateways that support store/unstore credit cards, and transactions using the vault key

Recurring billing and other daily tasks and notifications run on your server

  • Does not use recurring billing at the gateway (for more control and to avoid synchronization problems)

  • Run “rake saas:daily” (e.g. as a daily cron job)

  • Billing task can be run any time, skip a day, or multiple times a day without fear of sending duplicate billings or messages

Decouples subscriptions from authentication and authorization

  • You can use Restful Authentication, Authlogic or anything else

  • Declare your model (e.g. User or Account) with “acts_as_subscriber”

Separates the subscription, customer profile (credit card), and transaction history

Subscription model

  • When a model “acts_as_subscriber” it has one subscription

  • Subscription states - :free, :trial, :active, :past_due, :expired

  • #renew method processes recurring billing

  • #change_plan method for changing plans

  • #charge_balance to bill credit card current account balance

Subscription plan model

  • Define plans with different name, rate, interval

  • Migrate your own attributes (e.g. to define limitations, like max_memory, etc)

  • Plans defined in db/subscription_plans.yml file, loaded with “rake saas:plans” task

Subscription profile model

  • subscription has one profile

  • Responsible for handling the credit card information

  • Automatic validation, storing, and unstoring in vault on the gateway

  • Profile states - :no_info, :authorized, :error

Subscription transaction model

  • subscription has many transactions

  • Provides a transaction history

  • Wraps ActiveMerchant, unifying inconsistent gateway api

  • Handles exceptions and gateway responses

Subscription observer and mailer

  • observe transactions to send out email notifications as needed

  • email delivery issued from one file, un-clutters the models

  • includes mailer templates you can use or change

Example workflow ↑

  • New subscriptions can default to a free plan

  • New (non free) subscriptions start in :trial state (optional)

  • A warning email is sent out a few days before trial expires (trial period configurable)

  • When the trial period is over, and billing is successful, the subscription becomes :active

  • When renewals are due, :active subscriptions are billed and next renewal date is updated

  • If there’s a billing error, subscription becomes :past_due

  • Past due subscriptions have a grace period (optional) and warnings are sent before subscription becomes :expired

  • Expired subscriptions can revert to a limited plan rather than shut down the account

Dependencies ↑

Requires the following gems

  • ActiveMerchant - for gateways and credit card validation

  • Money - for currency numerics

  • state_machine - a better state machine

  • lockfile - for rake tasks

Testing requires gems

  • rspec, rspec-on-rails

optional:

  • cucumber

  • no-peeping-toms (plugin)

Installation ↑

$ script/plugin install git://github.com/linoj/saasramp.git

Easy configuration and customization

  • Configuration via a config/subscription.yml file (can vary per environment)

  • Populate and maintain current plans via a db/subscription_plans.yml file (can vary per environment)

  • Initializer generator for the default migration and configuration files

  • Scaffold generator for example controllers and views

  • Rake task for daily processing, you create a cron job

  • Gateway monkeypatches in config/initializers/gateways/

Add to environment.rb ↑

config.gem ‘activemerchant’, :lib => ‘active_merchant’ config.gem “money” config.gem ‘state_machine’ config.gem ‘lockfile’

Generate initialize ↑

$ ./script/generate saasramp

Generate migrations ↑

$ ./script/generate saas_migration (Review the file, adjust as needed, including custom attributes if any) (Note, you can migrate existing subscribers data at the same time) $ rake db:migrate

Define and populate the subscription plans ↑

  • Edit the file db/subscription_plans.yml

  • Load into database

$ rake saas:plans

Edit the configuration file config/subscription.yml ↑

  • gateway name and login parameters

  • default settings

  • environment specific settings

  • custom attributes (if any)

Acts as subscriber ↑

To the model that will own the subscription (e.g. User or Account), add

acts_as_subscriber

Optionally, migrate existing subscribers ↑

If you already have subscribers in your database (e.g. User or Account records), you need to create a subscription child object (and default plan) for them. This is easy, just re-save the objects. You can do this in console, or in another migration. For example,

User.all.each {|a| a.save }

Optionally, generate scaffolds (controllers and views) ↑

$ ./script/generate saas_scaffold

Optionally, add email notification observers, in environment.rb ↑

config.active_record.observers = :subscription_observer

Optionally, create your own mailer, using the SubscriptionMailer and templates as an example ↑

and modify subscription.yml with your mailer class name

Gateways ↑

Extensions/fixes to the ActiveMerchant gateways are in config/initializers/active_merchant/

I’ve only tested wrappers for the Authorize.Net CIM and Braintree gateways. The AN-CIM one is temporary until ActiveMerchant integrates CIM into the regular AuthorizeNet gateway.

The gateway is expected to support the following API:

Credit card based authorized/void, if you enable credit card validation at the gateway authorize( amount, credit_card ) # => response.authorization is the reference id void( reference ) Credit card storage and unstore store( credit_card ) # => response.token is the vault profile_key unstore( profile_key ) update( profile_key, credit_card ) # optional, if not we will unstore/store

Purchase based on customer profile key (vault key) (we’ll use either of the following methods) purchase( amount, profile_key ) # => response.authorization is the reference id or: authorize( amount, profile_key ) # => response.authorization is the reference id capture( amount, reference ) Credit/refund (we’ll use either of the following methods) credit( amount, profile_key ) or: refund( reference, :amount => amount ) See subscription_transaction.rb and spec/remote/*_spec.rb for more details.

Plan limits checker ↑

In your subscriber model you can declare a callback, #subscription_plan_check, that checks whether a subscriber has exceeded limits for his plan. This is used by Subscription#allowed_plans. The method is expected to return a blank value if ok (nil, false, [], {}), anything else means subscriber has exceeded limits. For example,

def subscription_plan_check(plan) (memory_used > plan.max_memory) || (file_count > plan.max_files) end # Or, def subscription_plan_check(plan) exceeded = {} exceeded = plan.max_memory if memory_used > plan.max_memory exceeded = plan.max_files if file_count > plan.max_files exceeded end

Setup recurring billing ↑

Review the rake task (tasks/saasramp_tasks.rake) and make sure the business logic meets your requirements. The task can be run any time from the command line,

$ rake saas:daily RAILS_ENV=production You can re-run the task multiple times a day without fear of accidental duplicate billings or notification emails.

Remember that email notifications are sent not by the rake task but through the SubscriptionObserver whenever a SubscriptionTransaction is created. You can modify that behavior by editing the subscription_observer.rb file, or simply not enabling the observer in your environment.rb.

To setup recurring billing on your server, use a cron tab manager to run the task, for example,

“cd ~/myapp && rake saas:daily RAILS_ENV=production”

To setup from the command line to run every day at 3am, for example:

$ echo “0 3 * * * cd ~/myapp && rake saas:daily RAILS_ENV=production” > daily.txt $ crontab daily.txt

Test the plugin ↑

Uses RSpec, which requires a dummy app to run the specs.

$ rails saastest $ cd saastest edit environment.rb config.gem ‘activemerchant’, :lib => ‘active_merchant’ config.gem “money” config.gem ‘state_machine’ edit environments/test.rb config.gem “rspec”, :lib => false, :version => “>= 1.2.0” config.gem “rspec-rails”, :lib => false, :version => “>= 1.2.0”

$ script/generate spec $ script/install plugin git:… $ script/generate saasramp $ cd vendor/plugins/saasramp/ $ rake spec $ rake remote_spec

Bonus: Example Cucumber features and steps included

$ script/generate subscription_features

References ↑

  • Peepcode ActiveMerchant pdf tutorial by Cody Fauser

  • Railscasts ActiveMerchant screencasts (144, 145)

  • The Bala Paranj screencasts on ActiveMerchant + Authorize.net

  • Freemium

  • Saasy

Developed for the ReviewRamp (www.reviewramp.com) application

Cost ↑

We appreciate a donation of $250 for one site, $1000 for multiple sites. (Just kidding).

jonathan at linowes dat com

Notes ↑

  • Uses the Money class for money but haven’t implemented currency or exchange rates

  • I built this for a “freemium” business model (en.wikipedia.org/wiki/Freemium) (sign up free, pay for more features). It should work for “subscribe or nothing” but I havent worked through those scenarios. I figure you’ll always want people to be able to log in and adjust their account even if they’re not a paying subscriber at the moment.

  • Works with acts_as_paranoid. Declare your subscriber model a_a_paranoid before a_a_subscriber. I’ve had problems with the aap gem, the plugin works (and use the edendevelopment fork, see www.vaporbase.com/postings/stack_level_too_deep). The subscription and its children are NOT paranoid, and they stick around until the subscriber is really really destroy! (bang).

Copyright © 2009 Jonathan Linowes, released under the MIT license