servicemerchant 0.1.0

data/recurring_billing/lib/recurring_billing.rdoc

@@ -0,0 +1,87 @@
+This class provides unified API to access remote payment gateways.
+
+== Quick overview
+=== Creating a gateway accessor
+There are two options to get an instance of an accessor for required gateway. First is to use get_instance method:
+ options = {:gateway => :authorize_net, :login => 'MyLogin', :password => 'MyPassword'}
+ gateway = RecurringBilling::RecurringBillingGateway.get_instance(options)
+which basically is an alias for the second method, directly calling
+the constructor of RecurringBilling::AuthorizeNetGateway (or any other RecurringBillingGateway descendant):
+ gateway = RecurringBilling::AuthorizeNetGateway({:login => 'MyLogin', :password => 'MyPassword'})
+First method is recommended to be used for more flexibility.
+
+=== Common options for RecurringBilling methods
+It should be self-explanatory that every recurring payment itself has many parameters - those parameters have to be specified
+when the payment is created and updated on remote gateway as well. Within the API, these are grouped for convenience into four groups
+that have become the input parameters for create and update methods:
+ - Amount
+ - Card
+ - Payment Options
+ - Recurring Options
+
+<b>Amount</b>(amount) is the object of Money class, which includes both amount and currency of the payment.
+
+<b>Card</b>(card) is the object of ActiveMerchant::Billing::CreditCard representing the credit card that is charged during recurring payments
+
+<b>Payment Options</b>(payment_options) are a hash of:
+- :subscription_name - +string+ containing the reference name for the subscription
+- :billing_address - +hash+ containing subscriber's billing address (see ActiveMerchant for more info on structure)
+- :order - +hash+ containing merchant's info about order, like invoice ID (see ActiveMerchant for more info on structure)
+- :taxes_amount_included - +boolean+ declaring if taxes are included in payment amount or not
+This set of options contains information of merchant.
+
+<b>Recurring Options</b>(payment_options) are a hash of:
+- :start_date - +Date+ object, date of the first billing occurrence
+- :interval - +string+ of <tt>(0.5|d+)\s*(d|w|m|y)/</tt> template that shows time between two consecutive billing occurrences
+- :end_date -  +Date+ object representing date after which there are no more billing occurrences
+- :occurrences - positive +integer+ showing number of billing occurrences. Either this or :end_date should be specified
+- :trial_days - positive +integer+ showing number of days of free trial
+This set of options declares settings of payment recurring occurrences.
+
+=== Creating a remote payment
+Once gateway is created, payments could be made. The whole idea is very simple - prepare parameters and use the
+create method of an instance:
+ amount = Money.us_dollar(100) # $1 USD
+ card =   ActiveMerchant::Billing::CreditCard.new({
+   :number => '4242424242424242',
+   :month => 9,
+   :year => Time.now.year + 1,
+   :first_name => 'Name',
+   :last_name => 'Lastname',
+   :verification_value => '123',
+   :type => 'visa'
+ }) # Some random credit card
+ payment_options = {
+         :subscription_name => 'Random subscription',
+         :order => {:invoice_number => 'ODMX31337'}
+         }
+ recurring_options = {
+         :start_date => Date.today,
+         :occurrences => 10,
+         :interval => '10d'
+         }
+ billing_id = gateway.create(amount, card, payment_options, recurring_options)
+You may then check the result of recurring payment creation by accessing last_response:
+ response = gateway.last_response
+ print response.inspect
+Exact structure of last_response return value is defined in respective ActiveMerchant module. Most common
+uses of last_response query are:
+ unless response.success? # succeed-failed check
+    print response.message # get message retrieved from remote gateway
+ ...
+Last response is changed whenever create, update, inquiry or delete methods are called.
+
+=== Updating and canceling a remote payment
+To update the settings of recurring payment on  gateway, just call the update method of an instance.
+ new_amount = Money.us_dollar(150) # $1.5 USD
+ success = gateway.update(billing_id, new_amount, nil, {}, {}) # or just gateway.update(new_amount)
+Please note that acceptable update parameters vary with gateway. Correctness of parameters for update is
+checked via protected correct_update? method.
+
+Recurring payment may be cancelled via delete method:
+ success = gateway.delete(billing_id)
+
+=== Inquiring gateway on payment status
+In order to inquire remote gateway on status of given subscription, inquiry method of an instance should be used:
+ result = gateway.inquiry(billing_id)
+The result structure varies from gateway to gateway.

data/recurring_billing/lib/utils.rb

@@ -0,0 +1,81 @@
+# This module contains common functions that ServiceMerchant uses. 
+module Utils
+  #Counts nubmer of months between two dates
+  #
+  # 2008/1/1, 2007/12/31 => 1
+  # 2008/9/10, 2009/10/20 => 13
+  # ETC
+  def months_between(date1, date2)
+    if date1 > date2
+      recent_date = date1.to_date
+      past_date = date2.to_date
+    else
+      recent_date = date2.to_date
+      past_date = date1.to_date
+    end
+    years_diff = recent_date.year - past_date.year
+    months_diff = recent_date.month - past_date.month + ((recent_date.day >= past_date.day) ? 0 : -1)
+    if months_diff < 0
+      months_diff = 12 + months_diff
+      years_diff -= 1
+    end
+    return years_diff*12 + months_diff
+  end
+  
+  # Parses given INTERVAL string into hash.
+  #
+  # Sample use:
+  #  "1w" => {:length => 1, :unit => :w }
+  #  "0.5 m" => {:length => 0.5, :unit => :m }
+  #  "10 d" => {:length => 10, :unit => :d }
+  #  "3y" => {:length => 3, :unit => :y }
+  #  "0.25 w" => ArgumentError
+  #  "2 x" => ArgumentError
+  def parse_interval(interval)
+    if (interval =~ /^(\d+|0\.5)\s*(d|w|m|y)$/i)
+      return $1 == '0.5' ? 0.5 : $1.to_i, $2.downcase.to_sym
+    end
+    raise ArgumentError, "Invalid value format for payment interval: #{interval}"
+  end
+  
+  # Returns number of payment occurrences between END_DATE and START_DATE with INTERVAL frequency.
+  #
+  # INTERVAL should be given in the same format parse_interval uses. END_DATE and START_DATE should be either Date or DateTime.
+  # Returned number includes initial payment.
+  #
+  # Sample use:
+  #  [Date.today(), '1 w', Date.today()+18] => 3
+  #  [DateTime.new(2008, 09, 20), '1y', DateTime.new(2009, 09, 19)] => 1
+  def get_occurrences(start_date, interval, end_date)
+
+    start_date = Date.new(start_date.year,start_date.month,start_date.mday)
+    end_date = Date.new(end_date.year,end_date.month,end_date.mday)
+    raise ArgumentError, "Start date (#{start_date}) should be less than or equal to end date (#{end_date})" if (start_date>end_date)
+
+    i_length, i_unit = parse_interval(interval)
+
+    if i_length == 0.5 && ![:m, :y].include?(i_unit)
+      raise ArgumentError, "Semi- interval is not supported to this units (#{i_unit.to_s})"
+    end
+
+    new_interval =  case i_unit
+                      when :d then {:length=>i_length,    :unit=>:days}
+                      when :w then {:length=>i_length*7,  :unit=>:days}
+                      when :m then {:length=>i_length,    :unit=>:months}
+                      when :y then {:length=>i_length*12, :unit=>:months}
+                    end
+
+    if new_interval[:unit] == :days
+      new_occurrences = 1 + ((end_date - start_date)/new_interval[:length]).to_i
+    elsif new_interval[:unit] == :months
+      new_occurrences = 1 + (months_between(end_date, start_date)/new_interval[:length]).to_i 
+    end
+    return new_occurrences
+  end
+  
+  # Returns midnight of specified DateTime object (as DateTime).
+  def get_midnight(datetime_x)
+    DateTime.new(datetime_x.year,datetime_x.month,datetime_x.mday)
+  end
+  
+end

data/recurring_billing/test/fixtures.yml

@@ -0,0 +1,33 @@
+# This file has all of the ActiveMerchant test account credentials.
+# Many gateways do not offer publicly available test accounts. In
+# order to make testing the gateways easy you can copy this file to
+# your home directory as the file ~/.active_merchant/fixtures.yml
+# You can then place your own test account credentials in your local
+# copy of the file.
+#
+# If the login is numeric, ensure that you place quotes around it.
+# Leading zeros will be lost when YAML parses the file if you don't.
+#
+# Paste any required PEM certificates after the pem key.
+#
+authorize_net:
+  gateway: authorize_net
+  login: 6zz6m5N4Et
+  password: 9V9wUv6Yd92t27t5
+  is_test: true
+
+# You can use either your API PEM file or API signature with PayPal.
+paypal_certificate:
+  gateway: paypal
+  login: LOGIN
+  password: PASSWORD
+  subject:
+  pem: |--
+    PASTE YOUR PEM FILE HERE
+
+paypal:
+  gateway: paypal
+  login: a.lebe_1220380924_biz_api1.list.ru
+  password: 1220380928
+  signature: An5ns1Kso7MWUdW4ErQKJJJ4qi4-ABavC-ayabELBOsjVjsDpfMCgJRN
+  is_test: true

data/recurring_billing/test/remote/authorize_net_test.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class AuthorizeNetGatewayRemoteTest < Test::Unit::TestCase
+  
+  def setup
+    credentials = fixtures(:authorize_net)
+    assert @gw = RecurringBilling::AuthorizeNetGateway.new(credentials.update({:is_test => true}))
+    assert_equal @gw.name, 'Authorize.net'
+    @card = credit_card()
+  end
+  
+  def test_crud_recurring_payment
+    payment_options = {
+          :subscription_name => 'Test Subscription 1337',
+          :order => {:invoice_number => '407933'}
+          }    
+    recurring_options = {
+          :start_date => Date.today + 1,
+          :end_date => Date.today + 290,
+          :interval => '1m'
+          }    
+
+    billing_id = @gw.create(Money.us_dollar(15), @card, payment_options, recurring_options)
+    print "Create:\n"
+    print @gw.last_response.inspect
+    payment_options[:order] = {:invoice_number => '407934'}
+    @gw.update(billing_id, Money.us_dollar(16), @card, payment_options, nil)
+    print "\nUpdate:\n"
+    print @gw.last_response.inspect
+    @gw.delete(billing_id)
+    print "\nDelete:\n"
+    print @gw.last_response.inspect
+    assert true
+  end
+  
+end

data/recurring_billing/test/remote/paypal_test.rb

@@ -0,0 +1,46 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class PaypalGatewayRemoteTest < Test::Unit::TestCase
+
+  def setup
+    cred = fixtures(:paypal)
+    assert @gw = RecurringBilling::PaypalGateway.new(cred.update({:is_test=>true}))
+    assert_equal @gw.name, 'PayPal Website Payments Pro (US)'
+    @card = credit_card()
+  end
+
+  def test_crud_recurring_payment
+    payment_options = {
+          :subscription_name => 'Test Subscription 1337',
+          :order => {:invoice_number => '407933'}
+          }
+    recurring_options = {
+          :start_date => Date.today + 1,
+          :end_date => Date.today + 290,
+          :interval => '1m'
+          }
+
+    print "\nCreate:\n"
+    billing_id = @gw.create(Money.us_dollar(15), @card, payment_options=payment_options, recurring_options=recurring_options)
+    print @gw.last_response.inspect
+    payment_options[:order] = {:invoice_number => '407934'}
+    assert @gw.last_response.success?
+
+    print "\n\nUpdate:\n"
+    @gw.update(billing_id, Money.us_dollar(16), @card, payment_options=payment_options)
+    print @gw.last_response.inspect
+    assert @gw.last_response.success?
+
+    print "\n\nInquiry:\n"
+    result = @gw.inquiry(billing_id)
+    print @gw.last_response.inspect
+    print "\n\n", result.inspect
+    assert @gw.last_response.success?
+
+    print "\n\nDelete:\n"
+    @gw.delete(billing_id)
+    print @gw.last_response.inspect
+    assert @gw.last_response.success?
+  end
+
+end

data/recurring_billing/test/remote/recurring_billing_test.rb

@@ -0,0 +1,41 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class RecurringBillingRemoteTest < Test::Unit::TestCase
+
+  def setup
+    @card = credit_card()
+  end
+
+  def perform_generic_test(gateway)
+    random_invoice = "%06d" % rand(999999)
+    payment_options = {
+          :subscription_name => 'Test Subscription 1337',
+          :order => {:invoice_number => random_invoice}
+          }
+    recurring_options = {
+          :start_date => Date.today + 1,
+          :end_date => Date.today + 290,
+          :interval => '1m'
+          }
+    credentials = fixtures(gateway)
+    assert gw = RecurringBilling::RecurringBillingGateway.get_instance(credentials)
+
+    billing_id = gw.create(Money.us_dollar(15), @card, payment_options, recurring_options)
+    assert gw.last_response.success?
+    new_random_invoice = "%06d" % rand(999999)
+    payment_options[:order] = {:invoice_number => new_random_invoice}
+    gw.update(billing_id, Money.us_dollar(16), @card, payment_options, {})
+    assert gw.last_response.success?
+    gw.delete(billing_id)
+    assert gw.last_response.success?
+  end
+
+  def test_paypal
+    perform_generic_test(:paypal)
+  end
+
+  def test_authorize_net
+    perform_generic_test(:authorize_net)
+  end
+
+end

data/recurring_billing/test/test_helper.rb

@@ -0,0 +1,153 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'test/unit'
+
+require 'active_merchant'
+
+require File.dirname(__FILE__) + '/../lib/gateways'
+
+# Turn off invalid certificate crashes
+require 'openssl'
+silence_warnings do
+  OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE
+end
+
+ActiveMerchant::Billing::Base.mode = :test
+
+module RecurringBilling
+  module Assertions
+    def assert_field(field, value)
+      clean_backtrace do
+        assert_equal value, @helper.fields[field]
+      end
+    end
+
+    # Allows the testing of you to check for negative assertions:
+    #
+    #   # Instead of
+    #   assert !something_that_is_false
+    #
+    #   # Do this
+    #   assert_false something_that_should_be_false
+    #
+    # An optional +msg+ parameter is available to help you debug.
+    def assert_false(boolean, message = nil)
+      message = build_message message, '<?> is not false or nil.', boolean
+
+      clean_backtrace do
+        assert_block message do
+          not boolean
+        end
+      end
+    end
+
+    # A handy little assertion to check for a successful response:
+    #
+    #   # Instead of
+    #   assert_success response
+    #
+    #   # DRY that up with
+    #   assert_success response
+    #
+    # A message will automatically show the inspection of the response
+    # object if things go wrong.
+    def assert_success(response)
+      clean_backtrace do
+        assert response.success?, "Response failed: #{response.inspect}"
+      end
+    end
+
+    # The negative of +assert_success+
+    def assert_failure(response)
+      clean_backtrace do
+        assert_false response.success?, "Response expected to fail: #{response.inspect}"
+      end
+    end
+
+    def assert_valid(validateable)
+      clean_backtrace do
+        assert validateable.valid?, "Expected to be valid"
+      end
+    end
+
+    def assert_not_valid(validateable)
+      clean_backtrace do
+        assert_false validateable.valid?, "Expected to not be valid"
+      end
+    end
+
+    private
+    def clean_backtrace(&block)
+      yield
+    rescue Test::Unit::AssertionFailedError => e
+      path = File.expand_path(__FILE__)
+      raise Test::Unit::AssertionFailedError, e.message, e.backtrace.reject { |line| File.expand_path(line) =~ /#{path}/ }
+    end
+  end
+end
+
+module Test
+  module Unit
+    class TestCase
+
+      include RecurringBilling::Assertions
+      include Utils
+
+      DEFAULT_CREDENTIALS = File.dirname(__FILE__) + '/fixtures.yml'
+
+      private
+      def credit_card(number = '4242424242424242', options = {})
+        defaults = {
+          :number => number,
+          :month => 9,
+          :year => Time.now.year + 1,
+          :first_name => 'John',
+          :last_name => 'Doe',
+          :verification_value => '123',
+          :type => 'visa'
+        }.update(options)
+
+        ActiveMerchant::Billing::CreditCard.new(defaults)
+      end
+
+      def address(options = {})
+        {
+          :name => 'John Doe',
+          :address1 => '1234 My Street',
+          :address2 => 'Apt 1',
+          :company => 'Widgets Inc',
+          :city => 'Ottawa',
+          :state => 'ON',
+          :zip => 'K1C2N6',
+          :country => 'CA',
+          :phone => '(555)555-5555'
+        }.update(options)
+      end
+
+      def all_fixtures
+        @@fixtures ||= load_fixtures
+      end
+
+      def fixtures(key)
+        data = all_fixtures[key] || raise(StandardError, "No fixture data was found for '#{key}'")
+
+        data.dup
+      end
+
+      def load_fixtures
+        file = DEFAULT_CREDENTIALS
+        yaml_data = YAML.load(File.read(file))
+        symbolize_keys(yaml_data)
+
+        yaml_data
+      end
+
+      def symbolize_keys(hash)
+        return unless hash.is_a?(Hash)
+
+        hash.symbolize_keys!
+        hash.each{|k,v| symbolize_keys(v)}
+      end
+    end
+  end
+end