# 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:
- Complete locales:
  - en
  - pl

- Incomplete locales:
  - da
  - ee
  - lt
  - lv
  - sv

## Installation

Add this line to your application's Gemfile:

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

```ruby
# 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).

```ruby
# 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)

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

```ruby
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

```ruby
# 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`. 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::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ść."
```

#### Methods

##### reason

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

```ruby
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.

```ruby
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

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')
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.

```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"
```

##### 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')
code.reason #=> "Suspected fraud"

code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :en)
code.reason #=> "Suspected fraud"

code = ::IssuerResponseCodes::TdsCode.new(id: '11', locale: :pl)
code.reason #=> "Podejrzenie oszustwa"
```

#### Methods

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

```ruby
code = ::IssuerResponseCodes::TdsCode.new(id: '08')
code.description #=> "No Card record"

code = ::IssuerResponseCodes::TdsCode.new(id: '22')
code.description #=> "ACS technical issue"

code = ::IssuerResponseCodes::TdsCode.new(id: '26')
code.description #=> "Authentication attempted but not performed by the cardholder"
```

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

```ruby
# 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](https://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](https://opensource.org/licenses/MIT).