ach_client 1.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ebc1c8a970fae00ba2d286d1a44d9b21dccfe153943112cf5aa8c2b55684944
-  data.tar.gz: '0479726dff32adff969b8e5411aa4df9752d122ebc29dea6942bdf2afa894114'
+  metadata.gz: 8e40c40c7ee42a6264c64f512772b254fac48b70cb7bb323ba238594c3d2d50c
+  data.tar.gz: a6d925e6f0a9682e085de0f1d12240c827cf769d521ee66fabe7001ade43fd64
 SHA512:
-  metadata.gz: 6cac06e017d5919800b050cbd0f839e1b288df41391fe4876766f7c26c2d4bd5910755abfd41c44c17b41c5114e29b31ec6944fc8e197a36b6ce5ebba3ee5226
-  data.tar.gz: 440a98bc9db3ee2cc0158ecd05665e6c80105d6fd35d48becfe41de1cd69f97f9675d25449850294b8e040d5059f05e7567ff0d14914d5d0bc55c2a9817ecde2
+  metadata.gz: 86303a731c6e1c4de5f4a82fa8a12f2f9f955e3ef70601c423d907282b50e2e5992a762f4736223bab87672b28a86b566fa112c55c0e9a0f7fd2c9c819dbc6c3
+  data.tar.gz: 71299fac7355cd6b0a48e0245e8aa19e01f809f4acdcc00f97afda028c0f18dc0bb8792fabd5b242c6e590317f83385cef7e434fac395d3ad3ac8371897a1cc4

data/.travis.yml

@@ -1,10 +1,15 @@
 language: ruby
-script:
-- bundle exec rake test
-- bundle exec codeclimate-test-reporter
 before_install:
-- export TZ=US/Eastern
-- export CODECLIMATE_REPO_TOKEN=1fc324a28beed303e632765cca14487904a23023d85b9127a288f04cc007d28d
-- date
+  - export TZ=US/Eastern
+  - export CODECLIMATE_REPO_TOKEN=1fc324a28beed303e632765cca14487904a23023d85b9127a288f04cc007d28d
+  - export CC_TEST_REPORTER_ID=1fc324a28beed303e632765cca14487904a23023d85b9127a288f04cc007d28d
+  - date
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rake test
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
 notifications:
   email: false

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+### 2.1.0
+
+* Add AchClient::Fake::AchStatusChecker to facilitate response poller testing
+
+### 2.0.0
+
+* Add new AchClient::ICheckGateway::InstantRejectionError to handle API errors raised by ICheckGateway in situations
+where other providers would accept the transaction and issue a return when polling in the future. This is a breaking
+change as previous versions would raise a RuntimeError with the message 'ICheckGateway ACH Transaction Failure' and
+including the API response.
+
+* Include "internal corrections" (return codes starting with 'XZ') in the AchClient::ReturnCode#correction? predicate
+
+### 1.1.0
+
+* Add AchClient::Fake provider to facilitate testing
+
+### 1.0.3
+
+* Add presumed description for X09 return code
+
+### 1.0.2
+
+* Add previously undocumented X01 internal return code
+
+### 1.0.1
+
+* Remove newline characters from fields before generating NACHA files
+
+### 1.0.0
+
+* Prior to 1.0.0, ach_client did not have a stable API.

data/README.md

@@ -115,6 +115,16 @@ returned by the `#send` method. So you should:
 
 4) When you eventually poll the provider for the status of your transactions, you can use the `external_ach_id` you stored to reconcile the returned data against your records
 
+### ICheckGateway instant rejection caveat
+
+ICheckGateway sometimes returns an API error when a valid ACH transaction is sent in a handful of
+rejection scenarios. This is unusual because most providers will accept the transaction, return an
+`external_ach_id`, and then supply the rejection info when you poll for responses (see section on response polling
+below) at a later date. This idiosyncrasy is handled by raising an exception `InstantRejectionError` which contains
+information about the premature ACH return. In this case, no `external_ach_id` is returned by the `#send` method
+because ICheck does not return one, nor do they maintain a record of the transaction in their system. See the
+`InstantRejectionError` class for more details.
+
 ## Batched ACH transactions
 
 A group of ACH transactions can also be sent in a single batched transaction to
@@ -145,6 +155,12 @@ SFTP+NACHA providers take an optional `batch_number` parameter which may be used
   )
 ```
 
+## Testing
+
+A fake ACH provider (in the `AchClient::Fake` namespace) is included to facilitate testing on staging environments.
+This provider behaves the same way as any other without actually sending any transactions. The transaction sending
+methods return the given `external_ach_id`s with no side-effects.
+
 ## Response Polling - Checking Transaction Status
 
 None of the providers support querying for transaction status by external_ach_id. Instead, we must query by date and
@@ -181,6 +197,12 @@ information has changed. Check the return code on the response object for
 details on what happened. Check the corrections hash on the response object for
 the new attributes
 
+### Testing
+
+The fake ACH provider namespace provides a status checker `AchClient::Fake::AchStatusChecker` that always returns the
+same responses. The external_ach_id for each response will be one of
+`['processing', 'settled', 'returned', 'corrected', 'late_returned']`
+
 ## Logging
 
 For record keeping purposes, there is a log provider that allows you to hook

data/ach_client.gemspec

@@ -43,13 +43,12 @@ Gem::Specification.new do |spec|
   # Asynchronocity w/out extra infrastucture dependency (database/redis)
   spec.add_dependency 'sucker_punch', '~> 2'
 
-  spec.add_development_dependency 'bundler', '~> 1.12'
   spec.add_development_dependency 'codeclimate-test-reporter'
   spec.add_development_dependency 'minitest-reporters'
   spec.add_development_dependency 'minitest', '~> 5'
-  spec.add_development_dependency 'mocha'
+  spec.add_development_dependency 'mocha', '~> 1'
   spec.add_development_dependency 'pry'
-  spec.add_development_dependency 'rake', '~> 10'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'timecop'
   spec.add_development_dependency 'vcr'

data/config/return_codes.yml

@@ -343,6 +343,10 @@
   code: 'X00'
   description: "Ok for submission"
   reason: "Ok for submission"
+-
+  code: 'X01'
+  description: "The available and/or cash reserve balance is not sufficient to cover the dollar value of the debit Entry."
+  reason: "Insufficient Funds"
 -
   code: 'X02'
   description: "A previously active account has been closed by action of the customer or the RDFI."
@@ -367,6 +371,10 @@
   code: 'X08'
   description: "The Receiver has placed a stop payment order on this debit Entry."
   reason: "Payment Stopped"
+-
+  code: 'X09'
+  description: "A sufficient ledger balance exists to satisfy the dollar value of the transaction, but the available balance is below the dollar value of the debit Entry."
+  reason: "Uncollected funds due to uncleared deposit"
 -
   code: 'X10'
   description: "The RDFI has been notified by the Receiver that the Entry is unauthorized, improper, or ineligible."

data/lib/ach_client/objects/return_code.rb

@@ -9,6 +9,9 @@ module AchClient
     # The first character in an internal return code
     INTERNAL_START_CHARACTER = 'X'
 
+    # Returns that are both internal and corrections start with this string
+    INTERNAL_CORRECTION_STRING = 'XZ'
+
     attr_accessor :code,
                   :description,
                   :reason
@@ -25,7 +28,7 @@ module AchClient
 
     # @return Whether or not this return is a correction/notice of change
     def correction?
-      @code.start_with?(CORRECTION_START_CHARACTER)
+      @code.start_with?(CORRECTION_START_CHARACTER) || @code.start_with?(INTERNAL_CORRECTION_STRING)
     end
 
     # @return Whether or not the return is internal

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

@@ -0,0 +1,11 @@
+module AchClient
+  class Fake
+    class AchBatch < Abstract::AchBatch
+
+      # Fake batch ACH sending just returns the provided external_ach_ids to indicate success
+      def do_send_batch
+        @ach_transactions.map(&:external_ach_id)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module AchClient
+  class Fake
+    # Fake ACH polling that always returns the same set of results.
+    class AchStatusChecker < Abstract::AchStatusChecker
+
+      def self.most_recent
+        in_range(start_date: Date.today - 3.days, end_date: Date.today)
+      end
+
+      def self.in_range(start_date:, end_date:)
+        {
+          'processing' => [AchClient::ProcessingAchResponse.new(amount: 100.0, date: start_date)],
+          'settled' => [AchClient::SettledAchResponse.new(amount: 100.0, date: start_date)],
+          'returned' => [
+            AchClient::ReturnedAchResponse.new(
+              amount: 100.0,
+              date: start_date,
+              return_code: AchClient::ReturnCodes.find_by(code: 'R01')
+            )
+          ],
+          'corrected' => [
+            AchClient::CorrectedAchResponse.new(
+              amount: 100.0,
+              date: start_date,
+              return_code: AchClient::ReturnCodes.find_by(code: 'XZ2'),
+              corrections: '123456789'
+            )
+          ],
+          'late_returned' => [
+            AchClient::SettledAchResponse.new(amount: 100.0, date: start_date),
+            AchClient::ReturnedAchResponse.new(
+              amount: 100.0,
+              date: end_date,
+              return_code: AchClient::ReturnCodes.find_by(code: 'R08')
+            )
+          ]
+        }
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module AchClient
+  class Fake
+    class AchTransaction < Abstract::AchTransaction
+
+      # Fake ACH sending just returns the provided external_ach_id to indicate success
+      def do_send
+        external_ach_id
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+module AchClient
+  class Fake
+  end
+end

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

@@ -3,11 +3,23 @@ module AchClient
     # ICheckGateway implementation for AchTransaction
     class AchTransaction < Abstract::AchTransaction
 
+      # When ICheck API gives us an error response containing a correction, the response field looks like this:
+      #   DECLINED - Notice of Change (XXX - Change Data: YYYYYY)
+      #     Where X is a three character string representing the return code (example: C01)
+      #     Where Y is any number of digits representing the updated information for the correction - the
+      #       ACH attribute that should be updated (example: 123456789)
+      # The (\w{3}) capture group matches the return code, while the (\d+) capture group matches the correction data
+      #   for later use.
+      NOC_RESPONSE_MATCHER = /DECLINED - Notice of Change \((\w{3}) - Change Data: (\d+)\)/
+
       # 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
+      # wrong.
+      # ICheck sometimes returns an API error for certain rejection scenarios. In this case we raise a
+      #   InstantRejectionError which can be caught to handle any business logic appropriate for this edge case.
+      #   The exception contains a method ach_response that returns the information about the return.
       # @return [String] a string returned by ICheckGateway - external_ach_id
       def do_send
         # The response comes back as a | separated list of field values with
@@ -21,6 +33,19 @@ module AchClient
         if response[0] == 'APPROVED'
           # Return the confirmation number
           response[7]
+        elsif response[0].include?('DECLINED - Notice of Change')
+          return_code, addendum = NOC_RESPONSE_MATCHER.match(response[0]).captures
+          # The API error message incorrectly uses the normal correction return codes when the internal correction
+          #  return codes should be used instead (since the transaction is never forwarded through to the NACHA system)
+          # Correcting this involves replacing `C0` with `XZ` (ie C01 becomes XZ1)
+          corrected_return_code = "XZ#{return_code.last}"
+          raise ICheckGateway::InstantRejectionError.new(
+            nacha_return_code: corrected_return_code,
+            addendum: addendum,
+            transaction: self
+          ), response[0]
+        elsif response[0].include?('DECLINED - Invalid Routing Number')
+          raise ICheckGateway::InstantRejectionError.new(nacha_return_code: 'X13', transaction: self), response[0]
         else
           # Don't have a reliable way of getting the error message, so we will
           # just raise the whole response.

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

@@ -0,0 +1,33 @@
+module AchClient
+  class ICheckGateway
+    # ICheckGateway sometimes returns an API error when a valid ACH transaction is sent in a handful of
+    #   rejection scenarios. This is unusual because most providers will accept the transaction, return an
+    #   external_ach_id, and then supply the rejection info when you poll for responses at a later date.
+    # So far we have observed this happening in the following scenarios:
+    #   - When an invalid routing number is supplied (X13 - Invalid ACH Routing Number - Entry contains a Receiving DFI
+    #       Identification or Gateway Identification that is not a valid ACH routing number.)
+    #   - When there is a Notice of Change for the account number (C01 - ACH Change Code. Incorrect Account Number)
+    #   - When there is a Notice of Change for the routing number (C02 - ACH Change Code. Incorrect Transit Route)
+    # This exception can be caught to handle the API error in the appropriate manner.
+    # The NACHA return code inferred from the error message is retrievable from the exception instance as well as any
+    #   addendum information provided by the API error (ie the correct new account/routing number)
+    class InstantRejectionError < RuntimeError
+      attr_reader :ach_response
+
+      def initialize(message = nil, nacha_return_code:, addendum: nil, transaction:)
+        super(message)
+        return_code = ReturnCodes.find_by(code: nacha_return_code)
+        response_args = {
+          amount: transaction.amount,
+          date: transaction.effective_entry_date,
+          return_code: return_code,
+        }
+        @ach_response = if return_code.correction?
+          CorrectedAchResponse.new(**response_args, corrections: addendum)
+        else
+          ReturnedAchResponse.new(**response_args)
+        end
+      end
+    end
+  end
+end

data/lib/ach_client/version.rb

@@ -1,4 +1,4 @@
 module AchClient
   # Increment this when changes are published
-  VERSION = '1.0.1'
+  VERSION = '2.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ach_client
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Zach Cotter
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-04-02 00:00:00.000000000 Z
+date: 2020-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ach
@@ -80,20 +80,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.12'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.12'
 - !ruby/object:Gem::Dependency
   name: codeclimate-test-reporter
   requirement: !ruby/object:Gem::Requirement
@@ -140,16 +126,16 @@ dependencies:
   name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -168,16 +154,16 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10'
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10'
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -276,6 +262,7 @@ files:
 - ".tool-versions"
 - ".tool-versions-e"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile
@@ -326,12 +313,17 @@ files:
 - lib/ach_client/providers/soap/ach_works/date_formatter.rb
 - lib/ach_client/providers/soap/ach_works/response_record_processor.rb
 - lib/ach_client/providers/soap/ach_works/transaction_type_transformer.rb
+- lib/ach_client/providers/soap/fake/ach_batch.rb
+- lib/ach_client/providers/soap/fake/ach_status_checker.rb
+- lib/ach_client/providers/soap/fake/ach_transaction.rb
+- lib/ach_client/providers/soap/fake/fake.rb
 - lib/ach_client/providers/soap/i_check_gateway/account_type_transformer.rb
 - lib/ach_client/providers/soap/i_check_gateway/ach_batch.rb
 - lib/ach_client/providers/soap/i_check_gateway/ach_status_checker.rb
 - lib/ach_client/providers/soap/i_check_gateway/ach_transaction.rb
 - lib/ach_client/providers/soap/i_check_gateway/company_info.rb
 - lib/ach_client/providers/soap/i_check_gateway/i_check_gateway.rb
+- lib/ach_client/providers/soap/i_check_gateway/instant_rejection_error.rb
 - lib/ach_client/providers/soap/i_check_gateway/response_record_processor.rb
 - lib/ach_client/providers/soap/i_check_gateway/transaction_type_transformer.rb
 - lib/ach_client/providers/soap/soap_provider.rb