issuer_response_codes 0.2.0 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fdf114e3233ad8d9aa121a2c12bc2819e9c110c6671a4e364ae00f5a69987e9
-  data.tar.gz: 9e22b8b8973d9577b47623b921ef0e2b2ea470b8175861b836656ec57fe35aac
+  metadata.gz: dac9d604f2e19423d50223600a7919c737ad77eaa6d20a81478f36dadc907cbb
+  data.tar.gz: 92cf2b531073ec57418906a5996b3b6fcdfeb2771c3646e7879178e73f836bcd
 SHA512:
-  metadata.gz: 238de0b95f1203dc1d93855c8badca49bd5792e3ad43c3ffb7d7df078cae4c68bf7bd28ae77204ffdf733d671a4c873e1e43a574169ce9185e720bdc26be44fc
-  data.tar.gz: 5d537189d5e4c074ec9fd4b4cbce724f97b9c2d64697a103be37fa1d348ff469d92fd697fe3b3dcaab3b34eca21ff7486ae880a0310297e1f08e1dd5fe7944df
+  metadata.gz: ac1b7680c8c076ac0f06108cc96e685c058fb506240e189f9ea14f7e4ec132d51fd279571bf39a441709adfad8f8bfcc3f798d397d16b82e5ce10f6c7a113937
+  data.tar.gz: 3c106d735298510ae3a73742b8ff40eb264a5cff307eb7cc6cc71a8031d6b3f21d7fdea9cda437e2e178746a48f7b0e597422d7c2248494d743ff2aa94a82891

data/.ruby-gemset

@@ -0,0 +1 @@
+issuer_response_codes

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    issuer_response_codes (0.2.0)
+    issuer_response_codes (0.2.4)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,13 +1,15 @@
 # IssuerResponseCodes
 
-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:
+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 9 languages:
 - Complete locales:
   - en
   - pl
 
 - Incomplete locales:
   - da
+  - de
   - ee
+  - it
   - lt
   - lv
   - sv
@@ -176,7 +178,7 @@ 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 (aliased as `humanize`) is a combination of both the `reason` and `behaviour` of a Issuer Response Code
 
@@ -219,14 +221,41 @@ You can choose the main target of these descriptions (certain details are hidden
 
 # fraud_notice is set to true by default when target = :merchant
 code = ::IssuerResponseCodes::TdsCode.new(id: '11')
-code.reason #=> "Suspected fraud"
+code.reason #=> "Suspected fraud."
 
 code = ::IssuerResponseCodes::TdsCode.new(id: '11', target: :merchant)
-code.reason #=> "Suspected fraud"
+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"
+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
@@ -234,31 +263,61 @@ code.reason #=> "Card authentication failed"
 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')
-code.reason #=> "Suspected fraud"
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', target: :cardholder)
+code.reason #=> "Card authentication failed."
 
-code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :en)
-code.reason #=> "Suspected fraud"
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :en, target: :cardholder)
+code.reason #=> "Card authentication failed."
 
-code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :pl)
-code.reason #=> "Podejrzenie oszustwa"
+code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :pl, target: :cardholder)
+code.reason #=> "Negatywny wynik silnego uwierzytelnienia w systemie banku."
 ```
 
 #### Methods
 
-##### description/reason
+##### reason
 
-The `description` (also aliased as `reason`) method returns a relatively short description of the main reason why the Issuer Response Code appeared in the first place.
+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: '08')
-code.description #=> "No Card record"
+code = ::IssuerResponseCodes::TdsCode.new(id: '01')
+code.reason #=> "Card authentication failed."
 
-code = ::IssuerResponseCodes::TdsCode.new(id: '22')
-code.description #=> "ACS technical issue"
+code = ::IssuerResponseCodes::TdsCode.new(id: '07')
+code.reason #=> "Invalid transaction."
 
-code = ::IssuerResponseCodes::TdsCode.new(id: '26')
-code.description #=> "Authentication attempted but not performed by the cardholder"
+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?

data/lib/issuer_response_codes/code.rb

@@ -32,15 +32,15 @@ module IssuerResponseCodes
       LOCALE_LIBRARY.dig(path: id, scope: "issuer_response_codes.targeted.#{target}", locale: locale, default: :unknown)
     end
 
-    def fraudulent_code?
-      @fraudulent_code ||= LOCALE_LIBRARY.dig(path: id, scope: "issuer_response_codes.fraudulent_codes", locale: locale)
-    end
-
     def behaviour
       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/locale_library.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'yaml'
-require 'byebug'
 
 module IssuerResponseCodes
   class LocaleLibrary
@@ -23,6 +22,44 @@ module IssuerResponseCodes
       result.gsub(/%{substitute}/, substitute)
     end
 
+    def issuer_response_codes(locale: :en)
+      fraudulent_codes = locale_hash.dig(locale, :issuer_response_codes, :fraudulent_codes)
+      behaviours = locale_hash.dig(locale, :issuer_response_codes, :behaviour)
+      cardholder_reasons = locale_hash.dig(locale, :issuer_response_codes, :targeted, :cardholder)
+      merchant_reasons = locale_hash.dig(locale, :issuer_response_codes, :targeted, :merchant)
+
+      merchant_reasons.map do |code, merchant_reason|
+        [
+          code,
+          {
+            merchant_reason: merchant_reason,
+            cardholder_reason: cardholder_reasons[code],
+            behaviour: behaviours[code],
+            fraudulent: fraudulent_codes[code] == true
+          }
+        ]
+      end.to_h
+    end
+
+    def tds_codes(locale: :en)
+      fraudulent_codes = locale_hash.dig(locale, :tds_status_codes, :fraudulent_codes)
+      behaviours = locale_hash.dig(locale, :tds_status_codes, :behaviour)
+      cardholder_reasons = locale_hash.dig(locale, :tds_status_codes, :targeted, :cardholder)
+      merchant_reasons = locale_hash.dig(locale, :tds_status_codes, :targeted, :merchant)
+
+      merchant_reasons.map do |code, merchant_reason|
+        [
+          code,
+          {
+            merchant_reason: merchant_reason,
+            cardholder_reason: cardholder_reasons[code],
+            behaviour: behaviours[code],
+            fraudulent: fraudulent_codes[code] == true
+          }
+        ]
+      end.to_h
+    end
+
     def self.symbolize_keys(hash)
       h = hash.map do |k, v|
         v_sym = if v.instance_of? Hash

data/lib/issuer_response_codes/tds_code.rb

@@ -1,33 +1,23 @@
 # frozen_string_literal: true
 
 module IssuerResponseCodes
-  class TdsCode
-    attr_reader :id, :target, :locale, :fraud_notice
-
-    NOT_PROVIDED = ::Object.new
-
-    def initialize(id:, target: :merchant, locale: :en, fraud_notice: NOT_PROVIDED)
-      @id = id
-      @target = target
-      @locale = locale
-
-      raise IllegalLocale, "No such locale: #{locale.inspect}" unless AVAILABLE_LOCALES.include?(locale)
-      raise IllegalTarget, "No such target: #{target.inspect}" unless AVAILABLE_TARGETS.include?(target)
-
-      if fraud_notice != NOT_PROVIDED
-        @fraud_notice = fraud_notice
-        return
-      end
-
-      @fraud_notice = target == :merchant
+  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
 
-    alias humanize reason
-    alias description reason
+    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)

data/lib/issuer_response_codes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IssuerResponseCodes
-  VERSION = '0.2.0'
+  VERSION = '0.2.4'
 end

data/lib/issuer_response_codes.rb

@@ -11,7 +11,7 @@ module IssuerResponseCodes
   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/locale/da.yml

@@ -4,43 +4,107 @@ da:
       '09': true
       '10': true
       '11': true
+    behaviour:
+      unknown: 'Please contact our support team.'
+      '01': Please try again.
+      '02': Please try again using a different device.
+      '03': Please try again using a different device.
+      '04': Please use a different card or contact your card issuer.
+      '05': Please use a different card.
+      '06': Please use a different card or check the card number.
+      '07': Please use a different card.
+      '08': Please use a different card.
+      '09': Please use a different card or contact issuer.
+      '10': Please use a different card or contact issuer.
+      '11': Please use a different card or contact issuer.
+      '12': Please use a different card or contact issuer.
+      '13': Please use a different card or contact issuer.
+      '14': Please try again or use a different card.
+      '15': Please use a different card or contact issuer.
+      '16': Please use a different card or contact issuer.
+      '17': Please use a different card or contact issuer.
+      '18': Please use a different card or contact issuer.
+      '19': Please use a different card or contact issuer.
+      '20': Please use a different card.
+      '21': Please use a different card.
+      '22': Please try again or use a different card.
+      '23': Please use a different card or contact issuer.
+      '24': Please try again or use a different card.
+      '25': Please try again or use a different card.
+      '26': Please try again or use a different card.
+      '80': Please use a different card.
+      '81': Please try again or use a different card.
+      '82': Please use a different card.
+      '83': Please use a different card.
+      '84': Please try again or use a different card.
+      '85': Please use a different card.
+      '86': Please use a different card.
+      '87': Please use a different card.
+      '88': Please use a different card.
     universal: &universal_tds_status_codes
       unknown: "Unknown reason."
-      '01': Card authentication failed
-      '02': Unknown Device
-      '03': Unsupported Device
-      '04': Exceeds authentication frequency limit
-      '05': Expired card
-      '06': Invalid card number
-      '07': Invalid transaction
-      '08': No Card record
-      '12': Transaction not permitted to cardholder
-      '13': Cardholder not enrolled in service
-      '14': Transaction timed out at the ACS
-      '15': Low confidence
-      '16': Medium confidence
-      '17': High confidence
-      '18': Very High confidence
-      '19': Exceeds ACS maximum challenges
-      '20': Non-Payment transaction not supported
-      '21': 3RI transaction not supported
-      '22': ACS technical issue
-      '23': Decoupled Authentication required by ACS but not requested by 3DS Requestor
-      '24': 3DS Requestor Decoupled Max Expiry Time exceeded
-      '25': Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
-      '26': Authentication attempted but not performed by the cardholder
-
+      '01': Card authentication failed.
+      '02': Unknown Device.
+      '03': Unsupported Device.
+      '04': Exceeds authentication frequency limit.
+      '05': Expired card.
+      '06': Invalid card number.
+      '07': Invalid transaction.
+      '08': No Card record.
+      '15': Low confidence.
+      '16': Medium confidence.
+      '17': High confidence.
+      '18': Very High confidence.
+      '19': Exceeds ACS maximum challenges.
+      '20': Non-Payment transaction not supported.
     targeted:
-      cardholder:
-        <<: *universal_tds_status_codes
-        '09': Card authentication failed # Security failure
-        '10': Card authentication failed # Stolen card
-        '11': Card authentication failed # Suspected fraud
       merchant:
         <<: *universal_tds_status_codes
-        '09': Security failure
-        '10': Stolen card
-        '11': Suspected fraud
+        '09': Security failure.
+        '10': Stolen card.
+        '11': Suspected fraud.
+        '12': Transaction not permitted to cardholder.
+        '13': Cardholder not enrolled in service.
+        '14': Transaction timed out at the ACS.
+        '21': 3RI transaction not supported.
+        '22': ACS technical issue.
+        '23': Decoupled Authentication required by ACS but not requested by 3DS Requestor.
+        '24': 3DS Requestor Decoupled Max Expiry Time exceeded.
+        '25': Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt.
+        '26': Authentication attempted but not performed by the cardholder.
+        '80': Error Connecting to ACS.
+        '81': ACS Timed Out.
+        '82': Invalid Response from ACS.
+        '83': System Error Response from ACS.
+        '84': Internal Error While Generating CAVV.
+        '85': VMID not eligible for requested program.
+        '86': Protocol Version Not Supported by ACS.
+        '87': Transaction is excluded from Attempts Processing (includes non- reloadable pre-paid cards and Non- Payments (NPA)).
+        '88': Requested program not supported by the ACS.
+      cardholder:
+        <<: *universal_tds_status_codes
+        '09': Card authentication failed. # Security failure
+        '10': Card authentication failed. # Stolen card
+        '11': Card authentication failed. # Suspected fraud
+        '12': Transaction not permitted to cardholder.
+        '13': Cardholder not enrolled in service.
+        '14': Card authentication failed.
+        '21': Card authentication failed.
+        '22': Issuer technical issue.
+        '23': Card authentication failed
+        '24': Card authentication failed
+        '25': Card authentication failed.
+        '26': Card authentication failed.
+        '80': Card authentication failed.
+        '81': Card authentication failed.
+        '82': Card authentication failed.
+        '83': Card authentication failed.
+        '84': Card authentication failed.
+        '85': Card authentication failed.
+        '86': Card authentication failed.
+        '87': Card authentication failed.
+        '88': Card authentication failed.
+
   issuer_response_codes:
     suggestion: 'Suggestion'
     fraud_notice: 'IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recognized as a fraud attempt!'
@@ -49,40 +113,6 @@ da:
       '07': true
       '41': true
       '43': true
-    universal: &issuer_response_code
-      '00': "En fejl opstod. Transaktionen blev afvist af Elavon på grund af ikke-understøttet korttype eller forkerte kortdata, intet svar fra udsteder / bank eller inaktiv Merchant-konto."
-      '05': "Banken har afvist transaktionen på grund af sikkerhedskontrol (brugt kort understøtter ikke tilbagebetalinger eller betaling uden CVV-kode), midlerne er blevet frosset eller grænsen overskredet, eller kortet understøtter ikke MOTO / internet-transaktioner."
-      '13': "MOTO / eCommerce betalinger på kort er inaktive eller beløbsgrænse overstiger."
-      '14': "Ugyldigt kortnummer."
-      'N7': "Negative CVV / CVC resultater."
-      '51': "Ikke nok penge."
-      '54': "Udgået kort."
-      '57': "Banken har afvist transaktionen, da dette kreditkort ikke kan bruges til denne type transaktion (e-handel, MOTO eller tilbagevendende)."
-      '61': "Banken har afvist transaktionen."
-      '82': "Negative CVV / CVC resultater."
-      # incomplete translations
-      unknown: "Unknown reason."
-      '01': "Authorization Error."
-      '02': "Authorization Error."
-      '03': "Authorization Error."
-      '12': "No privileges to execute this transaction for your card."
-      '30': "Your bank has declined this transaction"
-      '58': "Your bank has declined this transaction as this credit card cannot be used for this type of transaction (eccommerce, MOTO or recurring)."
-      '59': "Your bank has declined this transaction"
-      '62': "Your card can be not supported due to restrictions placed on the card or Seller country exclusion (imposition an embargo), or bank blocked a card eg. due to unacceptable debit balance."
-      '65': "Activity count limit exceeded."
-      '75': "Invalid activity count limit exceeded."
-      '78': "Inactive card."
-      '91': "Temporary issuer error."
-      '92': "Temporary issuer error."
-      '94': "Temporary issuer error."
-      '96': "Temporary issuer error."
-      '98': "Temporary issuer error."
-      'E3': "Transaction not executed due to a 3D-Secure error."
-      'E4': "Transaction not executed due to a negative 3D-Secure confirmation from your bank."
-      'E5': "Temporary 3D-Secure error."
-      'R0': "Refused by Issuer because Customer requested stop of specific recurring payments."
-      'R1': "Refused by Issuer because Customer requested stop of all recurring payments."
     behaviour:
       '00': "Prøv igen senere, kontakt med sælger eller med Espago Support Team."
       '05': "Tjek venligst dine kortindstillinger for disse transaktionstyper eller brug et andet kort."
@@ -121,6 +151,40 @@ da:
       'E5': "Please try again later or contact your card issuer to get more details"
       'R0': "Please contact your card issuer to get more details and try again later."
       'R1': "Please contact your card issuer to get more details and try again later."
+    universal: &issuer_response_code
+      '00': "En fejl opstod. Transaktionen blev afvist af Elavon på grund af ikke-understøttet korttype eller forkerte kortdata, intet svar fra udsteder / bank eller inaktiv Merchant-konto."
+      '05': "Banken har afvist transaktionen på grund af sikkerhedskontrol (brugt kort understøtter ikke tilbagebetalinger eller betaling uden CVV-kode), midlerne er blevet frosset eller grænsen overskredet, eller kortet understøtter ikke MOTO / internet-transaktioner."
+      '13': "MOTO / eCommerce betalinger på kort er inaktive eller beløbsgrænse overstiger."
+      '14': "Ugyldigt kortnummer."
+      'N7': "Negative CVV / CVC resultater."
+      '51': "Ikke nok penge."
+      '54': "Udgået kort."
+      '57': "Banken har afvist transaktionen, da dette kreditkort ikke kan bruges til denne type transaktion (e-handel, MOTO eller tilbagevendende)."
+      '61': "Banken har afvist transaktionen."
+      '82': "Negative CVV / CVC resultater."
+      # incomplete translations
+      unknown: "Unknown reason."
+      '01': "Authorization Error."
+      '02': "Authorization Error."
+      '03': "Authorization Error."
+      '12': "No privileges to execute this transaction for your card."
+      '30': "Your bank has declined this transaction"
+      '58': "Your bank has declined this transaction as this credit card cannot be used for this type of transaction (eccommerce, MOTO or recurring)."
+      '59': "Your bank has declined this transaction"
+      '62': "Your card can be not supported due to restrictions placed on the card or Seller country exclusion (imposition an embargo), or bank blocked a card eg. due to unacceptable debit balance."
+      '65': "Activity count limit exceeded."
+      '75': "Invalid activity count limit exceeded."
+      '78': "Inactive card."
+      '91': "Temporary issuer error."
+      '92': "Temporary issuer error."
+      '94': "Temporary issuer error."
+      '96': "Temporary issuer error."
+      '98': "Temporary issuer error."
+      'E3': "Transaction not executed due to a 3D-Secure error."
+      'E4': "Transaction not executed due to a negative 3D-Secure confirmation from your bank."
+      'E5': "Temporary 3D-Secure error."
+      'R0': "Refused by Issuer because Customer requested stop of specific recurring payments."
+      'R1': "Refused by Issuer because Customer requested stop of all recurring payments."
     targeted:
       merchant:
         <<: *issuer_response_code