ach_client 0.5.1

data/lib/ach_client/providers/soap/ach_works/ach_transaction.rb

@@ -0,0 +1,80 @@
+module AchClient
+  class AchWorks
+
+    # AchWorks implementation for AchTransaction
+    class AchTransaction < Abstract::AchTransaction
+
+      ##
+      # @param super [Array] args from parent class
+      # @param customer_id [String] optional identifier for the customer
+      def self.arguments
+        super + [:customer_id]
+      end
+
+      attr_reader :customer_id
+
+      # Send this transaction individually to AchWorks
+      # @return [String] the front end trace
+      def send
+        AchClient::AchWorks.wrap_request(
+          method: :send_ach_trans,
+          message: AchClient::AchWorks::CompanyInfo.build.to_hash.merge({
+            InpACHTransRecord: self.to_hash
+          }),
+          path: [:send_ach_trans_response, :send_ach_trans_result]
+        )[:front_end_trace]
+      end
+
+      ##
+      # @return [Hash] turns this transaction into a hash that can be sent to
+      # AchWorks
+      def to_hash
+        {
+          SSS: AchClient::AchWorks.s_s_s,
+          LocID: AchClient::AchWorks.loc_i_d,
+          FrontEndTrace: front_end_trace,
+          CustomerName: merchant_name,
+          CustomerRoutingNo: routing_number.to_s,
+          CustomerAcctNo: account_number.to_s,
+          OriginatorName: originator_name.try(:first, 16),
+          TransactionCode: sec_code,
+          CustTransType:
+            AchClient::AchWorks::TransactionTypeTransformer.serialize_to_provider_value(
+              transaction_type
+            ),
+          CustomerID: customer_id,
+          CustomerAcctType:
+            AchClient::AchWorks::AccountTypeTransformer.serialize_to_provider_value(
+              self.account_type
+            ),
+          TransAmount: amount,
+          CheckOrTransDate: DateFormatter.format(effective_entry_date),
+          EffectiveDate: DateFormatter.format(effective_entry_date),
+          Memo: memo.try(:first, 10),
+          OpCode: 'S', # Check this
+          AccountSet: '1'
+        }
+      end
+
+      # AchWorks Ach needs a "FrontEndTrace", for each ACH transaction.
+      # These can be used to track the processing of the ACH after it has been
+      # submitted.
+      # You can use the id of your Ach record
+      # It should be unique per ACH
+      # The consumer is responsible for ensuring the uniqueness of this value
+      # @return [String] the 12 char front end trace
+      def front_end_trace
+        # I want to stop this before it goes through because AchWorks might
+        # just truncate the value, which could result in lost Achs.
+        if external_ach_id.length > 11
+          raise 'AchWorks requires a FrontEndTrace of 12 chars or less'
+        else
+          # The front end trace MUST NOT start with a W.
+          # Our front end trace starts with a Z.
+          # The letter Z is not the letter W.
+          "Z#{external_ach_id}"
+        end
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/ach_works.rb

@@ -0,0 +1,57 @@
+require 'active_support/all'
+require_relative '../soap_provider'
+
+module AchClient
+  # Namespace class for all things AchWorks
+  # Contains class attributes with various initialization settings
+  class AchWorks
+
+    # See concern for functionality shared with other providers that SOAP it up
+    include SoapProvider
+
+    # @return [String] A key that they give you used as a password
+    class_attribute :company_key
+
+    # @return [String] Your user id string, used as a username
+    class_attribute :company
+
+    # @return [String] Another Arbitrary 4 letter code AchWorks gives you...
+    class_attribute :loc_i_d
+
+    # @return [String] Arbitrary 3 letter code AchWorks gives your company
+    class_attribute :s_s_s
+
+    # Handles making request to AchWorks.
+    # If the request was successful, returns the response
+    # If it is unsuccessful, tries to find the error message and raises it in
+    # an exception
+    # @param method [Symbol] SOAP operation to call against AchWorks
+    # @param message [Hash] The request body
+    # @param path [Array<Symbol>] Path to the attributes we care about (and the
+    # status field) within the response hash. For example, if you have a burrito
+    # but only care about the guacomole, the path to the hash with the guac
+    # would be: [:aluminum_foil, :tortilla]
+    # @return [Hash] The hash the input path led to within the response hash, if
+    # the response was successful.
+    def self.wrap_request(method:, message:, path:)
+      response = self.request(method: method, message: message)
+      if response.success?
+        response = path.reduce(response.body) {|r, node| r[node] }
+        if response[:status] == 'SUCCESS'
+          # It worked! Return the response hash
+          response
+        else
+          # AchWorks likes to keep things interesting by sometimes putting
+          # the error messages in the details field instead of errors.
+          raise response.try(:[], :errors)
+                        .try(:[], :string)
+                        .try(:join, ', ') ||
+                response[:details]
+        end
+      else
+        # This would normally raise an exception on its own, but just in case
+        raise "#{method} failed due to unknown SOAP fault"
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/company_info.rb

@@ -0,0 +1,87 @@
+module AchClient
+  class AchWorks
+    # This is the ACHworks "credentials" for your company
+    class CompanyInfo < Abstract::CompanyInfo
+
+      attr_reader :company_key,
+                  :company,
+                  :loc_i_d,
+                  :s_s_s
+
+      ##
+      # @param s_s_s [String] Arbitrary 3 letter code they give your company
+      # @param loc_i_d [String] Another Arbitrary 4 letter code they give you...
+      # @param company [String] Your user id string, used as a username
+      # @param company_key [String] A key that they give you used as a password
+      # Since all these fields are generated by them, and don't change, it
+      # really seems like they could use just one.
+      def initialize(
+        company_key:,
+        company:,
+        loc_i_d:,
+        s_s_s:
+      )
+        @company = company
+        @company_key = company_key
+        @loc_i_d = loc_i_d
+        @s_s_s = s_s_s
+      end
+
+      ##
+      # @return [CompanyInfo] instance built from configuration values
+      def self.build
+        build_from_config([
+          :company_key,
+          :company,
+          :loc_i_d,
+          :s_s_s
+        ])
+      end
+
+      # Wraps: http://tstsvr.achworks.com/dnet/achws.asmx?op=ConnectionCheck
+      # Checks validity of company info
+      # @return whether or not the request was successful
+      def connection_valid?
+        connection_check_request(method: :connection_check)
+      end
+
+      # Wraps: http://tstsvr.achworks.com/dnet/achws.asmx?op=CheckCompanyStatus
+      # Checks company status
+      # @return whether or not the request was successful
+      def company_valid?
+        connection_check_request(method: :check_company_status)
+      end
+
+      # Calls both company_valid? and connection_valid?
+      # Checks the validity of company info
+      # @return whether or not the validity check requests were successful
+      def valid?
+        connection_valid? && company_valid?
+      end
+
+      ##
+      # Build a hash to send to ACHWorks under the InpCompanyInfo XML path
+      # @return [Hash] hash to send to ACHWorks
+      def to_hash
+        {
+          InpCompanyInfo: self.instance_variables.map do |var|
+            {
+              var.to_s.split('@').last.camelize.to_sym =>
+                self.instance_variable_get(var)
+            }
+          end.reduce(&:merge)
+        }
+      end
+
+      private
+      def connection_check_request(method:)
+        AchClient::AchWorks.request(
+          method: method,
+          message: self.to_hash
+        ).body["#{method}_response".to_sym]["#{method}_result".to_sym].include?(
+          'SUCCESS'
+        )
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/correction_details_processor.rb

@@ -0,0 +1,92 @@
+module AchClient
+  class AchWorks
+    # Turns the gibberish string that AchWorks gives us for correction returns
+    # when possible into meaningful data
+    class CorrectionDetailsProcessor
+
+      # Turns the gibberish string that AchWorks gives us for correction returns
+      # when possible into meaningful data
+      # @param gibberish [String] the string that AchWorks gave you
+      # @return [Hash] a key value pairing of corrected attributes and their
+      #   values. When possible.
+      def self.decipher_correction_details(gibberish)
+        # The correction code is the first 3 chars of the gibberish.
+        # The meaning of the rest of the giberish depends on the correction
+        #   code. These meanings are sometimes enumerated in the AchWorks
+        #   documentation.
+        self.send(('decipher_' + gibberish[0..2]).to_sym, gibberish)
+      end
+
+      ##
+      # If it looks like we tried to call a function for an unknown correction
+      # code, then return the unhanlded correction data hash
+      def self.method_missing(method, *args, &block)
+        if method.to_s.start_with?('decipher_')
+          if (gibberish = args[0]) && gibberish.is_a?(String)
+            self.decipher_unknown(gibberish)
+          end
+        else
+          super
+        end
+      end
+
+      # CO3: The routing number and the account number were wrong.
+      def self.decipher_C03(gibberish)
+        {
+          routing_number: gibberish[3..11],
+          account_number: gibberish[15..31]
+        }
+      end
+
+      # Discrepency between AchWorks and standard correction codes:
+      # AchWorks: The account number and transaction code were wrong.
+      # Everyone else: The account number and account type (checking/saving)
+      #   were wrong.
+      # However, AchWorks indicates that the "transaction code" is only 1
+      #   character long within their gibberish string. Their transaction
+      #   codes are usually 3 characters, while their account types are one
+      #   character. So I will assume that "transaction code" means
+      #   "account type".
+      # C06: The account number and account type were wrong
+      def self.decipher_C06(gibberish)
+        {
+          account_number: gibberish[3..19],
+          account_type:
+            AchClient::AchWorks::AccountTypeTransformer.deserialize_provider_value(
+              gibberish[23]
+            )
+        }
+      end
+
+      # C07: The account number, routing number, and account type were all
+      #   incorrect. You really messed this one up.
+      # Same issue as above with Transaction Code => Account Type
+      # At least they were consistently discrepent.
+      def self.decipher_C07(gibberish)
+        {
+          routing_number: gibberish[3..11],
+          account_number: gibberish[12..28],
+          account_type:
+            AchClient::AchWorks::AccountTypeTransformer.deserialize_provider_value(
+              gibberish[29]
+            )
+        }
+      end
+
+      # The rest of the cases are undocumented. We will expose the raw data
+      #   given to us, along with a nice note that explains the situation
+      #   while shaming AchWorks.
+      def self.decipher_unknown(gibberish)
+        {
+          unhandled_correction_data: gibberish[3..-1],
+          note: 'AchWorks failed to document this correction code, so we ' +
+          'can\'t tell you what this data means. You might be able to find ' +
+          'out by contacting them. Alternatively, you could check the ' +
+          'AchWorks web console, and match your records against theirs to ' +
+          'see what changed. Enjoy! Let us know what you find, and maybe we' +
+          ' can handle this case in the future.'
+        }
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/date_formatter.rb

@@ -0,0 +1,33 @@
+module AchClient
+  class AchWorks
+    ##
+    # For formatting dates for AchWorks
+    class DateFormatter
+
+      ##
+      # Formats given date in the manner required by AchWorks
+      # The date can be a String or a Date/DateTime.
+      # If it is a string it will be given to the DateTime parser
+      # Will be formatted like 2016-08-11T09:56:24.35103-04:00
+      # @param date [Object] String or Date to format
+      # @return [String] formatted datetime
+      def self.format(date)
+        if date.is_a?(String)
+          format_string(date)
+        elsif date.respond_to?(:strftime)
+          format_date(date)
+        else
+          raise 'Cannot format date'
+        end
+      end
+
+      private_class_method def self.format_string(string)
+        format_date(DateTime.parse(string))
+      end
+
+      private_class_method def self.format_date(date)
+        date.strftime('%Y-%m-%dT%H:%M:%S.%5N%:z')
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/response_record_processor.rb

@@ -0,0 +1,91 @@
+module AchClient
+  class AchWorks
+    # Processes individual response records from AchWorks
+    class ResponseRecordProcessor < Abstract::ResponseRecordProcessor
+
+      # Find the response code in the response record and delegate to the
+      # appropriate handler method
+      # @param record [Hash] AchWorks response hash
+      # @return [AchClient::AchResponse] response
+      def self.process_response_record(record)
+        self.send(('process_' + record[:response_code]).to_sym, record)
+      end
+
+      ##
+      # If it looks like we tried to call a function for an unknown response
+      # code, then raise an exception so we know what kind of crazy response
+      # codes they are sending us
+      def self.method_missing(method, *args, &block)
+        if method.to_s.start_with?('process_')
+          if (record = args[0]) && record.is_a?(Hash)
+            raise "Unknown response code #{record[:response_code]}"
+          end
+        else
+          super
+        end
+      end
+
+      # 1SNT: The transaction has been sent, but not yet processed
+      # @param record [Hash] AchWorks response hash
+      # @return [AchClient::ProcessingAchResponse] processing response
+      def self.process_1SNT(record)
+        AchClient::ProcessingAchResponse.new(
+          amount: BigDecimal.new(record[:trans_amount]),
+          date: record[:action_date]
+        )
+      end
+
+      # 2STL: The transaction is settled. Huzzah!
+      # @param record [Hash] AchWorks response hash
+      # @return [AchClient::SettledAchResponse] settled response
+      def self.process_2STL(record)
+        AchClient::SettledAchResponse.new(
+          amount: BigDecimal.new(record[:trans_amount]),
+          date: record[:action_date]
+        )
+      end
+
+      # 3RET: The transaction was returned for some reason (insufficient
+      #   funds, invalid account, etc)
+      # @param record [Hash] AchWorks response hash
+      # @return [AchClient::ReturnedAchResponse] returned response
+      def self.process_3RET(record)
+        AchClient::ReturnedAchResponse.new(
+          amount: BigDecimal.new(record[:trans_amount]),
+          date: record[:action_date],
+          return_code: AchClient::ReturnCodes.find_by(
+            code: record[:action_detail][0..2]
+          )
+        )
+      end
+
+      # 4INT: AchWorks already knows the transaction would result in a
+      #   return, so they didn't bother sending it to the bank.
+      # @param record [Hash] AchWorks response hash
+      # @return [AchClient::ReturnedAchResponse] returned response
+      def self.process_4INT(record)
+        self.process_3RET(record)
+      end
+
+      # 5COR: Corrected account details (new account number, bank buys
+      #   another bank, etc). You are responsible for updating your records,
+      #   and making the request with the new info, lest AchWorks will be
+      #   most displeased.
+      # @param record [Hash] AchWorks response hash
+      # @return [AchClient::CorrectedAchResponse] corrected response
+      def self.process_5COR(record)
+        AchClient::CorrectedAchResponse.new(
+          amount: BigDecimal.new(record[:trans_amount]),
+          date: record[:action_date],
+          return_code: AchClient::ReturnCodes.find_by(
+            code: record[:action_detail][0..2]
+          ),
+          corrections: AchClient::AchWorks::CorrectionDetailsProcessor
+            .decipher_correction_details(record[:action_detail])
+        )
+      end
+
+      # Not pictured: 9BNK
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/transaction_type_transformer.rb

@@ -0,0 +1,18 @@
+module AchClient
+  class AchWorks
+    ##
+    # Transforms TransactionTypes between AchClient class and the string
+    # that AchWorks expects
+    class TransactionTypeTransformer < AchClient::Transformer
+
+      # 'C' means Credit, 'D' means Debit
+      # @return [Hash {String => Class}] the mapping
+      def self.transformer
+        {
+          'C' => AchClient::TransactionTypes::Credit,
+          'D' => AchClient::TransactionTypes::Debit
+        }
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/i_check_gateway/account_type_transformer.rb

@@ -0,0 +1,20 @@
+module AchClient
+  class ICheckGateway
+    ##
+    # Transforms AccountTypes between AchClient class and the string
+    # that ICheckGateway expects
+    class AccountTypeTransformer < AchClient::Transformer
+      # 'B' means Business, 'P' means Personal
+      # 'C' means Checking, 'S' means Savings
+      # @return [Hash {String => Class}] the mapping
+      def self.transformer
+        {
+          'PS' => AchClient::AccountTypes::PersonalSavings,
+          'PC' => AchClient::AccountTypes::PersonalChecking,
+          'BS' => AchClient::AccountTypes::BusinessSavings,
+          'BC' => AchClient::AccountTypes::BusinessChecking
+        }
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/i_check_gateway/ach_batch.rb

@@ -0,0 +1,12 @@
+module AchClient
+  class ICheckGateway
+    # Implementation of AchBatch for ICheckGateway
+    class AchBatch < Abstract::AchBatch
+
+      # ICheckGateway does not support ACH batching
+      def send_batch
+        raise 'ICheckGateway does not support ACH batching'
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/i_check_gateway/ach_status_checker.rb

@@ -0,0 +1,35 @@
+module AchClient
+  class ICheckGateway
+    # Poll ICheckGateway for status of processed or processing Ach transactions.
+    class AchStatusChecker < Abstract::AchStatusChecker
+      ##
+      # ICheckGateway does not support this
+      def self.most_recent
+        # In the future, this might just return the last 24 hours or something
+        raise 'ICheckGateway does not have a most_recent bucket'
+      end
+
+      # Wrapper for the range response endpoint
+      # @return [Hash{String => AchClient::AchResponse}] Hash with confirmation
+      # number as the key, AchResponse objects as values
+      def self.in_range(start_date:, end_date:)
+        AchClient::ICheckGateway.wrap_request(
+          method: :pull_transaction_report,
+          message: AchClient::ICheckGateway::CompanyInfo.build.to_hash.merge({
+            startDate: start_date,
+            endDate: end_date
+          })
+        ).split("\n").select do |record|
+          # Ignore credit card swipes if there are any
+          record.start_with?('ICHECK')
+        end.map do |record|
+          {
+            record.split('|')[3] =>
+              AchClient::ICheckGateway::ResponseRecordProcessor
+                .process_response_record(record)
+          }
+        end.reduce(&:merge)
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/i_check_gateway/ach_transaction.rb

@@ -0,0 +1,53 @@
+module AchClient
+  class ICheckGateway
+    # ICheckGateway implementation for AchTransaction
+    class AchTransaction < Abstract::AchTransaction
+
+      # Sends this transaction to ICheckGateway
+      # If successful, returns a string from the response that seems to be
+      # a unique identifier for the transaction from ICheckGateway
+      # Raises an exception with as much info as possible if something goes
+      # wrong
+      # @return [String] a string returned by ICheckGateway - external_ach_id
+      def send
+        # The response comes back as a | separated list of field values with
+        #   no header field/keys. It seems that the first column will contain
+        #   'APPROVED' if the request was successful. The 8th column is the
+        #   confirmation number
+        response = AchClient::ICheckGateway.wrap_request(
+          method: :process_check,
+          message: self.to_hash
+        ).split('|')
+        if response[0] == 'APPROVED'
+          # Return the confirmation number
+          response[7]
+        else
+          # Don't have a reliable way of getting the error message, so we will
+          # just raise the whole response.
+          raise "ICheckGateway ACH Transaction Failure: #{response.join('|')}"
+        end
+      end
+
+      ## Turns this transaction into a Hash that can be sent via soap to the
+      # provider
+      # @return [Hash] payload for ICheckGateway
+      def to_hash
+        AchClient::ICheckGateway::CompanyInfo.build.to_hash.merge({
+          APIMethod: 'ProcessCheck',
+          Amount: amount,
+          RoutingNumber: routing_number.to_s,
+          AccountNumber: account_number.to_s,
+          AccountType: AchClient::ICheckGateway::AccountTypeTransformer
+                         .serialize_to_provider_value(account_type),
+          EntryClassCode: sec_code,
+          TransactionType:
+            AchClient::ICheckGateway::TransactionTypeTransformer
+              .serialize_to_provider_value(transaction_type),
+          CompanyName: merchant_name,
+          Description: memo,
+          TransactionDate: effective_entry_date
+        })
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/i_check_gateway/company_info.rb

@@ -0,0 +1,51 @@
+module AchClient
+  class ICheckGateway
+    # ICheckGateway credentials for your company
+    class CompanyInfo < Abstract::CompanyInfo
+      attr_reader :api_key,
+                  :site_i_d,
+                  :site_key,
+                  :live
+
+      ##
+      # @param api_key [String] your ICheckGateway API key
+      # @param site_i_d [String] your ICheckGateway SiteID
+      # @param site_key [String] your ICheckGateway SiteKey
+      # @param live [Boolean] "GatewayLiveMode" value
+      def initialize(
+        api_key:,
+        site_i_d:,
+        site_key:,
+        live:
+      )
+        @api_key = api_key
+        @site_i_d = site_i_d
+        @site_key = site_key
+        @live = live
+      end
+
+      ##
+      # @return [CompanyInfo] instance built from configuration values
+      def self.build
+        build_from_config([
+          :api_key,
+          :live,
+          :site_i_d,
+          :site_key
+        ])
+      end
+
+      ##
+      # Build a hash to send to ICheckGateway
+      # @return [Hash] hash to send to ICheckGateway
+      def to_hash
+        {
+          SiteID: @site_i_d,
+          SiteKey: @site_key,
+          APIKey: @api_key,
+          GatewayLiveMode: @live ? '1' : '0'
+        }
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/i_check_gateway/i_check_gateway.rb

@@ -0,0 +1,39 @@
+module AchClient
+  # Wrapper class for all things ICheckGateway
+  class ICheckGateway
+    include SoapProvider
+
+    # @return [String] Site identifier from ICheckGateway
+    class_attribute :site_i_d
+
+    # @return [String] Site key from ICheckGateway
+    class_attribute :site_key
+
+    # @return [String] API key from ICheckGateway
+    class_attribute :api_key
+
+    # @return [Boolean] ICheckGateway GatewayLiveMode setting
+    # ICheckGateway uses their production environment for test/sandbox accounts
+    # Set this to false if you don't want your transactions to actually complete
+    class_attribute :live
+
+    ## Wraps SOAP request with exception handling and pulls relevent hash out of
+    # response
+    # @param method [Symbol] SOAP action to call
+    # @param message [Hash] SOAP message to send
+    # @return [Hash] ICheckGateway response
+    def self.wrap_request(method:, message:)
+      response = AchClient::ICheckGateway.request(
+        method: method,
+        message: message
+      )
+      if response.success?
+        response.body["#{method}_response".to_sym]["#{method}_result".to_sym]
+      else
+        # This happens when something goes wrong within the actual HTTP
+        #   request before it gets to the soap processing.
+        raise 'Unknown ICheckGateway SOAP fault'
+      end
+    end
+  end
+end