ach_client 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fadb80869dd7fcd712cce4344a08ddfa1da32e70b7cee237a39c9abcb96ac03a
-  data.tar.gz: 440ea73e8b1cbaafad65ecc94fa4710a9f8df1daa53a5ad656b7f5c2a4cced72
+  metadata.gz: bdcfddb63a2f873af45df29f8fcf6765ec99aff800eb04e8ec2b7500f0827e3c
+  data.tar.gz: 3bfa32675ec76f4e31b830b3616cc913b13f865c2c789394d49cc07758e93b89
 SHA512:
-  metadata.gz: 19e7c19755a287febc77466ccfda9abe3cc567897462ed3b32d9831e00e754283d1b168d069d4b08223e0e0e6ee56b5b7635fb712d23aa8d2780670b93ff792d
-  data.tar.gz: 0b5139c86630be28a2432fcf709772cb4bccdf725a724a6718b11b5057e69bcff71e2e0594075126781480e4fe9b494d3537aea816270dbec3afb1e97e77b9b6
+  metadata.gz: 25670e16c050eb8248d80f22ffeea4a649cef6f624828118e32c866b7b7e0b0e19f0735150b7b636e5cb88dafc7d57fe7a2ac3225b8c507100b42a3a9fba668e
+  data.tar.gz: ed197b466da4182a732f463b7c51f4a0bd24fdfbfa58755bd058d2f830790719e5f6d6c600abf480e045430e186c962f331ee0a7e17534546d93f7ed44cc8819

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+### 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

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/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.1.0'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ach_client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Zach Cotter
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-03-03 00:00:00.000000000 Z
+date: 2020-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ach
@@ -262,6 +262,7 @@ files:
 - ".tool-versions"
 - ".tool-versions-e"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile
@@ -321,6 +322,7 @@ files:
 - 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