issuer_response_codes 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7dbb167d16f432e8a8113006dc1d2591b05c96ed6141fc0c1532c9b1e241ebf
-  data.tar.gz: 3b5101d1027157edad887ee134551adffbd8a79210f238230d98091fd2b817df
+  metadata.gz: 02f7ca39c355badd05b7083f83789aa3d9271b0195d5955d2247548d8dd67d27
+  data.tar.gz: fad7b1f3758eb3211fd04a62155883d64939dc04382f4288ba45d2bc3aad8b59
 SHA512:
-  metadata.gz: 1b4d8a1836429d54ee6ed64f408f3fa6c108047f8266e1f91253e362e7234805ff27f66ccd0ea953cdfe0124f6ec30b903ec74eec4a280e843aef4b0273578b8
-  data.tar.gz: 1fb3f071324d4cdd7d1d63272ac82c86258f4509ba4cf2bf45cdb3245f85bd44ef7ae3ab70036213487dba5f4cbb1da0385ccb1ff9469e7eef185beb73baf396
+  metadata.gz: c3896b85d20055b822c6d07bb30ea0cff9f091e559166135339c3e6e2b8ebb5a29574b22446c2635cfc13790175510435ebc9f9d24975daf17a548cca3905140
+  data.tar.gz: 4806b6ace9f4c153aa9e0f56d25c7d940fc8033eab73a569511244d74b207b683f2dc9da056ba980abaeda98255eafcf4f5acdb3cbdd7ec681b4b5f0c966ba15

data/.gitignore

@@ -6,3 +6,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+.byebug_history
+my_examples

data/.rubocop.yml

@@ -1,6 +1,9 @@
 Style/StringLiterals:
   Enabled: false
 
+Style/SingleArgumentDig:
+  Enabled: false
+
 Layout/LineLength:
   Enabled: false
 

data/Gemfile

@@ -4,6 +4,3 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in issuer_response_codes.gemspec
 gemspec
-
-gem "minitest", "~> 5.0"
-gem "rake", "~> 12.0"

data/Gemfile.lock

@@ -1,27 +1,28 @@
 PATH
   remote: .
   specs:
-    issuer_response_codes (0.1.0)
+    issuer_response_codes (0.2.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    backport (1.1.2)
+    backport (1.2.0)
     benchmark (0.1.1)
     bundler-audit (0.8.0)
       bundler (>= 1.2.0, < 3)
       thor (~> 1.0)
     byebug (11.1.3)
+    diff-lcs (1.4.4)
     e2mmap (0.1.0)
     jaro_winkler (1.5.4)
     kramdown (2.3.1)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
-    mini_portile2 (2.5.1)
+    mini_portile2 (2.5.3)
     minitest (5.14.4)
-    nokogiri (1.11.3)
+    nokogiri (1.11.7)
       mini_portile2 (~> 2.5.0)
       racc (~> 1.4)
     parallel (1.20.1)
@@ -34,22 +35,23 @@ GEM
     reverse_markdown (2.0.0)
       nokogiri
     rexml (3.2.5)
-    rubocop (1.14.0)
+    rubocop (1.18.2)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.5.0, < 2.0)
+      rubocop-ast (>= 1.7.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.5.0)
+    rubocop-ast (1.7.0)
       parser (>= 3.0.1.1)
     ruby-progressbar (1.11.0)
-    solargraph (0.40.4)
-      backport (~> 1.1)
+    solargraph (0.42.3)
+      backport (~> 1.2)
       benchmark
       bundler (>= 1.17.2)
+      diff-lcs (~> 1.4)
       e2mmap
       jaro_winkler (~> 1.5)
       kramdown (~> 2.3)

data/README.md

@@ -1,9 +1,9 @@
 # IssuerResponseCodes
 
-This gem provides a quite comprehensive library of Issuer Response Code descriptions (for both cardholders and merchants) with suggested actions in 7 languages:
+This gem provides a quite comprehensive library of Issuer Response Code and 3D-Secure Status Code descriptions (for both cardholders and merchants) with suggested actions in 7 languages:
 - Complete locales:
-    - en
-    - pl
+  - en
+  - pl
 
 - Incomplete locales:
   - da
@@ -59,11 +59,22 @@ def response_code_description
     ::ISSUER_RESPONSE_CODES.code(id: '43', locale: :pl).description
     #=> "Karta oznaczona jako skradziona. Skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu."
 end
+
+def tds_code_description
+    ::ISSUER_RESPONSE_CODES.tds_code(id: '09').description
+    #=> "Security failure"
+
+    ::ISSUER_RESPONSE_CODES.tds_code(id: '09', target: :cardholder).description
+    #=> "Card authentication failed"
+
+    ::ISSUER_RESPONSE_CODES.tds_code(id: '09', locale: :pl).description
+    #=> "Niepowodzenie autoryzacji karty"
+end
 ```
 
 ## Usage
 
-This gem provides an easy way of handling Issuer Response Codes. Whether you need detailed descriptions, short reasons or suggestions of what to do when a certain Code appeared, we've got you covered. Certain more explicit codes like `Stolen card' are masked behind more generic terms when you choose to target cardholders.
+This gem provides an easy way of handling Issuer Response Codes and 3D-Secure Status Codes. Whether you need detailed descriptions, short reasons or suggestions of what to do when a certain Code appeared, we've got you covered. Certain more explicit codes like `Stolen card' are masked behind more generic terms when you choose to target cardholders.
 
 ### IssuerResponseCodes::Code
 #### Creation options
@@ -135,7 +146,7 @@ code.reason #=> "Karta utraciła ważność."
 
 #### Methods
 
-##### Reason
+##### reason
 
 The `reason` method returns a relatively short description of the main reason why the Issuer Response Code appeared in the first place.
 
@@ -150,7 +161,7 @@ code = ::IssuerResponseCodes::Code.new(id: '59')
 code.reason #=> "Your bank has declined this transaction"
 ```
 
-##### Behaviour
+##### behaviour
 
 The `behaviour` method returns a suggestion of what to do when the Issuer Response Code appeared. Mainly for cardholders.
 
@@ -165,9 +176,9 @@ code = ::IssuerResponseCodes::Code.new(id: '59')
 code.behaviour #=> "Please contact your card issuer to get more details and try again later."
 ```
 
-##### Description
+##### description/humanize
 
-The `description` method is a combination of both the `reason` and `behaviour` of a Issuer Response Code
+The `description` method (aliased as `humanize`) is a combination of both the `reason` and `behaviour` of a Issuer Response Code
 
 ```ruby
 code = ::IssuerResponseCodes::Code.new(id: '14')
@@ -180,6 +191,148 @@ code = ::IssuerResponseCodes::Code.new(id: '59')
 code.description #=> "Your bank has declined this transaction. Please contact your card issuer to get more details and try again later."
 ```
 
+##### fraudulent_code?
+
+The `fraudulent_code?` method returns `true` when the Code indicates fraud.
+
+```ruby
+code = ::IssuerResponseCodes::Code.new(id: '14')
+code.fraudulent_code? #=> false
+
+code = ::IssuerResponseCodes::Code.new(id: '04')
+code.fraudulent_code? #=> true
+
+code = ::IssuerResponseCodes::Code.new(id: '43')
+code.fraudulent_code? #=> true
+```
+
+### IssuerResponseCodes::TdsCode
+#### Creation options
+
+##### Targets
+
+You can choose the main target of these descriptions (certain details are hidden for cardholders)
+
+```ruby
+# Default values are as follows:
+# target: :merchant, locale: :en
+
+# fraud_notice is set to true by default when target = :merchant
+code = ::IssuerResponseCodes::TdsCode.new(id: '11')
+code.reason #=> "Suspected fraud."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', target: :merchant)
+code.reason #=> "Suspected fraud."
+
+# fraud_notice is set to false by default when target = :cardholder
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', target: :cardholder)
+code.reason #=> "Card authentication failed."
+```
+
+##### Fraud notice
+
+Certain 3D-Secure status codes may signify that the transaction may be viewed as a fraud attempt. As such, this gem provides appropriate warnings. You can manually decide whether these warnings/notices should be added to descriptions or behaviour suggestions generated by this gem.
+
+By default descriptions targeted at merchants have these warnings, while those targeted at cardholders omit them.
+
+```ruby
+code = ::IssuerResponseCodes::TdsCode.new(id: '09', target: :merchant)
+code.behaviour #=> "Please use a different card or contact issuer. Transactions with this code may be considered fraudulent."
+
+# fraud_notice is set to false by default when target = :cardholder
+code = ::IssuerResponseCodes::TdsCode.new(id: '09', target: :cardholder)
+code.behaviour #=> "Please use a different card or contact issuer."
+```
+
+This however can be overridden by explicitly passing the `fraud_notice` keyword parameter
+
+```ruby
+# default options can be overridden
+code = ::IssuerResponseCodes::TdsCode.new(id: '09', target: :merchant, fraud_notice: false)
+code.behaviour #=> "Please use a different card or contact issuer."
+
+# fraud_notice is set to false by default when target = :cardholder
+code = ::IssuerResponseCodes::TdsCode.new(id: '09', target: :cardholder, fraud_notice: true)
+code.behaviour #=> "Please use a different card or contact issuer. Transactions with this code may be considered fraudulent."
+```
+
+##### Locale
+
+The default locale is `:en`. There are 7 in total: `%i[en pl da ee lt lv sv]`. Only the first two are complete, the rest are partially in English.
+
+```ruby
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', target: :cardholder)
+code.reason #=> "Card authentication failed."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :en, target: :cardholder)
+code.reason #=> "Card authentication failed."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :pl, target: :cardholder)
+code.reason #=> "Negatywny wynik silnego uwierzytelnienia w systemie banku."
+```
+
+#### Methods
+
+##### reason
+
+The `reason` method returns a relatively short description of the main reason why the 3D-Secure status code appeared in the first place.
+
+```ruby
+code = ::IssuerResponseCodes::TdsCode.new(id: '01')
+code.reason #=> "Card authentication failed."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '07')
+code.reason #=> "Invalid transaction."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '20')
+code.reason #=> "Non-Payment transaction not supported."
+```
+
+##### behaviour
+
+The `behaviour` method returns a suggestion of what to do when the 3D-Secure status code appeared. Mainly for cardholders.
+
+```ruby
+code = ::IssuerResponseCodes::TdsCode.new(id: '01')
+code.behaviour #=> "Check entered data and try again."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '07')
+code.behaviour #=> "Please check funds on your account and try again later."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '20')
+code.behaviour #=> "Please contact your card issuer to get more details and try again later."
+```
+
+##### description/humanize
+
+The `description` method (aliased as `humanize`) is a combination of both the `reason` and `behaviour` of a Issuer Response Code
+
+```ruby
+code = ::IssuerResponseCodes::TdsCode.new(id: '01')
+code.description #=> "Invalid card number. Check entered data and try again."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '07')
+code.description #=> "Insufficient funds. Please check funds on your account and try again later."
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '20')
+code.description #=> "Your bank has declined this transaction. Please contact your card issuer to get more details and try again later."
+```
+
+##### fraudulent_code?
+
+The `fraudulent_code?` method returns `true` when the TdsCode indicates fraud.
+
+```ruby
+code = ::IssuerResponseCodes::TdsCode.new(id: '11')
+code.fraudulent_code? #=> true
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '22')
+code.fraudulent_code? #=> false
+
+code = ::IssuerResponseCodes::TdsCode.new(id: '26')
+code.fraudulent_code? #=> false
+```
+
 ### Custom default configuration
 
 You can make use of the `Context` class to easily create your own default configurations. Contexts work as proxies which create codes for you.
@@ -194,12 +347,15 @@ ISSUER_RESPONSE_CODES = ::IssuerResponseCodes::Context.new(
 )
 
 # now just use this object as a proxy
-code = ISSUER_RESPONSE_CODE.code(id: '43')
+code = ISSUER_RESPONSE_CODES.code(id: '43')
 code.reason #=> "Bank odrzucił autoryzację."
 code.behaviour #=> "Skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa!"
 
+tds_code = ISSUER_RESPONSE_CODES.tds_code(id: '11')
+tds_code.reason #=> "Niepowodzenie autoryzacji karty"
+
 # these can always be overridden
-code = ISSUER_RESPONSE_CODE.code(id: '43', locale: :en, target: :merchant, fraud_notice: false)
+code = ISSUER_RESPONSE_CODES.code(id: '43', locale: :en, target: :merchant, fraud_notice: false)
 code.reason #=> "Stolen card."
 code.behaviour #=> "Please contact your card issuer to get more details and try again later."
 ```

data/issuer_response_codes.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = "A simple Ruby gem which provides Issuer Response Code descriptions and suggestions for cardholders and merchants"
   spec.homepage      = "https://github.com/espago/issuer_response_codes"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/espago/issuer_response_codes"
@@ -29,6 +29,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'bundler-audit'
   spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 12.0'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'solargraph'
 end

data/lib/issuer_response_codes.rb

@@ -4,13 +4,14 @@ require "issuer_response_codes/version"
 require "issuer_response_codes/locale_library"
 require "issuer_response_codes/context"
 require "issuer_response_codes/code"
+require "issuer_response_codes/tds_code"
 
 module IssuerResponseCodes
   class IllegalTarget < StandardError; end
   class IllegalLocale < StandardError; end
 
   AVAILABLE_TARGETS = %i[merchant cardholder].freeze
-  AVAILABLE_LOCALES = %i[en pl da ee lt lv sv].freeze
+  AVAILABLE_LOCALES = %i[en pl da de ee it lt lv sv].freeze
 
   LOCALE_LIBRARY = LocaleLibrary.new
 end

data/lib/issuer_response_codes/code.rb

@@ -33,8 +33,14 @@ module IssuerResponseCodes
     end
 
     def behaviour
-      fraud_notice_str = fraud_notice ? LOCALE_LIBRARY.dig(path: 'issuer_response_codes.fraud_notice') : ''
-      LOCALE_LIBRARY.dig(path: id, substitute: fraud_notice_str, scope: "issuer_response_codes.behaviour", locale: locale, default: :unknown)
+      behaviour_str = LOCALE_LIBRARY.dig(path: id, scope: "issuer_response_codes.behaviour", locale: locale, default: :unknown)
+      return behaviour_str unless fraud_notice && fraudulent_code?
+
+      "#{behaviour_str} #{LOCALE_LIBRARY.dig(path: 'issuer_response_codes.fraud_notice')}"
+    end
+
+    def fraudulent_code?
+      @fraudulent_code ||= LOCALE_LIBRARY.dig(path: id, scope: "issuer_response_codes.fraudulent_codes", locale: locale)
     end
   end
 end

data/lib/issuer_response_codes/context.rb

@@ -24,5 +24,9 @@ module IssuerResponseCodes
     def code(id:, target: default_target, locale: default_locale, fraud_notice: fraud_notice_by_default)
       Code.new(id: id, target: target, locale: locale, fraud_notice: fraud_notice)
     end
+
+    def tds_code(id:, target: default_target, locale: default_locale, fraud_notice: fraud_notice_by_default)
+      TdsCode.new(id: id, target: target, locale: locale, fraud_notice: fraud_notice)
+    end
   end
 end

data/lib/issuer_response_codes/locale_library.rb

@@ -18,6 +18,7 @@ module IssuerResponseCodes
     def dig(path:, locale: :en, scope: '', default: nil, substitute: '')
       result = __dig__(path: path, locale: locale, scope: scope, default: default)
       return result unless result
+      return result unless result.is_a? ::String
 
       result.gsub(/%{substitute}/, substitute)
     end
@@ -48,6 +49,8 @@ module IssuerResponseCodes
     end
 
     def dig_provided_path(path, scope, locale)
+      return if path.nil? || path.empty?
+
       full_path_array = [locale]
       full_path_array.append(*scope.split('.').map(&:to_sym))
       full_path_array.append(*path.split('.').map(&:to_sym))
@@ -58,7 +61,8 @@ module IssuerResponseCodes
     def load_locale(name)
       name_str = name.to_s
 
-      single_locale_hash = self.class.symbolize_keys(::YAML.load_file("lib/locale/#{name_str}.yml")[name_str])
+      raw_hash = ::YAML.load_file(::File.join(::File.dirname(::File.expand_path(__FILE__)), "../locale/#{name_str}.yml"))[name_str]
+      single_locale_hash = self.class.symbolize_keys(raw_hash)
       @locale_hash[name] = single_locale_hash
     end
   end

data/lib/issuer_response_codes/tds_code.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IssuerResponseCodes
+  class TdsCode < Code
+    def humanize
+      "#{reason} #{behaviour}"
+    end
+
+    alias description humanize
+
+    def reason
+      LOCALE_LIBRARY.dig(path: id, scope: "tds_status_codes.targeted.#{target}", locale: locale, default: :unknown)
+    end
+
+    def behaviour
+      behaviour_str = LOCALE_LIBRARY.dig(path: id, scope: "tds_status_codes.behaviour", locale: locale, default: :unknown)
+      return behaviour_str unless fraud_notice && fraudulent_code?
+
+      "#{behaviour_str} #{LOCALE_LIBRARY.dig(path: 'tds_status_codes.fraud_notice')}"
+    end
+
+    def fraudulent_code?
+      @fraudulent_code ||= LOCALE_LIBRARY.dig(path: id, scope: "tds_status_codes.fraudulent_codes", locale: locale)
+    end
+  end
+end