vaulted_billing 0.0.14 → 0.0.15

data/lib/vaulted_billing/configuration.rb

@@ -1,13 +1,34 @@
+
 module VaultedBilling
+  ##
+  # This configuration holds the default values to use when instantiating
+  # VaultedBilling gateways.  This configuration is accessed via
+  # VaultedBilling.config, or set en mass via a Hash with
+  # VaultedBilling.set_config(...).
+  #
   class Configuration
-    class GatewayConfiguration #:nodoc:
+    ##
+    # This class holds default configuration options for a specific
+    # gateway in the library.
+    #
+    class GatewayConfiguration
       attr_accessor :username, :password, :test_mode
 
+      ##
+      # Possible options are:
+      #
+      # * password - The default password for the gateway.
+      # * test_mode - A boolean indicating whether or not to use the test mode of the gateway (sandbox server, test API, etc.)
+      # * username - The default username for the gateway.
+      #
+      # Unless otherwise defined, test_mode will default to being true.
+      #
       def initialize(options = {}, &block)
         options = options.with_indifferent_access
         self.username = options[:username]
         self.password = options[:password]
-        self.test_mode = options.has_key?(:test_mode) ? options[:test_mode] : true
+        self.test_mode = options.has_key?(:test_mode) ?
+          options[:test_mode] : true
         yield(self) if block_given?
       end
     end
@@ -15,24 +36,50 @@ module VaultedBilling
     attr_accessor :logger
     alias :logger? :logger
 
+    attr_accessor :ca_file
+
     attr_accessor :test_mode
 
+    ##
+    # Possible options are as follows:
+    #
+    # * authorize_net_cim - A hash of GatewayConfiguration options for the Authorize.net CIM
+    # * bogus - A hash of GatewayConfiguration options for the Bogus gateway
+    # * nmi_customer_vault - A hash of GatewayConfiguration options for the NMI Customer Vault
+    # * test_mode - A boolean indicating whether or not the system defaults to using the test end points on the gateways.
+    #
     def initialize(options = {})
       options = options.with_indifferent_access
       self.test_mode = options.has_key?(:test_mode) ? options[:test_mode] : true
       @_authorize_net_cim = GatewayConfiguration.new(options[:authorize_net_cim]) if options[:authorize_net_cim]
       @_nmi_customer_vault = GatewayConfiguration.new(options[:nmi_customer_vault]) if options[:nmi_customer_vault]
       @_bogus = GatewayConfiguration.new(options[:bogus]) if options[:bogus]
+      @ca_file = File.expand_path('../../ext/cacert.pem', __FILE__)
     end
 
+    ##
+    # Returns a VaultedBilling::Configuration::GatewayConfiguration 
+    # instance to be used for defining default settings for the
+    # Authorize.net CIM gateway.
+    #
     def authorize_net_cim
       @_authorize_net_cim ||= GatewayConfiguration.new
     end
 
+    ##
+    # Returns a VaultedBilling::Configuration::GatewayConfiguration 
+    # instance to be used for defining default settings for the
+    # NMI Customer Vault gateway.
+    #
     def nmi_customer_vault
       @_nmi_customer_vault ||= GatewayConfiguration.new
     end
 
+    ##
+    # Returns a VaultedBilling::Configuration::GatewayConfiguration 
+    # instance to be used for defining default settings for the
+    # Bogus gateway.
+    #
     def bogus
       @_bogus ||= GatewayConfiguration.new
     end

data/lib/vaulted_billing/credit_card.rb

@@ -1,19 +1,40 @@
 module VaultedBilling
+  ##
+  # Intermediary class used to translate your local credit card information
+  # into data which VaultedBilling can recognize and use.
+  #
+  # Generally - and this is gateway specific - the only data which is
+  # actually required is the card number and expiration date (expires_on).
+  # Most of the other data is optional and may or may not be stored by
+  # your gateway.
+  #
+  # Note: The vault_id is the unique identifier generated by your gateway
+  # when you initially store the customer information.  This should be
+  # kept and stored locally, related to your local credit card information.
+  # If you generate a CreditCard object with a vault_id, it is assumed that
+  # the card is already stored on the gateway and is not new information.
+  #
   class CreditCard
-    attr_accessor :vault_id
-    attr_accessor :currency
-    attr_accessor :card_number
-    attr_accessor :cvv_number
-    attr_accessor :expires_on
-    attr_accessor :first_name
-    attr_accessor :last_name
-    attr_accessor :street_address
-    attr_accessor :locality
-    attr_accessor :region
-    attr_accessor :postal_code
-    attr_accessor :country
-    attr_accessor :phone
+    attr_accessor :card_number # The customer's credit card number
+    attr_accessor :country # The country of the credit card address.
+    attr_accessor :currency # The currency used by the credit card.
+    attr_accessor :cvv_number # The verification number (CVV2) on the card.
+    attr_accessor :expires_on # The date on which the credit card expires.
+    attr_accessor :first_name # The first name of the cardholder.
+    attr_accessor :last_name # The last name of the cardholder.
+    attr_accessor :locality # The "city" of the address on the card.
+    attr_accessor :phone # A phone number for the cardholder.
+    attr_accessor :postal_code # The postal code (zipcode) for the card.
+    attr_accessor :region # The "state" of the address on the card.
+    attr_accessor :street_address # The house number and street name of the card address.
+    attr_accessor :vault_id # The unique, gateway-generated identifier for this credit card.
 
+    ##
+    # You may define any of the CreditCard attributes by passing a hash
+    # with the attribute name as the key:
+    #
+    #     CreditCard.new(:card_number => '4111....')
+    #
     def initialize(attributes = {})
       attributes = HashWithIndifferentAccess.new(attributes)
       attributes.each_pair do |key, value|

data/lib/vaulted_billing/customer.rb

@@ -1,9 +1,24 @@
 module VaultedBilling
+  ##
+  # An intermediary object for VaultedBilling which represents a single
+  # customer on the gateway.
+  #
+  # Many gateways support you in defining multiple credit cards or payment
+  # methods under a single customer object.  To support this, they will
+  # generate one identifier for the top-level customer, and then separate
+  # identifiers for each payment method (see VaultedBilling::CreditCard).
+  #
   class Customer
-    attr_accessor :vault_id
-    attr_accessor :merchant_id
-    attr_accessor :email
+    attr_accessor :email # Optional email address for the customer.
+    attr_accessor :merchant_id # Optional custom identifier for the customer (i.e. your database key).
+    attr_accessor :vault_id # Gateway generated unique identifier for this customer in their system.
 
+    ##
+    # You can mass assign the attributes by passing a hash with keys
+    # matching attributes of the Customer:
+    #
+    #     Customer.new(:merchant_id => 1)
+    #
     def initialize(attributes = {})
       attributes = HashWithIndifferentAccess.new(attributes)
       @vault_id = attributes[:vault_id]

data/lib/vaulted_billing/gateways/authorize_net_cim.rb

@@ -13,7 +13,6 @@ module VaultedBilling
       def initialize(options = {})
         self.test_uri = 'https://apitest.authorize.net/xml/v1/request.api'
         self.live_uri = 'https://api.authorize.net/xml/v1/request.api'
-        self.ssl_pem = File.read(File.expand_path(File.join(File.dirname(__FILE__), '..', 'certificate_authorities', 'entrust.pem')))
 
         options = HashWithIndifferentAccess.new(options)
         @login = options[:username] || VaultedBilling.config.authorize_net_cim.username

data/lib/vaulted_billing/gateways/bogus.rb

@@ -2,6 +2,16 @@ require 'digest/md5'
 
 module VaultedBilling
   module Gateways
+    ##
+    # The Bogus gateway should only be used for simple interface testing
+    # to the VaultedBilling library.  All customer and credit card requests
+    # will always return successfully.  All transaction requests (purchase,
+    # authorize, capture, etc.) will always return successfully.
+    #
+    # The primary purpose of this gateway is to provide you with an end
+    # point for testing your interface, as well as a fairly reasonable
+    # gateway for performing simple, non-network based tests against.
+    #
     class Bogus
       include VaultedBilling::Gateway
 
@@ -69,4 +79,4 @@ module VaultedBilling
       end
     end
   end
-end
+end

data/lib/vaulted_billing/gateways/nmi_customer_vault.rb

@@ -17,7 +17,6 @@ module VaultedBilling
 
       def initialize(options = {})
         self.live_uri = self.test_uri = "https://secure.nmi.com/api/transact.php"
-        self.ssl_pem = File.read(File.expand_path(File.join(File.dirname(__FILE__), '..', 'certificate_authorities', 'verisign.pem')))
 
         options = HashWithIndifferentAccess.new(options)
         @username = options[:username] || VaultedBilling.config.nmi_customer_vault.username

data/lib/vaulted_billing/https_interface.rb

@@ -41,7 +41,6 @@ module VaultedBilling
     end
 
     attr_writer :use_test_uri
-    attr_writer :ssl_pem
 
     def live_uri=(input)
       @live_uri = input ? URI.parse(input) : nil
@@ -70,12 +69,8 @@ module VaultedBilling
       request.body = data
       response = Net::HTTP.new(uri.host, uri.port).tap do |https|
         https.use_ssl = true
-        if @ssl_pem
-          https.cert = OpenSSL::X509::Certificate.new(@ssl_pem)
-          https.verify_mode = OpenSSL::SSL::VERIFY_PEER
-        else
-          https.verify_mode = OpenSSL::SSL::VERIFY_NONE
-        end
+        https.ca_file = VaultedBilling.config.ca_file
+        https.verify_mode = OpenSSL::SSL::VERIFY_PEER
       end
 
       before_post_caller(data)

data/lib/vaulted_billing/transaction.rb

@@ -1,11 +1,30 @@
 module VaultedBilling
+  ##
+  # This class encapsulates the data returned by the gateway / payment
+  # processor for transaction requests.  An instance of this class will
+  # be returned from all transaction requests (authorize, capture, 
+  # refund, void, etc.) performed against a gateway.
+  #
   class Transaction
+    # The transaction identifier from the processor
     attr_accessor :id
+
+    # The authorization code for the transaction
     attr_accessor :authcode
+
+    # The address verification service response
     attr_accessor :avs_response
+
+    # The card verification number response
     attr_accessor :cvv_response
+
+    # The response code from the processor
     attr_accessor :code
+
+    # The message from the processor
     attr_accessor :message
+
+    # The masked card number used in the transaction, if available
     attr_accessor :masked_card_number
 
     def initialize(attributes = {})

data/lib/vaulted_billing/version.rb

@@ -1,3 +1,3 @@
 module VaultedBilling
-  Version = '0.0.14'
+  Version = '0.0.15'
 end

data/lib/vaulted_billing.rb

@@ -8,8 +8,6 @@ module VaultedBilling
   autoload :Transaction, 'vaulted_billing/transaction'
   autoload :HttpsInterface, 'vaulted_billing/https_interface'
 
-  mattr_accessor :config
-
   Dir[File.expand_path('../vaulted_billing/core_ext/**/*.rb', __FILE__)].each do |extension|
     require extension
   end
@@ -25,10 +23,27 @@ module VaultedBilling
     Gateways.const_get(name.to_s.camelize)
   end
 
+  ##
+  # Returns the VaultedBilling::Configuration.  This is primarily used to
+  # modify the default settings used when new gateways are instantiated.
+  #
   def self.config
     @@config ||= VaultedBilling::Configuration.new
   end
 
+  ##
+  # A helper method to allow you to set the configuration en mass via
+  # a properly formatted Hash of options:
+  #
+  #     VaultedBilling.set_config({
+  #       :test_mode => false,
+  #       :authorize_net_cim => {
+  #         :username => 'APIName',
+  #         :password => 'APIPassword',
+  #         :test_mode => false,
+  #       :nmi_customer_vault => { ... }
+  #     })
+  #
   def self.set_config(options = {})
     @@config = VaultedBilling::Configuration.new(options)
   end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: vaulted_billing
 version: !ruby/object:Gem::Version 
-  hash: 3
   prerelease: false
   segments: 
   - 0
   - 0
-  - 14
-  version: 0.0.14
+  - 15
+  version: 0.0.15
 platform: ruby
 authors: 
 - Nathaniel Bibler
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-21 00:00:00 -05:00
+date: 2011-01-03 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 5
         segments: 
         - 2
         - 3
@@ -41,7 +39,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 15
         segments: 
         - 2
         - 1
@@ -57,7 +54,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 2
         - 3
@@ -73,7 +69,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 25
         segments: 
         - 0
         - 0
@@ -89,7 +84,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 7
         segments: 
         - 1
         - 4
@@ -105,7 +99,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 13
         segments: 
         - 1
         - 6
@@ -121,7 +114,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 31
         segments: 
         - 1
         - 3
@@ -137,7 +129,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 17
         segments: 
         - 0
         - 3
@@ -155,6 +146,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/ext/cacert.pem
 - lib/vaulted_billing/certificate_authorities/entrust.pem
 - lib/vaulted_billing/certificate_authorities/verisign.pem
 - lib/vaulted_billing/configuration.rb
@@ -185,7 +177,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -194,7 +185,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 23
       segments: 
       - 1
       - 3