issuer_response_codes 0.1.0

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "issuer_response_codes"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/issuer_response_codes.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/issuer_response_codes/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "issuer_response_codes"
+  spec.version       = IssuerResponseCodes::VERSION
+  spec.authors       = ["Espago", "Mateusz Drewniak"]
+  spec.email         = ["m.drewniak@espago.com"]
+
+  spec.summary       = "Issuer Response Code descriptions for cardholders and merchants"
+  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.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/espago/issuer_response_codes"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'bundler-audit'
+  spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'solargraph'
+end

data/lib/issuer_response_codes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "issuer_response_codes/version"
+require "issuer_response_codes/locale_library"
+require "issuer_response_codes/context"
+require "issuer_response_codes/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
+
+  LOCALE_LIBRARY = LocaleLibrary.new
+end

data/lib/issuer_response_codes/code.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module IssuerResponseCodes
+  class Code
+    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
+    end
+
+    def humanize
+      "#{reason} #{behaviour}"
+    end
+
+    alias description humanize
+
+    def reason
+      LOCALE_LIBRARY.dig(path: id, scope: "issuer_response_codes.targeted.#{target}", locale: locale, default: :unknown)
+    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)
+    end
+  end
+end

data/lib/issuer_response_codes/context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module IssuerResponseCodes
+  class Context
+    attr_reader :default_target, :default_locale, :fraud_notice_by_default
+
+    NOT_PROVIDED = ::Object.new
+
+    def initialize(default_target: :merchant, default_locale: :en, fraud_notice_by_default: NOT_PROVIDED)
+      @default_target = default_target
+      @default_locale = default_locale
+
+      raise IllegalLocale, "No such locale: #{default_locale.inspect}" unless AVAILABLE_LOCALES.include?(default_locale)
+      raise IllegalTarget, "No such target: #{default_target.inspect}" unless AVAILABLE_TARGETS.include?(default_target)
+
+      if fraud_notice_by_default != NOT_PROVIDED
+        @fraud_notice_by_default = fraud_notice_by_default
+        return
+      end
+
+      @fraud_notice_by_default = default_target == :merchant
+    end
+
+    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
+  end
+end

data/lib/issuer_response_codes/locale_library.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'byebug'
+
+module IssuerResponseCodes
+  class LocaleLibrary
+    attr_reader :locale_hash
+
+    def initialize
+      @locale_hash = {}
+
+      AVAILABLE_LOCALES.each do |locale|
+        load_locale(locale)
+      end
+    end
+
+    def dig(path:, locale: :en, scope: '', default: nil, substitute: '')
+      result = __dig__(path: path, locale: locale, scope: scope, default: default)
+      return result unless result
+
+      result.gsub(/%{substitute}/, substitute)
+    end
+
+    def self.symbolize_keys(hash)
+      h = hash.map do |k, v|
+        v_sym = if v.instance_of? Hash
+                  symbolize_keys(v)
+                else
+                  v
+                end
+
+        [k.to_sym, v_sym]
+      end
+
+      h.to_h
+    end
+
+    private
+
+    def __dig__(path:, locale: :en, scope: '', default: nil)
+      result = dig_provided_path(path, scope, locale)
+      return result if result || !default
+
+      return default.to_s if default.is_a?(String) || scope.empty?
+
+      dig_provided_path(default.to_s, scope, locale)
+    end
+
+    def dig_provided_path(path, scope, locale)
+      full_path_array = [locale]
+      full_path_array.append(*scope.split('.').map(&:to_sym))
+      full_path_array.append(*path.split('.').map(&:to_sym))
+
+      locale_hash.dig(*full_path_array)
+    end
+
+    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])
+      @locale_hash[name] = single_locale_hash
+    end
+  end
+end

data/lib/issuer_response_codes/version.rb

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

data/lib/locale/da.yml

@@ -0,0 +1,89 @@
+da:
+  issuer_response_code: &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."
+  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!'
+    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."
+      '13': "Tjek venligst indstillinger for din konto og konfigurationer af grænser. Kontakt venligst din kortudsteder og prøv igen senere."
+      '14': "Kontroller indtastede data og prøv igen."
+      'N7': "Kontroller indtastede data og prøv igen."
+      '51': "Tjek venligst penge på din konto og prøv igen senere."
+      '54': "Kontrollér dit kort eller prøv et andet."
+      '57': "Tjek venligst dine kortindstillinger for disse transaktionstyper eller brug et andet kort."
+      '61': "Tjek venligst indstillinger for din konto og konfigurationer af grænser. Kontakt venligst din kortudsteder og prøv igen senere."
+      '82': "Kontroller indtastede data og prøv igen."
+      # incomplete translations
+      unknown: "Please contact our support team."
+      '01': "Please contact your card issuer."
+      '02': "Please contact your card issuer."
+      '03': "Please contact your card issuer and try again later."
+      '04': "Please contact your card issuer and try again later. %{substitute}"
+      '07': "Please contact your card issuer and try again later. %{substitute}"
+      '12': "Please contact your card issuer to get more details and try again later."
+      '30': "Please contact your card issuer to get more details and try again later."
+      '41': "Please contact your card issuer to get more details and try again later. %{substitute}"
+      '43': "Please contact your card issuer to get more details and try again later. %{substitute}"
+      '58': "Please check your card settings for those transaction types or use another card."
+      '59': "Please contact your card issuer to get more details and try again later."
+      '62': "Please contact your bank."
+      '65': "Change your limits settings or try again later."
+      '75': "Please check your CVV/CVC/PIN code on your card."
+      '78': "Please activate your card and try again later."
+      '91': "Please try again later."
+      '92': "Please try again later."
+      '94': "Please try again later."
+      '96': "Please try again later."
+      '98': "Please try again later."
+      'E3': "Please try again later."
+      'E4': "Please try again later or contact your card issuer to get more details"
+      '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."
+    targeted:
+      merchant:
+        <<: *issuer_response_code
+        '04': "Pickup card."
+        '07': "Pickup card."
+        '41': "Lost card."
+        '43': "Stolen card."
+      cardholder:
+        <<: *issuer_response_code
+        '04': "Your bank has declined this transaction."
+        '07': "Your bank has declined this transaction."
+        '41': "Your bank has declined this transaction."
+        '43': "Your bank has declined this transaction."

data/lib/locale/ee.yml

@@ -0,0 +1,89 @@
+ee:
+  issuer_response_code: &issuer_response_code
+    '00': "Tekkis viga. Tehing lükati Elavoni poolt tagasi sobimatu kaardiliigi, valede kaardiandmete, väljaandja / panga loa puudumise või kaupmehe suletud konto tõttu."
+    '05': "Pank lükkas tehingu tagasi, kuna turvalisuskontrollis avastati puudusi (kasutatud kaardiga ei saa teostada korduvtehinguid / makseid ilma CVV-koodita), rahalised vahendid on külmutatud, limiidid ületatud või kaart ei toeta MOTO-/internetitehinguid."
+    '13': "MOTO/eCommerce mitteaktiivne või summa limiit ületatud."
+    '14': "Kehtetu kaardi number."
+    'N7': "Vale CVV-kood."
+    '51': "Puuduvad piisavad vahendid."
+    '54': "Kehtivuse kaotanud kaart."
+    '57': "Pank lükkas tehingu tagasi, kuna antud krediitkaarti ei saa seda liiki tehingu teostamiseks kasutada (eCommerce, MOTO või korduvtehing)."
+    '61': "MOTO/eCommerce mitteaktiivne või summa limiit ületatud."
+    '82': "Vale CVV-kood."
+    # 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."
+  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!'
+    behaviour:
+      '00': "Palun proovige hiljem uuesti, võtke ühendust müüja või Espago klienditoega."
+      '05': "Palun kontrollige oma antud liiki tehinguid käsitlevaid kaardi seadeid või kasutage teist kaarti."
+      '13': "Palun kontrollige oma konto seadeid ja sätestatud limiite. Palun võtke ühendust oma kaardi väljaandjaga ja proovige hiljem uuesti."
+      '14': "Kontrollige sisestatud andmeid ja proovige uuesti."
+      'N7': "Kontrollige sisestatud andmeid ja proovige uuesti."
+      '51': "Palun kontrollige oma kontol olevaid vahendeid ja proovige hiljem uuesti."
+      '54': "Palun kontrollige oma kaarti või proovige teist kaarti."
+      '57': "Palun kontrollige oma antud liiki tehinguid käsitlevaid kaardi seadeid või kasutage teist kaarti."
+      '61': "Palun kontrollige oma konto seadeid ja sätestatud limiite. Palun võtke ühendust oma kaardi väljaandjaga ja proovige hiljem uuesti."
+      '82': "Kontrollige sisestatud andmeid ja proovige uuesti."
+      # incomplete translations
+      unknown: "Please contact our support team."
+      '01': "Please contact your card issuer."
+      '02': "Please contact your card issuer."
+      '03': "Please contact your card issuer and try again later."
+      '04': "Please contact your card issuer and try again later. %{substitute}"
+      '07': "Please contact your card issuer and try again later. %{substitute}"
+      '12': "Please contact your card issuer to get more details and try again later."
+      '30': "Please contact your card issuer to get more details and try again later."
+      '41': "Please contact your card issuer to get more details and try again later. %{substitute}"
+      '43': "Please contact your card issuer to get more details and try again later. %{substitute}"
+      '58': "Please check your card settings for those transaction types or use another card."
+      '59': "Please contact your card issuer to get more details and try again later."
+      '62': "Please contact your bank."
+      '65': "Change your limits settings or try again later."
+      '75': "Please check your CVV/CVC/PIN code on your card."
+      '78': "Please activate your card and try again later."
+      '91': "Please try again later."
+      '92': "Please try again later."
+      '94': "Please try again later."
+      '96': "Please try again later."
+      '98': "Please try again later."
+      'E3': "Please try again later."
+      'E4': "Please try again later or contact your card issuer to get more details"
+      '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."
+    targeted:
+      merchant:
+        <<: *issuer_response_code
+        '04': "Pickup card."
+        '07': "Pickup card."
+        '41': "Lost card."
+        '43': "Stolen card."
+      cardholder:
+        <<: *issuer_response_code
+        '04': "Your bank has declined this transaction."
+        '07': "Your bank has declined this transaction."
+        '41': "Your bank has declined this transaction."
+        '43': "Your bank has declined this transaction."

data/lib/locale/en.yml

@@ -0,0 +1,87 @@
+en:
+  issuer_response_code: &issuer_response_code
+    unknown: "Unknown reason."
+    '00': "Transaction rejected due to no response from issuer/bank, inactive Merchant account, used not supported card or incorrect card data."
+    '01': "Authorization Error."
+    '02': "Authorization Error."
+    '03': "Authorization Error."
+    '05': "The bank has declined the transaction due to security check (used card doesn't support recurring payments/ payment without CVV code), the funds have been frozen or limit exceeded, or card doesn't support MOTO/internet transactions."
+    '12': "No privileges to execute this transaction for your card."
+    '13': "Please check settings of your account and configurations of limits."
+    '14': "Invalid card number."
+    '30': "Your bank has declined this transaction"
+    'N7': "Negative CVV results."
+    '51': "Insufficient funds."
+    '54': "Expired card."
+    '57': "Bank/Issuer has declined the transaction as this credit card cannot be used for this type of transaction (eccommerce, MOTO or recurring)."
+    '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."
+    '61': "Your bank has declined this transaction"
+    '65': "Activity count limit exceeded."
+    '75': "Invalid activity count limit exceeded."
+    '78': "Inactive card."
+    '82': "Negative CVV results."
+    '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."
+  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!'
+    behaviour:
+      unknown: "Please contact our support team."
+      '00': "Check the card's data or please try again later."
+      '01': "Please contact your card issuer."
+      '02': "Please contact your card issuer."
+      '03': "Please contact your card issuer and try again later."
+      '04': "Please contact your card issuer and try again later. %{substitute}"
+      '05': "Please check your card settings for those transaction types or use another card."
+      '07': "Please contact your card issuer and try again later. %{substitute}"
+      '12': "Please contact your card issuer to get more details and try again later."
+      '13': "Please contact your card issuer and try again later."
+      '14': "Check entered data and try again."
+      '30': "Please contact your card issuer to get more details and try again later."
+      '41': "Please contact your card issuer to get more details and try again later. %{substitute}"
+      '43': "Please contact your card issuer to get more details and try again later. %{substitute}"
+      'N7': "Check entered data and try again."
+      '51': "Please check funds on your account and try again later."
+      '54': "Please check your card or try another."
+      '57': "Please check your card settings or use another card."
+      '58': "Please check your card settings for those transaction types or use another card."
+      '59': "Please contact your card issuer to get more details and try again later."
+      '61': "Please check settings of your account and configurations of limits. Please contact your card issuer and try again later."
+      '62': "Please contact your bank."
+      '65': "Change your limits settings or try again later."
+      '75': "Please check your CVV/CVC/PIN code on your card."
+      '78': "Please activate your card and try again later."
+      '82': "Check entered data and try again."
+      '91': "Please try again later."
+      '92': "Please try again later."
+      '94': "Please try again later."
+      '96': "Please try again later."
+      '98': "Please try again later."
+      'E3': "Please try again later."
+      'E4': "Please try again later or contact your card issuer to get more details"
+      '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."
+    targeted:
+      merchant:
+        <<: *issuer_response_code
+        '04': "Pickup card."
+        '07': "Pickup card."
+        '41': "Lost card."
+        '43': "Stolen card."
+      cardholder:
+        <<: *issuer_response_code
+        '04': "Your bank has declined this transaction."
+        '07': "Your bank has declined this transaction."
+        '41': "Your bank has declined this transaction."
+        '43': "Your bank has declined this transaction."