minfraud 2.5.0 → 2.7.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2c683916a690e43c095a9fcb4b08118b5516919245fc5bf47d8b7b1de51f2be
-  data.tar.gz: 65135f9eb185edacfdc737d195cd283b77e6a548b49854f4b4964f8d7d061d39
+  metadata.gz: 48d0ecc771382609286c6c96297b5c452163d99f8657a176bdaa3c25344b7667
+  data.tar.gz: bbb364d67a5172f3e1134833acb3835e4de6582eb079341f727963b058fe2df0
 SHA512:
-  metadata.gz: b5642ec35609ebe7463b8a252593247d2676df99fafcf374ddca1c8463160ede4e4dc2c7b3adbf398ec54daf23640e9625443a60723e4afe01098caede9ee66a
-  data.tar.gz: 7276700318812cd0bd9b306237018cba29107a5723b8c4ddf6f76d0ed2394deea191655f149069d1cf0c11b5864725fc834805b42c39afc1daf2c616ee0a30ba
+  metadata.gz: c66d6b084f94957a376636a4ff90ab961e5632f67e1950019dc0acf424cd9c86c8db67cbcea99aae05bfc052cd37c7e08bdc3cbde6fc4099f23009387cc611a8
+  data.tar.gz: f5a425d99063ca41b1ff4aba8c72f881abd08a35fbbd6d13606f31f8080964d94dc678cf6d03292c1150fcab7e67ef62ae2b05ee7b6d56a39df82a44201f966e

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v2.7.0.beta1 (2024-09-06)
+
+* Added support for the new risk reasons outputs in minFraud Factors. The risk
+  reasons output codes and reasons are currently in beta and are subject to
+  change. We recommend that you use these beta outputs with caution and avoid
+  relying on them for critical applications.
+
+## v2.6.0 (2024-07-08)
+
+* Updated the validation for the Report Transactions API to make the
+  `ip_address` parameter optional. Now the `tag` and at least one of the
+  following parameters must be supplied: `ip_address`, `maxmind_id`,
+  `minfraud_id`, `transaction_id`.
+* Updated the validation for the Report Transactions API to check that
+  `ip_address`, `maxmind_id`, and `minfraud_id` contain valid values.
+* Added `billing_phone` and `shipping_phone` attributes to the minFraud
+  Insights and Factors response models. These contain objects with
+  information about the respective phone numbers. Please see [our developer
+  site](https://dev.maxmind.com/minfraud/api-documentation/responses/) for
+  more information.
+* Added the processor `:payconex` to `Minfraud::Components::Payment`.
+
 ## v2.5.0 (2024-04-16)
 
 * Equivalent domain names are now normalized when `hash_address` is used.

data/README.md

@@ -208,9 +208,9 @@ channel is used to improve the accuracy of their fraud detection
 algorithms.
 
 To use the Report Transaction API, create a
-`Minfraud::Components::Report::Transaction` object. An IP address and a
-valid tag are required arguments for this API. Additional parameters may be
-set, as shown below.
+`Minfraud::Components::Report::Transaction` object. A valid tag and at least
+one of the following are required parameters: ip_address, maxmind_id,
+minfraud_id, transaction_id. Additional parameters may be set, as shown below.
 
 If the report is successful, nothing is returned. If the report fails, an
 exception will be thrown.

data/lib/minfraud/components/payment.rb

@@ -108,6 +108,7 @@ module Minfraud
         orangepay
         other
         pacnet_services
+        payconex
         payeezy
         payfast
         paygate

data/lib/minfraud/components/report/transaction.rb

@@ -8,9 +8,13 @@ module Minfraud
       # @see https://dev.maxmind.com/minfraud/report-a-transaction?lang=en
       class Transaction < Base
         include ::Minfraud::Enum
+        include ::Minfraud::Validates
 
         # The IP address of the customer placing the order. This should be
-        # passed as a string like "152.216.7.110".
+        # passed as a string like "152.216.7.110". This field is not required
+        # if you provide at least one of the transaction's minfraud_id,
+        # maxmind_id, or transaction_id. You are encouraged to provide it, if
+        # possible.
         #
         # @return [String, nil]
         attr_accessor :ip_address
@@ -34,16 +38,19 @@ module Minfraud
 
         # A unique eight character string identifying a minFraud Standard or
         # Premium request. These IDs are returned in the maxmindID field of a
-        # response for a successful minFraud request. This field is not
-        # required, but you are encouraged to provide it, if possible.
+        # response for a successful minFraud request. This field is not required
+        # if you provide at least one of the transaction's ip_address,
+        # minfraud_id, or transaction_id. You are encouraged to provide it, if
+        # possible.
         #
         # @return [String, nil]
         attr_accessor :maxmind_id
 
         # A UUID that identifies a minFraud Score, minFraud Insights, or
         # minFraud Factors request. This ID is returned at /id in the response.
-        # This field is not required, but you are encouraged to provide it if
-        # the request was made to one of these services.
+        # This field is not required if you provide at least one of the
+        # transaction's ip_address, maxmind_id, or transaction_id. You are
+        # encouraged to provide it, if possible.
         #
         # @return [String, nil]
         attr_accessor :minfraud_id
@@ -56,9 +63,10 @@ module Minfraud
         # @return [String, nil]
         attr_accessor :notes
 
-        # The transaction ID you originally passed to minFraud. This field is
-        # not required, but you are encouraged to provide it or the
-        # transaction's maxmind_id or minfraud_id.
+        # The transaction ID you originally passed to minFraud. This field
+        # is not required if you provide at least one of the transaction's
+        # ip_address, maxmind_id, or minfraud_id. You are encouraged to
+        # provide it, if possible.
         #
         # @return [String, nil]
         attr_accessor :transaction_id
@@ -73,6 +81,30 @@ module Minfraud
           @notes           = params[:notes]
           @transaction_id  = params[:transaction_id]
           self.tag         = params[:tag]
+
+          validate
+        end
+
+        private
+
+        def validate
+          return if !Minfraud.enable_validation
+
+          validate_ip('ip_address', @ip_address)
+          validate_string('maxmind_id', 8, @maxmind_id)
+          validate_uuid('minfraud_id', @minfraud_id)
+
+          if ip_address.nil? &&
+             (minfraud_id.nil? || empty_uuid(minfraud_id)) &&
+             (maxmind_id.nil? || maxmind_id.empty?) &&
+             (transaction_id.nil? || transaction_id.empty?)
+            raise ArgumentError, 'At least one of the following is required: ip_address, minfraud_id, maxmind_id, transaction_id.'
+          end
+        end
+
+        def empty_uuid(value)
+          stripped_value = value.to_s.gsub('-', '')
+          stripped_value == '0' * 32
         end
       end
     end

data/lib/minfraud/model/address.rb

@@ -39,7 +39,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @distance_to_ip_location = get('distance_to_ip_location')
         @is_in_ip_country        = get('is_in_ip_country')

data/lib/minfraud/model/credit_card.rb

@@ -57,7 +57,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @brand                                = get('brand')
         @country                              = get('country')

data/lib/minfraud/model/device.rb

@@ -39,7 +39,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @confidence = get('confidence')
         @id         = get('id')

data/lib/minfraud/model/disposition.rb

@@ -31,7 +31,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @action     = get('action')
         @reason     = get('reason')

data/lib/minfraud/model/email.rb

@@ -41,7 +41,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @domain        = Minfraud::Model::EmailDomain.new(get('domain'))
         @first_seen    = get('first_seen')

data/lib/minfraud/model/email_domain.rb

@@ -15,7 +15,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @first_seen = get('first_seen')
       end

data/lib/minfraud/model/error.rb

@@ -18,7 +18,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @code  = get('code')
         @error = get('error')

data/lib/minfraud/model/factors.rb

@@ -2,11 +2,21 @@
 
 require 'minfraud/model/insights'
 require 'minfraud/model/subscores'
+require 'minfraud/model/risk_score_reason'
 
 module Minfraud
   module Model
     # Model representing the Factors response.
     class Factors < Insights
+      # This field contains RiskScoreReason objects that describe risk score reasons
+      # for a given transaction that change the risk score significantly.
+      # Risk score reasons are usually only returned for medium to high risk transactions.
+      # If there were no significant changes to the risk score due to these reasons,
+      # then this array will be empty.
+      #
+      # @return [Array<Minfraud::Model::RiskScoreReason>]
+      attr_reader :risk_score_reasons
+
       # An object containing scores for many of the individual risk factors
       # that are used to calculate the overall risk score.
       #
@@ -15,7 +25,14 @@ module Minfraud
 
       # @!visibility private
       def initialize(record, locales)
-        super(record, locales)
+        super
+
+        @risk_score_reasons = []
+        if record&.key?('risk_score_reasons')
+          record['risk_score_reasons'].each do |r|
+            @risk_score_reasons << Minfraud::Model::RiskScoreReason.new(r)
+          end
+        end
 
         @subscores = Minfraud::Model::Subscores.new(get('subscores'))
       end

data/lib/minfraud/model/geoip2_location.rb

@@ -16,7 +16,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @local_time = get('local_time')
       end

data/lib/minfraud/model/insights.rb

@@ -5,6 +5,7 @@ require 'minfraud/model/credit_card'
 require 'minfraud/model/device'
 require 'minfraud/model/email'
 require 'minfraud/model/ip_address'
+require 'minfraud/model/phone'
 require 'minfraud/model/score'
 require 'minfraud/model/shipping_address'
 
@@ -18,6 +19,12 @@ module Minfraud
       # @return [Minfraud::Model::BillingAddress]
       attr_reader :billing_address
 
+      # An object containing minFraud data related to the billing phone
+      # number used in the transaction.
+      #
+      # @return [Minfraud::Model::Phone]
+      attr_reader :billing_phone
+
       # An object containing minFraud data about the credit card used in the
       # transaction.
       #
@@ -48,13 +55,20 @@ module Minfraud
       # @return [Minfraud::Model::ShippingAddress]
       attr_reader :shipping_address
 
+      # An object containing minFraud data related to the shipping phone
+      # number used in the transaction.
+      #
+      # @return [Minfraud::Model::Phone]
+      attr_reader :shipping_phone
+
       # @!visibility private
       def initialize(record, locales)
-        super(record, locales)
+        super
 
         @billing_address  = Minfraud::Model::BillingAddress.new(
           get('billing_address')
         )
+        @billing_phone    = Minfraud::Model::Phone.new(get('billing_phone'))
         @credit_card      = Minfraud::Model::CreditCard.new(get('credit_card'))
         @device           = Minfraud::Model::Device.new(get('device'))
         @email            = Minfraud::Model::Email.new(get('email'))
@@ -62,6 +76,7 @@ module Minfraud
         @shipping_address = Minfraud::Model::ShippingAddress.new(
           get('shipping_address')
         )
+        @shipping_phone   = Minfraud::Model::Phone.new(get('shipping_phone'))
       end
     end
   end

data/lib/minfraud/model/ip_address.rb

@@ -24,7 +24,7 @@ module Minfraud
       # @!visibility private
       def initialize(record, locales)
         if record
-          super(record, locales)
+          super
         else
           super({}, locales)
         end

data/lib/minfraud/model/ip_risk_reason.rb

@@ -38,7 +38,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @code   = get('code')
         @reason = get('reason')

data/lib/minfraud/model/issuer.rb

@@ -37,7 +37,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @name                          = get('name')
         @phone_number                  = get('phone_number')

data/lib/minfraud/model/phone.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model with information about the billing or shipping phone number.
+    class Phone < Abstract
+      # The two-character ISO 3166-1 country code for the country associated
+      # with the phone number.
+      #
+      # @return [String, nil]
+      attr_reader :country
+
+      # This is true if the phone number is a Voice over Internet Protocol
+      # (VoIP) number allocated by a regulator. It is false if the phone
+      # number is not a VoIP number allocated by a regulator. The attribute
+      # is nil when a valid phone number has not been provided or we do not
+      # have data for the phone number.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_voip
+
+      # The name of the original network operator associated with the phone
+      # number. This attribute does not reflect phone numbers that have been
+      # ported from the original operator to another, nor does it identify
+      # mobile virtual network operators.
+      #
+      # @return [String, nil]
+      attr_reader :network_operator
+
+      # One of the following values: fixed or mobile. Additional values may
+      # be added in the future.
+      #
+      # @return [String, nil]
+      attr_reader :number_type
+
+      # @!visibility private
+      def initialize(record)
+        super
+
+        @country          = get('country')
+        @is_voip          = get('is_voip')
+        @network_operator = get('network_operator')
+        @number_type      = get('number_type')
+      end
+    end
+  end
+end

data/lib/minfraud/model/reason.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # The risk score reason for the multiplier.
+    #
+    # This class provides both a machine-readable code and a human-readable
+    # explanation of the reason for the risk score, see
+    # https://dev.maxmind.com/minfraud/api-documentation/responses/schema--response--risk-score-reason--multiplier-reason.
+    # Although more codes may be added in the future, the current codes are:
+    #
+    # * BROWSER_LANGUAGE - Riskiness of the browser user-agent and
+    #   language associated with the request.
+    # * BUSINESS_ACTIVITY - Riskiness of business activity
+    #   associated with the request.
+    # * COUNTRY - Riskiness of the country associated with the request.
+    # * CUSTOMER_ID - Riskiness of a customer's activity.
+    # * EMAIL_DOMAIN - Riskiness of email domain.
+    # * EMAIL_DOMAIN_NEW - Riskiness of newly-sighted email domain.
+    # * EMAIL_ADDRESS_NEW - Riskiness of newly-sighted email address.
+    # * EMAIL_LOCAL_PART - Riskiness of the local part of the email address.
+    # * EMAIL_VELOCITY - Velocity on email - many requests on same email
+    #   over short period of time.
+    # * ISSUER_ID_NUMBER_COUNTRY_MISMATCH - Riskiness of the country mismatch
+    #   between IP, billing, shipping and IIN country.
+    # * ISSUER_ID_NUMBER_ON_SHOP_ID - Risk of Issuer ID Number for the shop ID.
+    # * ISSUER_ID_NUMBER_LAST_DIGITS_ACTIVITY - Riskiness of many recent requests
+    #   and previous high-risk requests on the IIN and last digits of the credit card.
+    # * ISSUER_ID_NUMBER_SHOP_ID_VELOCITY - Risk of recent Issuer ID Number activity
+    #   for the shop ID.
+    # * INTRACOUNTRY_DISTANCE - Risk of distance between IP, billing,
+    #   and shipping location.
+    # * ANONYMOUS_IP - Risk due to IP being an Anonymous IP.
+    # * IP_BILLING_POSTAL_VELOCITY - Velocity of distinct billing postal code
+    #   on IP address.
+    # * IP_EMAIL_VELOCITY - Velocity of distinct email address on IP address.
+    # * IP_HIGH_RISK_DEVICE - High-risk device sighted on IP address.
+    # * IP_ISSUER_ID_NUMBER_VELOCITY - Velocity of distinct IIN on IP address.
+    # * IP_ACTIVITY - Riskiness of IP based on minFraud network activity.
+    # * LANGUAGE - Riskiness of browser language.
+    # * MAX_RECENT_EMAIL - Riskiness of email address
+    #   based on past minFraud risk scores on email.
+    # * MAX_RECENT_PHONE - Riskiness of phone number
+    #   based on past minFraud risk scores on phone.
+    # * MAX_RECENT_SHIP - Riskiness of email address
+    #   based on past minFraud risk scores on ship address.
+    # * MULTIPLE_CUSTOMER_ID_ON_EMAIL - Riskiness of email address
+    #   having many customer IDs.
+    # * ORDER_AMOUNT - Riskiness of the order amount.
+    # * ORG_DISTANCE_RISK - Risk of ISP and distance between
+    #   billing address and IP location.
+    # * PHONE - Riskiness of the phone number or related numbers.
+    # * CART - Riskiness of shopping cart contents.
+    # * TIME_OF_DAY - Risk due to local time of day.
+    # * TRANSACTION_REPORT_EMAIL - Risk due to transaction reports
+    #   on the email address.
+    # * TRANSACTION_REPORT_IP - Risk due to transaction reports on the IP address.
+    # * TRANSACTION_REPORT_PHONE - Risk due to transaction reports
+    #   on the phone number.
+    # * TRANSACTION_REPORT_SHIP - Risk due to transaction reports
+    #   on the shipping address.
+    # * EMAIL_ACTIVITY - Riskiness of the email address
+    #   based on minFraud network activity.
+    # * PHONE_ACTIVITY - Riskiness of the phone number
+    #   based on minFraud network activity.
+    # * SHIP_ACTIVITY - Riskiness of ship address based on minFraud network activity.
+    class Reason < Abstract
+      # This value is a machine-readable code identifying the reason.
+      #
+      # @return [String]
+      attr_reader :code
+
+      # This property provides a human-readable explanation of the reason. The
+      # description may change at any time and should not be matched against.
+      #
+      # @return [String]
+      attr_reader :reason
+
+      # @!visibility private
+      def initialize(record)
+        super
+
+        @code   = get('code')
+        @reason = get('reason')
+      end
+    end
+  end
+end

data/lib/minfraud/model/risk_score_reason.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/reason'
+
+module Minfraud
+  module Model
+    # The risk score multiplier and the reasons for that multiplier.
+    class RiskScoreReason < Abstract
+      # The factor by which the risk score is increased (if the value is greater than 1)
+      # or decreased (if the value is less than 1) for given risk reason(s).
+      # Multipliers greater than 1.5 and less than 0.66 are considered significant
+      # and lead to risk reason(s) being present.
+      #
+      # @return [Float]
+      attr_reader :multiplier
+
+      # This field contains Risk objects that describe one of the reasons for the multiplier.
+      #
+      # @return [Array<Minfraud::Model::Risk>]
+      attr_reader :reasons
+
+      # @!visibility private
+      def initialize(record)
+        super
+
+        @multiplier = get('multiplier')
+
+        @reasons = []
+        if record&.key?('reasons')
+          record['reasons'].each do |r|
+            @reasons << Minfraud::Model::Reason.new(r)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/minfraud/model/score_ip_address.rb

@@ -14,7 +14,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @risk = get('risk')
       end

data/lib/minfraud/model/shipping_address.rb

@@ -20,7 +20,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @distance_to_billing_address = get('distance_to_billing_address')
         @is_high_risk                = get('is_high_risk')

data/lib/minfraud/model/subscores.rb

@@ -126,7 +126,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @avs_result                               = get('avs_result')
         @billing_address                          = get('billing_address')

data/lib/minfraud/model/warning.rb

@@ -52,7 +52,7 @@ module Minfraud
 
       # @!visibility private
       def initialize(record)
-        super(record)
+        super
 
         @code          = get('code')
         @warning       = get('warning')

data/lib/minfraud/validates.rb

@@ -24,6 +24,19 @@ module Minfraud
       end
     end
 
+    def validate_uuid(field, value)
+      return if !value
+
+      stripped_value = value.to_s.gsub('-', '')
+
+      # Define a regex pattern for a valid UUID without dashes
+      uuid_regex = /\A[0-9a-f]{32}\z/i
+
+      unless uuid_regex.match(stripped_value)
+        raise InvalidInputError, "The #{field} value is not valid. It must be a UUID string."
+      end
+    end
+
     def validate_subdivision_code(field, value)
       return if !value
 

data/lib/minfraud/version.rb

@@ -2,5 +2,5 @@
 
 module Minfraud
   # The Gem version.
-  VERSION = '2.5.0'
+  VERSION = '2.7.0.beta1'
 end

data/minfraud.gemspec

@@ -22,10 +22,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'connection_pool', '~> 2.2'
-  spec.add_runtime_dependency 'http', '>= 4.3', '< 6.0'
-  spec.add_runtime_dependency 'maxmind-geoip2', '~> 1.2'
-  spec.add_runtime_dependency 'simpleidn', '~> 0.1', '>= 0.1.1'
+  spec.add_dependency 'connection_pool', '~> 2.2'
+  spec.add_dependency 'http', '>= 4.3', '< 6.0'
+  spec.add_dependency 'maxmind-geoip2', '~> 1.2'
+  spec.add_dependency 'simpleidn', '~> 0.1', '>= 0.1.1'
 
   spec.add_development_dependency 'bundler', '~> 2.2'
   spec.add_development_dependency 'rake', '~> 13.0'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minfraud
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.7.0.beta1
 platform: ruby
 authors:
 - kushnir.yb
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-04-16 00:00:00.000000000 Z
+date: 2024-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -203,6 +203,9 @@ files:
 - lib/minfraud/model/ip_address.rb
 - lib/minfraud/model/ip_risk_reason.rb
 - lib/minfraud/model/issuer.rb
+- lib/minfraud/model/phone.rb
+- lib/minfraud/model/reason.rb
+- lib/minfraud/model/risk_score_reason.rb
 - lib/minfraud/model/score.rb
 - lib/minfraud/model/score_ip_address.rb
 - lib/minfraud/model/shipping_address.rb
@@ -233,7 +236,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.16
 signing_key: 
 specification_version: 4
 summary: Ruby API for the minFraud Score, Insights, Factors, and Report Transactions