ServiceMerchant

Ruby toolkit for recurring billing and subscription management

ServiceMerchant is an open source library for Software-as-a-Service applications, based on subscription payments and various service plans. The library consists of number of well-isolated and well-defined components, so that you may re-use portions of the library, should you find the full functionality not required for you. If you choose to use the library as whole, it should cover most of your payments requirements, thus being billing module for your application.

ServiceMerchant’s main purpose is providing gateway-independent support for recurring billing operations and powerful high-level tools for building subscription-based billing atop of it. It is built on top of well-known Active Merchant library.

ServiceMerchant can be used both as a Rails plug-in or standalone Ruby library. It is also possible to integrate ServiceMerchant with non-Ruby web applications via REST interface or common GUI.

Supported Gateways

Currently Authorize.Net and Paypal Website Payments Pro (US) are supported.

Generally, if Active Merchant supports some gateway with recurring billing features then it is easy to add ServiceMerhant support as well. In this case you’ll only need to add a few lines of proxy code between Active Merchant and common recurring billing API.

How do I get it?

git clone git://github.com/itteco/service_merchant.git

If you’re not using git, you can download snapshot from Service Merchant page on github.com

Components

ServiceMerchant consists of three relatively independent components:

Recurring Billing API

Recurring Billing API is aimed at providing uniform interface for recurring billing features of payment gateways and making switching from one to another as painless as possible.

Transaction Tracker

Transactions Tracker stores local and readily available snapshots of so-called “recurring billing profiles”. With Tracker you can check account status much faster than vie gateway query (which not every gateway API includes). Transaction Tracker hooks automatically to Recurring Billing API and updates your local copy of data according to all ongoing operations.

Subscription Manager

Subscription Manager provides high-level logic for managing subscription services, tariff plans, payment policies and so on. You can even use it to automatically adjust final price with the tax of appropriate region!

Sample

def subscribe
  if params[:submit] && params[:tariff_plan_id]
    subscription_options = {
      :account_id => @current_account[:id],
      :account_country => @current_account[:country],
      :account_state => @current_account[:state],
      :tariff_plan => params[:tariff_plan_id],
      :quantity => params[:quantity].to_i,
      :start_date => Date.parse(params[:start_date]),
      :end_date => Date.parse(params[:end_date])
    }
    credit_card = ActiveMerchant::Billing::CreditCard.new({
      :type => params[:card_type],
      :number => params[:card_number].to_i,
      :month => params[:card_expiration_month].to_i,
      :year => params[:card_expiration_year].to_i,
      :first_name => params[:card_first_name],
      :last_name => params[:card_last_name],
      :verification_value => params[:card_verification_value]
    })
    # subscribe
    subscription_id = @sm.subscribe(subscription_options)

    # this block should be different in multi-step subscription
    begin
      @sm.pay_for_subscription(subscription_id, credit_card, {})
    rescue
      Subscription.delete(subscription_id)
      raise
    end

    redirect_to :action => nil
    return
  end
end

Sample application

ServiceMerchant includes sample Ruby on Rails application that demonstrates recurring billing-based subscription management in action. See sample_app/README for details.

Authors and contributors

• Alexander Lebedev — me [at] alexlebedev.com
• Artyom Scorecky — tonn81 [at] gmail.com
• Anatoly Ivanov — mail [at] anatoly-ivanov.com

Sponsored by Itteco Software