experian 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 73a404dfa3f7928172bb01a332a7d7acd008963a
+  data.tar.gz: 1cbe21e733ba63c7be1e096f726b1805a48d44ae
+SHA512:
+  metadata.gz: e4c01acf12f4073d200c2c9b8613aa1ad46536dcf9ee44a31fed93d8a52f797f79812bf832210db0b97107f8877581488112bdf15bb1f10fd1d9000ee773b769
+  data.tar.gz: 4fa06a3a87bbec3a8736d546693c4b20da618d4dd71e4eff41a9e7969617c42051aa8c8154b95aa09ad64c7ddfb05374473d491ba6b8c72a8c73374c3402695a

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+
+group :development do
+  gem 'pry'
+end
+
+group :test do
+  gem 'minitest'
+  gem 'webmock'
+  gem 'mocha', require: false
+  gem 'timecop'
+end
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Eric Hutzelman
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# Experian Ruby Gem
+
+Ruby Wrapper for portions of the Experian Net Connect API. Experian exposes nearly 30 different services through the Net Connect API.
+This gem currently only implements the Connect Check product (consumer credit scoring and identity validation), although
+expanding it to support the other products should be straightforward.
+
+*Net Connect is a business-to-business application gateway designed to allow access to Experian legacy systems via the public
+Internet or Experian’s private TCP/IP extranet transport. It is a secure 168-bit encrypted transaction, using HTTPS.
+Net Connect is a non-browser-based system requiring Experian certified client or vendor software at the user's location.
+It utilizes XML for the input inquiry and has the capability of returning field-level XML, as well as our standard Automated
+Response Format (ARF) (computer readable), Teletype Response Format (TTY) (human readable) and Parallel Profile
+(both ARF and TTY in one response). Net Connect meets the encryption standards requirement in the Safeguards section of the
+Gramm- Leach-Bliley (GLB) Act.*
+
+#### Net Connect Products
+
+* Address Update
+* Authentication Services
+* BizID
+* Bullseye
+* Checkpoint - File One Verification Solution
+* Collection Advantage interactive
+* Collection Report
+* **Connect Check (implemented in this gem)**
+* Credit Profile
+* Custom Solution
+* Cross View
+* CU Decision Expert
+* Custom Strategist
+* Decode
+* Demographics
+* Direct Check
+* Employment Insight
+* Fraud Shield
+* Instant Prescreen
+* New Consumer Identification
+* Numeric Inquiry
+* Parallel Profile
+* Profile Summary
+* Precise ID
+* Precise ID Distributed
+* Risk Models
+* Social Search
+* Truvue
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'experian'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install experian
+
+## Usage
+
+### Configuration
+
+Experian will provide you with the following authentication credentials when you sign up for their service:
+```ruby
+# Provide authentication credentials
+Experian.configure do |config|
+  config.eai = "X42PB93F"
+  config.preamble = "FCD2"
+  config.op_initials = "AB"
+  config.subcode = "1968543"
+  config.user = "user"
+  config.password = "password"
+  config.vendor_number = "P55"
+end
+
+# Route requests to Experian test server instead of production
+Experian.test_mode = true
+
+```
+
+### Using a product client
+
+Products are namespaced under the Experian module. Example of how to create a client for the Connect Check product:
+```ruby
+client = Experian::ConnectCheck::Client.new
+```
+
+Once you have a client, you can make requests:
+```ruby
+response = client.check_credit(first_name: "Homer", last_name: "Simpson", ssn: "123456789")
+
+response.success?
+# => true
+response.completion_message
+# => "Request processed successfully"
+response.credit_match_code
+# => "C"
+response.credit_match_code_message
+# => "ID Match"
+response.credit_score
+# => 846
+response.customer_message
+# => "Credit and ID have been verified and no deposit is required."
+response.customer_names
+# => ["HOMER J SIMPSON", "HOMER SIMPSON", "H SIMPSON", "PLOW KING"]
+response.customer_addresses
+# => ["96 JAMESTOWN BLVD  /HAMMONTON NJ 080372110",
+# => "1466 BALLY BUNION DR  /EGG HARBOR CITY NJ 082155118",
+# => "100 WEST LN  /HAMMONTON NJ 080371151"]
+```
+
+Alternatively, you can skip the explicit client instantiation and use the module level convenience method instead:
+```ruby
+response = Experian::ConnectCheck.check_credit(...)
+```
+
+
+### Handling errors from Experian
+```ruby
+response = client.check_credit(first_name: "Homer", last_name: "Simpson", ssn: "NaN")
+
+response.success?
+# => false
+response.error_message
+# => "Invalid request format"
+response.error_action_indicator_message
+# => "Correct and/or resubmit"
+```
+
+### Examine raw request and response XML
+If you need to troubleshoot by viewing the raw xml, it is accesssible on the request and response objects of the client:
+```ruby
+# Inspect the request XML that was sent to Experian
+client.request.xml
+# => "<?xml version='1.0' encoding='utf-8'?>..."
+
+# Inspect the response XML that was received from Experian
+client.response.xml
+# => "<?xml version='1.0' encoding='utf-8'?>..."
+```
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Copyright
+
+Copyright (c) 2012-2013 Eric Hutzelman.
+See [LICENSE][] for details.
+
+[license]: LICENSE.txt

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = "test/**/*_test.rb"
+end
+
+task :default => :test

data/experian.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'experian/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "experian"
+  spec.version       = Experian::VERSION
+  spec.authors       = ["Eric Hutzelman"]
+  spec.email         = ["ehutzelman@gmail.com"]
+  spec.description   = "Ruby gem wrapper for the Experian net connect API."
+  spec.summary       = "Ruby gem wrapper for the Experian net connect API."
+  spec.homepage      = "http://github.com/ehutzelman/experian"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "excon"
+  spec.add_dependency "builder"
+  spec.add_development_dependency "bundler", "~> 1.3"
+end

data/lib/experian.rb

@@ -0,0 +1,73 @@
+require "excon"
+require "builder"
+require "experian/version"
+require "experian/constants"
+require "experian/error"
+require "experian/client"
+require "experian/request"
+require "experian/response"
+require "experian/connect_check"
+
+module Experian
+  include Experian::Constants
+
+  class << self
+
+    attr_accessor :eai, :preamble, :op_initials, :subcode, :user, :password, :vendor_number
+    attr_accessor :test_mode
+
+    def configure
+      yield self
+    end
+
+    def test_mode?
+      !!test_mode
+    end
+
+    def ecals_uri
+      uri = URI(Experian::LOOKUP_SERVLET_URL)
+      uri.query = URI.encode_www_form(
+        'lookupServiceName' => Experian::LOOKUP_SERVICE_NAME,
+        'lookupServiceVersion' => Experian::LOOKUP_SERVICE_VERSION,
+        'serviceName' => service_name,
+        'serviceVersion' => Experian::SERVICE_VERSION,
+        'responseType' => 'text/plain'
+      )
+      uri
+    end
+
+    def net_connect_uri
+      perform_ecals_lookup if ecals_lookup_required?
+
+      # setup basic authentication
+      @net_connect_uri.user = Experian.user
+      @net_connect_uri.password = Experian.password
+
+      @net_connect_uri
+    end
+
+    def perform_ecals_lookup
+      @net_connect_uri = URI.parse(Excon.get(ecals_uri.to_s).body)
+      assert_experian_domain
+      @ecals_last_update = Time.now
+    rescue Excon::Errors::SocketError => e
+      raise Experian::ClientError, "Could not connect to Experian: #{e.message}"
+    end
+
+    def ecals_lookup_required?
+      @net_connect_uri.nil? || @ecals_last_update.nil? || Time.now - @ecals_last_update > Experian::ECALS_TIMEOUT
+    end
+
+    def assert_experian_domain
+      unless @net_connect_uri.host.end_with?('.experian.com')
+        @net_connect_uri = nil
+        raise Experian::ClientError, "Could not authenticate connection to Experian, unexpected host name."
+      end
+    end
+
+    def service_name
+      test_mode? ? Experian::SERVICE_NAME_TEST : Experian::SERVICE_NAME
+    end
+
+  end
+end

data/lib/experian/client.rb

@@ -0,0 +1,29 @@
+module Experian
+  class Client
+
+    attr_reader :request, :response
+
+    def submit_request
+      connection = Excon.new(Experian.net_connect_uri.to_s, idempotent: true)
+      @raw_response = connection.post(body: request_body, headers: request_headers)
+      raise Experian::Forbidden, "Invalid Experian login credentials" if invalid_login?
+      @raw_response.body
+
+    rescue Excon::Errors::SocketError => e
+      raise Experian::ClientError, "Could not connect to Experian: #{e.message}"
+    end
+
+    def request_body
+      URI.encode_www_form('NETCONNECT_TRANSACTION' => request.xml)
+    end
+
+    def request_headers
+      { "Content-Type" => "application/x-www-form-urlencoded" }
+    end
+
+    def invalid_login?
+      !!(@raw_response.headers["Location"] =~ /sso_logon/)
+    end
+
+  end
+end

data/lib/experian/connect_check.rb

@@ -0,0 +1,29 @@
+require 'experian/connect_check/client'
+require 'experian/connect_check/request'
+require 'experian/connect_check/response'
+
+module Experian
+  module ConnectCheck
+
+    MATCH_CODES = {
+      "A" => "Deceased/Non-Issued Social Security Number",
+      "B" => "No Record Found",
+      "C" => "ID Match",
+      "D" => "ID Match to Other Name",
+      "E" => "ID No Match"
+    }
+
+    DB_HOST = "CIS"
+    DB_HOST_TEST = "STAR"
+
+    def self.db_host
+      Experian.test_mode? ? DB_HOST_TEST : DB_HOST
+    end
+
+    # convenience method
+    def self.check_credit(options = {})
+      Client.new.check_credit(options)
+    end
+
+  end
+end

data/lib/experian/connect_check/client.rb

@@ -0,0 +1,19 @@
+module Experian
+  module ConnectCheck
+    class Client < Experian::Client
+
+      def check_credit(options = {})
+        assert_check_credit_options(options)
+        @request = Request.new(options)
+        @response = Response.new(submit_request)
+      end
+
+      def assert_check_credit_options(options)
+        return if options[:first_name] && options[:last_name] && options[:ssn]
+        return if options[:first_name] && options[:last_name] && options[:street] && options[:zip]
+        raise Experian::ArgumentError, "Required options missing: first_name, last_name, ssn OR first_name, last_name, street, zip"
+      end
+
+   end
+  end
+end

data/lib/experian/connect_check/request.rb

@@ -0,0 +1,116 @@
+module Experian
+  module ConnectCheck
+    class Request < Experian::Request
+
+      def build_request
+        super do |xml|
+          xml.tag!('EAI', Experian.eai)
+          xml.tag!('DBHost', ConnectCheck.db_host)
+          add_reference_id(xml)
+          xml.tag!('Request', :xmlns => Experian::XML_REQUEST_NAMESPACE, :version => '1.0') do
+            xml.tag!('Products') do
+              xml.tag!('ConnectCheck') do
+                add_subscriber(xml)
+                add_applicant(xml)
+                add_output_type(xml)
+                add_vendor(xml)
+                add_options(xml)
+              end
+            end
+          end
+        end
+      end
+
+      def add_reference_id(xml)
+        xml.tag!('ReferenceId', @options[:reference_id]) if @options[:reference_id]
+      end
+
+      def add_subscriber(xml)
+        xml.tag!('Subscriber') do
+          xml.tag!('Preamble', Experian.preamble)
+          xml.tag!('OpInitials', Experian.op_initials)
+          xml.tag!('SubCode', Experian.subcode)
+        end
+      end
+
+      def add_applicant(xml)
+        xml.tag!('PrimaryApplicant') do
+          xml.tag!('Name') do
+            xml.tag!('Surname', @options[:last_name])
+            xml.tag!('First', @options[:first_name])
+            xml.tag!('Middle', @options[:middle_name]) if @options[:middle_name]
+            xml.tag!('Gen', @options[:generation_code]) if @options[:generation_code]
+          end
+          xml.tag!('SSN', @options[:ssn]) if @options[:ssn]
+          add_current_address(xml)
+          add_previous_address(xml)
+          add_driver_license(xml)
+          add_employment(xml)
+          xml.tag!('Age', @options[:age]) if @options[:age]
+          xml.tag!('DOB', @options[:dob]) if @options[:dob]
+          xml.tag!('YOB', @options[:yob]) if @options[:yob]
+        end
+      end
+
+      def add_current_address(xml)
+        xml.tag!('CurrentAddress') do
+          xml.tag!('Street', @options[:street])
+          xml.tag!('City', @options[:city])
+          xml.tag!('State', @options[:state])
+          xml.tag!('Zip', @options[:zip])
+        end if @options[:zip]
+      end
+
+      def add_previous_address(xml)
+        xml.tag!('PreviousAddress') do
+          xml.tag!('Street', @options[:previous_street])
+          xml.tag!('City', @options[:previous_city])
+          xml.tag!('State', @options[:previous_state])
+          xml.tag!('Zip', @options[:previous_zip])
+        end if @options[:previous_zip]
+      end
+
+      def add_driver_license(xml)
+        xml.tag!('DriverLicense') do
+          xml.tag!('State', @options[:driver_license_state])
+          xml.tag!('Number', @options[:driver_license_number])
+        end if @options[:driver_license_number]
+      end
+
+      def add_employment(xml)
+        # Not Implemented
+      end
+
+      def add_account_type(xml)
+        xml.tag!('AccountType') do
+          xml.tag!('Type', @options[:account_type])
+          xml.tag!('Terms', @options[:account_terms])
+          xml.tag!('FullAmount', @options[:account_full_amount])
+          xml.tag!('AbbreviatedAmount', @options[:account_abbreviated_amount])
+        end if @options[:account_type]
+      end
+
+      def add_output_type(xml)
+        xml.tag!('OutputType') do
+          xml.tag!('ARF') do
+            xml.tag!('ARFVersion', Experian::ARF_VERSION)
+          end
+        end
+      end
+
+      def add_vendor(xml)
+        xml.tag!('Vendor') do
+          xml.tag!('VendorNumber', Experian.vendor_number)
+        end
+      end
+
+      def add_options(xml)
+        xml.tag!('Options') do
+          xml.tag!('ReferenceNumber', @options[:reference_number])
+          xml.tag!('EndUser', @options[:end_user])
+        end if @options[:reference_number]
+      end
+
+    end
+  end
+end