paytrace 0.1.23 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb8b55937b9c0b2a71ebf27a80842724762b006d
-  data.tar.gz: 872c601caeb2ebe395d9ff3abc1c64edde62f78b
+  metadata.gz: 0c93b4f1327e0d702fb6fb6c45643323f1a98421
+  data.tar.gz: 5461e5901af68ce1c0af687eaec7fed77e9165d9
 SHA512:
-  metadata.gz: fa3d3191c00543ab32e097a41a2b50fe8ab74eff126c64e288ae9d1b74dc841a7316e44706357ea14baca473673674a0561a59e07f82e913a0ccb264336cd44e
-  data.tar.gz: 0b32bc57ddec96fa1007f53118cbfc85fd685d804048a9729ae5356868c783e1fd6a692b3072aff36602321a9772c35a4d76ad28b0f02f7ecd7ca18d382ad574
+  metadata.gz: f2923d19c3f1d19c60988b228481b0d08fa711f80e4adb9e8ee18de5a22a1d1ff0cf17897f1ac7fb070895184047b7a3d6f9ad6a314aef00ee771d45e694ff26
+  data.tar.gz: 07faf40f2999b251eb20ecfdd4a68ecec571efedfa56508fe63fa22f8493a3b745890b1b47bc9b728d3276c0858b8209c06ca15cb17a57c4e45d4ad5dae22af2

data/lib/paytrace/address.rb

@@ -3,6 +3,7 @@ module PayTrace
   # _Note:_ the "region" parameter can only be defined for shipping addresses, and the
   # default address type (if unspecified) is billing.
   class Address
+    # :nodoc:
     attr_accessor :name, :street,:street2,:city,:state, :country,:region,:postal_code,:address_type
 
     ATTRIBUTE_MAP = [
@@ -15,6 +16,7 @@ module PayTrace
       [:postal_code, :postal_code],
       [:country, :country]
     ]
+    # :doc:
 
     # Initialize a new address instance. Parameters are symbolic keys in a hash. They are:
     # * *:name* -- the name on this address

data/lib/paytrace/api/gateway.rb

@@ -14,6 +14,7 @@ module PayTrace
       @@last_response_object = nil
       @@next_response = nil
       @@raise_exceptions = true
+      # :doc:
 
       # Creates a new gateway object, optionally using a supplied connection object
       def initialize(connection = nil)
@@ -58,10 +59,24 @@ module PayTrace
         @@raise_exceptions = raise_exceptions
       end
 
+      # Helper method to abstract away a common use pattern. Creates a request object, sets parameters, creates a gateway object, sends the request, and returns the response.
+      #
+      # Arguments:
+      #
+      # * *param_names* -- the array of parameter names to be set from *arguments*
+      # * *arguments* -- the arguments to be set in the request
+      def self.send_request(method, params, required = [], optional = [])
+        request = Request.new
+        request.set_param(:method, method)
+        request.set_params(params, required, optional)
+        yield request if block_given?
+
+        gateway = Gateway.new
+        gateway.send_request(request)
+      end
+
       # Sends a request object
-      # Params:
-      # * *:multi_value_response_fields* -- response fields that may have multiple entries for the same key
-      def send_request(request, multi_value_response_fields = [])
+      def send_request(request)
         @@last_request = request.to_parms_string if @@debug
         unless (@@debug && @@next_response)
           res = @connection.post PayTrace.configuration.url, parmlist: request.to_parms_string
@@ -71,7 +86,7 @@ module PayTrace
         end
         
         @@last_response = raw_response
-        response = PayTrace::API::Response.new(raw_response, multi_value_response_fields)
+        response = PayTrace::API::Response.new(raw_response)
         @@last_response_object = response
 
         @@next_response = nil # just to be sure

data/lib/paytrace/api/request.rb

@@ -57,30 +57,25 @@ module PayTrace
       end
 
       # :nodoc:
-      def validate_param(k, v)
-        raise PayTrace::Exceptions::ValidationError.new("Unknown field '#{k}'") unless PayTrace::API.fields.has_key?(k)
+      def valid_param?(key, value)
+        if key == :discretionary_data
+          value.is_a?(Hash) || value.nil? # any discretionary data that's a hash or nil should be passed
+        else
+          PayTrace::API.fields.has_key?(key) || value.nil? || value.respond_to?(:set_request)
+        end
       end
-      # :doc:
-
-      # Sets a single request parameters
-      # * *:key* -- the name of the setting
-      # * *:value* -- the value of the setting
-      def set_param(key, value = nil)
-        validate_param(key, value)
-
-        unless value.nil?
-          @params[key] ||= []
 
-          @params[key] << value
-        end
+      def validate_param!(k, v)
+        raise PayTrace::Exceptions::ValidationError.new("Unknown field '#{k}' (value: #{v})") unless valid_param?(k,v)
       end
+      # :doc:
 
       # Sets multiple parameters with the same name using the custom delimiter
-      # * *:param_name* -- the name of the "top level" setting
-      # * *:items* -- a hash of "second level" settings
+      # * *param_name* -- the name of the "top level" setting
+      # * *items* -- a hash of "second level" settings
       def set_multivalue(param_name, items = {})
         result = (items.map do |k,v|
-          validate_param(k, v)
+          validate_param!(k, v)
           "#{PayTrace::API.fields[k]}#{@multi_value_delim}#{v}"
         end.join(@multi_field_delim))
 
@@ -89,9 +84,28 @@ module PayTrace
         result
       end
 
+      # Sets a single request parameters
+      # * *key* -- the name of the setting
+      # * *value* -- the value of the setting
+      #
+      # _Note:_ you can pass in an object that responds to *set_request* as the *value*, and this will invoke *set_request* on it, with this request object as the parameter. Also, any value named *:discretionary_data* that is set will be set in the discretionary hash, not the regular params hash.
+      def set_param(key, value = nil)
+        validate_param!(key, value)
+
+        if value.respond_to?(:set_request)
+          value.set_request(self)
+        elsif key == :discretionary_data
+          set_discretionary(value)
+        elsif value != nil
+          @params[key] ||= []
+
+          @params[key] << value
+        end
+      end
+
       # Sets multiple parameters at once
-      # * *:keys* -- an array of key names to extract from the params hash
-      # * *:params* -- the parameters hash to be extracted from
+      # * *:params* -- the hash or object to fetch the parameters from
+      # * *:required* -- an array of required key names to extract from the params object
       #
       # _Note:_ the values in *:keys* can also include arrays of two values (techincally, a tuple). The sub-array contains the name of the field that will be used in the request, and the name of the field in the params. This allows more succinct parameter names; e.g. *:address* instead of *:billing_address*. Example:
       #
@@ -103,16 +117,46 @@ module PayTrace
       #       :foo,
       #       [:billing_address, :address]
       #     ], params) 
-      def set_params(keys, params)
-        keys.each do |key|
-          if key.is_a?(Array)
-            request_variable = key[0]
-            arg_name = key[1]
-            set_param(request_variable, params[arg_name])
-          else
-            set_param(key, params[key])
-          end
+      def set_params(params, required = [], optional = [])
+        required_remaining, params_remaining = Request.process_param_list(required, params) do |request_variable, arg_name, value|
+          set_param(request_variable, value)
+        end
+
+        # if we're missing *required* parameters, fail...
+        raise PayTrace::Exceptions::ValidationError.new("Missing the following required parameters: #{required_remaining.to_s}") if required_remaining.any?
+
+        optional_remaining, params_remaining = Request.process_param_list(optional, params_remaining) do |request_variable, arg_name, value|
+          set_param(request_variable, value)
         end
+
+        # if we have any EXTRA parameters, fail...
+        raise PayTrace::Exceptions::ValidationError.new("The following parameters are unknown: #{params_remaining.to_s}") if params_remaining && params_remaining.any?
+      end
+
+      # takes a list of permitted keys and a params hash, and returns any missing or extra params, optionally
+      # calling a supplied block once per key
+      def self.process_param_list(key_list, params, &block)
+        if params.is_a?(Hash)
+          accessor = :[]
+          track_params = true
+        else
+          accessor = :send
+          track_params = false
+        end
+        params_remaining = params.dup if track_params
+
+        remaining = key_list.dup
+        key_list.each do |key|
+          request_variable, arg_name = key # de-alias the name, if it's aliased
+          arg_name ||= request_variable # just use the same name for both, if not
+
+          value = params.send(accessor, arg_name) # this allows us to treat hashes and objects the same
+          yield request_variable, arg_name, value if block_given?
+          remaining.delete(key) if value
+          params_remaining.delete(arg_name) if track_params
+        end
+
+        return (remaining.map {|req,arg| arg || req}), (track_params ? params_remaining : nil)
       end
     end
   end

data/lib/paytrace/api/response.rb

@@ -2,21 +2,18 @@ module PayTrace
   module API
     # An object representing an API response from sending a PayTrace::API::Request with a PayTrace::API::Gateway object
     class Response
+      # :nodoc:
       attr_reader :values, :errors
+      # :doc
 
       # Called by the PayTrace::API::Gateway object to initialize a response
-      def initialize(response_string, multi_value_fields = [])
+      def initialize(response_string)
         @field_delim = "|"
         @value_delim = "~"
         @multi_value_delim = "+"
         @values = {}
         @errors = {}
-        parse_response(response_string, multi_value_fields)
-      end
-
-      # Returns the response code(s) received
-      def response_code
-        get_response
+        parse_response(response_string)
       end
 
       # Returns true if the response contained any error codes
@@ -24,8 +21,19 @@ module PayTrace
         @errors.length > 0
       end
 
+      # given a field name, splits the data in that value into an array of record hashes
+      def parse_records(field_name)
+        records = []
+
+        [@values[field_name]].flatten.each do |raw_record|
+          records << Hash[raw_record.split(@multi_value_delim).map {|pair| pair.split('=')}]
+        end
+
+        records
+      end
+
       # Called by the initialize method
-      def parse_response(response_string, multi_value_fields = [])
+      def parse_response(response_string)
 
         if (response_string.include? "ERROR")
            return parse_errors(response_string)
@@ -34,9 +42,9 @@ module PayTrace
         pairs = response_string.split(@field_delim)
         pairs.each do |p|
           k,v = p.split(@value_delim)
-          if multi_value_fields.include?(k)
-            @values[k] ||= []
-            @values[k] << Hash[v.split(@multi_value_delim).map {|pair| pair.split('=')}]
+          if @values.has_key?(k)
+            @values[k] = [@values[k]] unless @values[k].is_a?(Array)
+            @values[k] << v
           else
             @values[k] = v
           end

data/lib/paytrace/batch_operations.rb

@@ -1,9 +1,11 @@
 module PayTrace
   # This class serves as a container for batch processing methods
   class BatchOperations
+    # :nodoc:
     EXPORT_SINGLE_METHOD = "ExportBatch"
     EXPORT_MULTIPLE_METHOD = "ExportBatches"
     EXPORT_DETAILS_METHOD = "ExportBatchDetails"
+    # :doc:
 
     # See http://help.paytrace.com/api-export-single-batch
     #
@@ -12,16 +14,8 @@ module PayTrace
     # Optional parameters hash:
     #
     # * *:batch_number* -- number of the batch of transactions you wish to export
-    def self.exportSingle(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, EXPORT_SINGLE_METHOD)
-      request.set_param(:batch_number, params[:batch_number])
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)      
-      unless response.has_errors?
-        response.values
-      end
+    def self.export_single(params = {})
+      PayTrace::API::Gateway.send_request(EXPORT_SINGLE_METHOD, params, [], [:batch_number])
     end
 
     # See http://help.paytrace.com/api-export-batches
@@ -30,16 +24,8 @@ module PayTrace
     #
     # * *:start_date* -- indicates when to start searching for transactions to export. Must be a valid date formatted as MM/DD/YYYY
     # * *:end_date* -- indicates when to end searching for transactions to export. Must be a valid date formatted as MM/DD/YYYY
-    def self.exportMultiple(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, EXPORT_MULTIPLE_METHOD)
-      request.set_params([:start_date, :end_date], params)
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)      
-      unless response.has_errors?
-        response.values
-      end
+    def self.export_multiple(params = {})
+      PayTrace::API::Gateway.send_request(EXPORT_MULTIPLE_METHOD, params, [:start_date, :end_date])
     end
 
     # See http://help.paytrace.com/api-export-batch-details
@@ -47,16 +33,8 @@ module PayTrace
     # Exports transaction details of a given batch. Required parameters hash:
     #
     # * *:batch_number* -- number of the batch of transactions you wish to export
-    def self.exportDetails(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, EXPORT_DETAILS_METHOD)
-      request.set_param(:batch_number, params[:batch_number])
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)      
-      unless response.has_errors?
-        response.values
-      end
+    def self.export_details(params = {})
+      PayTrace::API::Gateway.send_request(EXPORT_DETAILS_METHOD, params, [:batch_number])
     end
   end
 end

data/lib/paytrace/check_transaction.rb

@@ -1,73 +1,139 @@
 module PayTrace
   # Provides a number of helper methods to process check transactions
   class CheckTransaction
+    # :nodoc:
     PROCESS_SALE_METHOD = "ProcessCheck"
     MANAGE_CHECK_METHOD = "ManageCheck"
 
-    # Process a transaction as a sale. Parameters are passed by symbol name in a hash. 
-    # _Note:_ either supply a customer ID *or* an account/routing number. Although passing in
-    # both sets of data will not raise an error, the backend API will ignore the account/routing
-    # number if the customer ID is supplied
+    # parameters used by several methods
+    COMMON_PARAMETERS = [
+      :check_type, 
+      :amount, :customer_id, :account_number, :routing_number,
+      :email, :invoice, :description, :tax_amount, :customer_reference_id, :billing_address, :shipping_address, :discretionary_data,
+      :test_flag
+    ]
+
+    BILLING_AND_SHIPPING_ADDRESS_FIELDS = [
+      :billing_name,
+      :billing_address,
+      :billing_address2,
+      :billing_city,
+      :billing_state,
+      :billing_postal_code,
+      :billing_country,
+      :shipping_name,
+      :shipping_address,
+      :shipping_address2,
+      :shipping_city,
+      :shipping_state,
+      :shipping_postal_code,
+      :shipping_region,
+      :shipping_country
+    ]
+
+    SALE_OPTIONAL_PARAMETERS = BILLING_AND_SHIPPING_ADDRESS_FIELDS + [
+      :email,
+      :invoice,
+      :description,
+      :tax_amount,
+      :customer_reference_id,
+      :discretionary_data
+    ]
+    # :doc:
+
+    # See http://help.paytrace.com/api-processing-a-check-sale
+    #
+    # Process a transaction as a sale by checking account number and routing number.
     # 
-    # The parameters are:
+    # Required parameters:
+    #
     # * *:check_type* -- the check transaction type; typically "Sale"
     # * *:amount* -- the amount of the check
-    # * *:customer_id* -- the customer ID for the check
     # * *:account_anumber* -- the checking account number
     # * *:routing_number* -- the checking account routing number
-    # * *:email* -- the customer's email
-    # * *:invoice* -- an invoice number to apply to the sale
-    # * *:description* -- a free text description of the sale
-    # * *:tax_amount* -- the tax amount for the sale
-    # * *:customer_reference_id* -- an optional customer reference number
-    # * *:discretionary_data* -- any discretionary data to be applied
-    # * *:shipping_address* -- a shipping address object; see PayTrace::Address
-    # * *:billing_address* -- a billing address object; see PayTrace::Address
-    def self.process_sale(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, PROCESS_SALE_METHOD)
-      self.add_common_parameters(params, request)
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)      
-      unless response.has_errors?
-        response.values
-      end
+    # 
+    # Optional parameters:
+    #
+    # * *:billing_name* -- the billing name for this transaction
+    # * *:billing_address* -- the billing street address for this transaction
+    # * *:billing_address2* -- the billing street address second line (e.g., apartment, suite) for this transaction
+    # * *:billing_city* -- the billing city for this transaction
+    # * *:billing_state* -- the billing state for this transaction
+    # * *:billing_postal_code* -- the billing zip code for this transaction
+    # * *:billing_country* -- the billing country for this transaction
+    # * *:shipping_name* -- the shipping name for this transaction
+    # * *:shipping_address* -- the shipping street address for this transaction
+    # * *:shipping_address2* -- the shipping street address second line (e.g., apartment, suite) for this transaction
+    # * *:shipping_city* -- the shipping city for this transaction
+    # * *:shipping_state* -- the shipping state for this transaction
+    # * *:shipping_postal_code* -- the shipping zip code for this transaction
+    # * *:shipping_region* -- the shipping region (e.g. county) for this transaction
+    # * *:shipping_country* -- the shipping country for this transaction
+    # * *:email* -- the customer email for this transaction
+    # * *:invoice* -- an internal invoice number (customer ID token or referenced transaction sale)
+    # * *:description* -- a description of the sale (customer ID token or referenced transaction sale)
+    # * *:tax_amount* -- the amount of tax on the sale (customer ID token or referenced transaction sale)
+    # * *:customer_reference_id* -- a customer reference ID (customer ID token or referenced transaction sale)
+    # * *:discretionary_data* -- a hash of optional discretionary data to attach to this transaction
+    def self.sale(params = {})
+      PayTrace::API::Gateway.send_request(PROCESS_SALE_METHOD, params, [:check_type, :amount, :routing_number, :account_number], SALE_OPTIONAL_PARAMETERS)
+    end
+
+    # See http://help.paytrace.com/api-processing-a-check-sale
+    #
+    # Process a transaction as a sale by checking account number and routing number.
+    # 
+    # Required parameters:
+    #
+    # * *:check_type* -- the check transaction type; typically "Sale"
+    # * *:amount* -- the amount of the check
+    # * *:customer_id -- the customer ID to reference for this sale
+    # 
+    # Optional parameters are the same as for sale
+    def self.customer_id_sale(params = {})
+      PayTrace::API::Gateway.send_request(PROCESS_SALE_METHOD, params, [:check_type, :amount, :customer_id], SALE_OPTIONAL_PARAMETERS)
     end
 
     # Process a transaction as a hold. Parameters are passed by symbol name in a hash. 
-    # _Note:_ the parameters for this method are identical to process_sale; this is simply
+    # _Note:_ the parameters for this method are identical to sale; this is simply
     # a convenience method. The :check_type is automatically set to "Hold"
-    def self.process_hold(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, PROCESS_SALE_METHOD)
-      params.delete(:check_type) # make sure we don't duplicate this
-      self.add_common_parameters(params, request)
-      request.set_param(:check_type, "Hold")
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)      
-      unless response.has_errors?
-        response.values
-      end
+    def self.hold(params = {})
+      params = params.dup
+      params[:check_type] = "Hold"
+
+      PayTrace::API::Gateway.send_request(PROCESS_SALE_METHOD, params, [], COMMON_PARAMETERS)
     end
 
+
+
     # Process a transaction as a refund. Parameters are passed by symbol name in a hash. 
-    # _Note:_ the parameters for this method are identical to process_sale; this is simply
-    # a convenience method. The :check_type is automatically set to "Hold"
-    def self.process_refund(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, PROCESS_SALE_METHOD)
-      params.delete(:check_type) # make sure we don't duplicate this
-      self.add_common_parameters(params, request)
-      request.set_param(:check_id, params[:check_id])
-      request.set_param(:check_type, "Refund")
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)      
-      unless response.has_errors?
-        response.values
-      end
+    # _Note:_ the parameters for this method are identical to sale; this is simply
+    # a convenience method. The :check_type is automatically set to "Refund"
+    def self.refund(params = {})
+      params = params.dup
+      params[:check_type] = "Refund"
+
+      PayTrace::API::Gateway.send_request(PROCESS_SALE_METHOD, params, [:check_type, :amount, :routing_number, :account_number])
+    end
+
+    # Process a transaction as a refund. Parameters are passed by symbol name in a hash. 
+    # _Note:_ the parameters for this method are identical to sale; this is simply
+    # a convenience method. The :check_type is automatically set to "Refund"
+    def self.refund_by_customer_id(params = {})
+      params = params.dup
+      params[:check_type] = "Refund"
+
+      PayTrace::API::Gateway.send_request(PROCESS_SALE_METHOD, params, [:check_type, :amount, :customer_id])
+    end
+
+    # Process a transaction as a refund. Parameters are passed by symbol name in a hash. 
+    # _Note:_ the parameters for this method are identical to sale; this is simply
+    # a convenience method. The :check_type is automatically set to "Refund"
+    def self.refund_existing_check_id(params = {})
+      params = params.dup
+      params[:check_type] = "Refund"
+
+      PayTrace::API::Gateway.send_request(PROCESS_SALE_METHOD, params, [:check_type, :check_id])
     end
 
     # Manage an existing check, setting a new check type if necessary. Params are passed by symbol
@@ -75,38 +141,7 @@ module PayTrace
     # * *:check_type* -- the (new) type of this check (e.g. "Sale", "Hold", "Refund", etc.)
     # * *:check_id* -- the id of the check to manage
     def self.manage_check(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, MANAGE_CHECK_METHOD)
-      request.set_params([:check_type, :check_id], params)
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)      
-      unless response.has_errors?
-        response.values
-      end
-    end
-
-    # Helper method called by the framework. Do not call directly.
-    def self.add_common_parameters(params = {}, request)
-      request.set_params([
-        :check_type, 
-        :amount, :customer_id, :account_number, :routing_number,
-        :email, :invoice, :description, :tax_amount, :customer_reference_id, :test_flag
-        ], params)
-
-      if params[:discretionary_data] 
-        params[:discretionary_data].keys.each do |k|
-          request.set_discretionary(k, params[:discretionary_data][k])
-        end
-      end
-
-      if params.has_key?(:billing_address)
-        params[:billing_address].set_request(request)
-      end
-
-      if params.has_key?(:shipping_address)
-        params[:shipping_address].set_request(request)
-      end
+      PayTrace::API::Gateway.send_request(MANAGE_CHECK_METHOD, params, [:check_type, :check_id])
     end
   end
 end

data/lib/paytrace/configuration.rb

@@ -1,9 +1,11 @@
 module PayTrace
   # Contains necessary configuration to access the API server; notably the user name, password, and URL information
   class Configuration
+    # :nodoc:
     attr_accessor :user_name, :password, :connection, :domain, :path
 
     RESET_PASSWORD_METHOD = "UpdatePassword"
+    # :doc:
 
     # Default initializer. Do not call directly; instead use the PayTrace.configure method
     # Example: