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 many languages:

Complete locales:
- en
- pl
- es
- fi
- fr
- hr
- it
- nl
- pt
- uk
- ja
- cs
- sk
- hu
Incomplete locales:
- da
- de
- ee
- lt
- lv
- sv

Installation

Add this line to your application's Gemfile:

gem 'issuer_response_codes'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install issuer_response_codes

Rails

For Rails projects, we highly encourage you to create a brand new initializer like config/initializers/issuer_response_codes.rb. You can then define your own context with the desired default options like so:

# config/initializers/issuer_response_codes.rb
# frozen_string_literal: true

ISSUER_RESPONSE_CODES = ::IssuerResponseCodes::Context.new(
    default_target: :merchant,
    default_locale: :en,
    fraud_notice_by_default: false # decide whether fraud attempt warnings/notices should
                                   # be added to code descriptions by default
)

Afterwards, all Issuer Response Codes you create using this context as a proxy will use these settings by default (You can always override them).

# app/models/some_model.rb

def response_code_description
    ::ISSUER_RESPONSE_CODES.code(id: '43').description
    #=> "Stolen card. Please contact your card issuer to get more details and try again later."

    ::ISSUER_RESPONSE_CODES.code(id: '43', fraud_notice: true).description
    #=>  "Stolen card. Please contact your card issuer to get more details and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recognized as a fraud attempt!"

    ::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 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

Targets

You can choose the main target of these descriptions (certain details are hidden for cardholders)

# Default values are as follows:
# target: :merchant, locale: :en, fraud_notice: true

# fraud_notice is set to true by default when target = :merchant
code = ::IssuerResponseCodes::Code.new(id: '43')
code.reason #=> "Stolen card."
code.behaviour #=> "Please contact your card issuer to get more details and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recognized as a fraud attempt!"

code = ::IssuerResponseCodes::Code.new(id: '43', target: :merchant)
code.reason #=> "Stolen card."
code.behaviour #=> "Please contact your card issuer to get more details and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recognized as a fraud attempt!"

# fraud_notice is set to false by default when target = :cardholder
code = ::IssuerResponseCodes::Code.new(id: '43', target: :cardholder)
code.reason #=> "Your bank has declined this transaction."
code.behaviour #=> "Please contact your card issuer to get more details and try again later."

Fraud notice

Certain Issuer Response 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.

code = ::IssuerResponseCodes::Code.new(id: '43', target: :merchant)
code.behaviour #=> "Please contact your card issuer to get more details and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recognized as a fraud attempt!"

# fraud_notice is set to false by default when target = :cardholder
code = ::IssuerResponseCodes::Code.new(id: '43', target: :cardholder)
code.behaviour #=> "Please contact your card issuer to get more details and try again later."

This however can be overridden by explicitly passing the fraud_notice keyword parameter

# default options can be overridden
code = ::IssuerResponseCodes::Code.new(id: '43', target: :merchant, fraud_notice: false)
code.behaviour #=> "Please contact your card issuer to get more details and try again later."

# fraud_notice is set to false by default when target = :cardholder
code = ::IssuerResponseCodes::Code.new(id: '43', target: :cardholder, fraud_notice: true)
code.behaviour #=> "Please contact your card issuer to get more details and try again later. IMPORTANT NOTICE: It is forbidden to retry transactions that ended with this code. It may be recognized as a fraud attempt!"

Locale

The default locale is :en. Only the first two are complete, the rest are partially in English.

code = ::IssuerResponseCodes::Code.new(id: '54')
code.reason #=> "Expired card."

code = ::IssuerResponseCodes::Code.new(id: '54', locale: :en)
code.reason #=> "Expired card."

code = ::IssuerResponseCodes::Code.new(id: '54', locale: :pl)
code.reason #=> "Karta utraciła ważność."

A full list of available locales is stored in IssuerResponseCodes::AVAILABLE_LOCALES.

Methods

reason

The reason method returns a relatively short description of the main reason why the Issuer Response Code appeared in the first place.

code = ::IssuerResponseCodes::Code.new(id: '14')
code.reason #=> "Invalid card number."

code = ::IssuerResponseCodes::Code.new(id: '51')
code.reason #=> "Insufficient funds."

code = ::IssuerResponseCodes::Code.new(id: '59')
code.reason #=> "Your bank has declined this transaction"

behaviour

The behaviour method returns a suggestion of what to do when the Issuer Response Code appeared. Mainly for cardholders.

code = ::IssuerResponseCodes::Code.new(id: '14')
code.behaviour #=> "Check entered data and try again."

code = ::IssuerResponseCodes::Code.new(id: '51')
code.behaviour #=> "Please check funds on your account and try again later."

code = ::IssuerResponseCodes::Code.new(id: '59')
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

code = ::IssuerResponseCodes::Code.new(id: '14')
code.description #=> "Invalid card number. Check entered data and try again."

code = ::IssuerResponseCodes::Code.new(id: '51')
code.description #=> "Insufficient funds. Please check funds on your account and try again later."

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.

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)

# 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.

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

# 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. Only the first two are complete, the rest are partially in English.

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.

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.

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

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.

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.

# non-standard default configuration
ISSUER_RESPONSE_CODES = ::IssuerResponseCodes::Context.new(
    default_target: :cardholder,
    default_locale: :pl,
    fraud_notice_by_default: true  # decide whether fraud attempt warnings/notices should
                                   # be added to code descriptions by default
)

# now just use this object as a proxy
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_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."

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/espago/issuer_response_codes.

License

The gem is available as open source under the terms of the MIT License.

issuer_response_codes

Runtime

IssuerResponseCodes

Installation

Rails

Usage

IssuerResponseCodes::Code

Creation options

Targets

Fraud notice

Locale

Methods

reason

behaviour

description/humanize

fraudulent_code?

IssuerResponseCodes::TdsCode

Creation options

Targets

Fraud notice

Locale

Methods

reason

behaviour

description/humanize

fraudulent_code?

Custom default configuration

Development

Contributing

License