genesis_ruby 0.1.0 → 0.1.2

data/lib/genesis_ruby/api/constants/transactions/parameters/refund/bank_account_types.rb

@@ -0,0 +1,27 @@
+module GenesisRuby
+  module Api
+    module Constants
+      module Transactions
+        module Parameters
+          module Refund
+            # Available Bank Account Types used in the Refund transaction request
+            class BankAccountTypes
+
+              extend Mixins::Constants::Common
+
+              # C: for Checking accounts
+              CHECKING      = 'C'.freeze
+
+              # S: for Savings accounts
+              SAVINGS       = 'S'.freeze
+
+              # I: for International accounts
+              INTERNATIONAL = 'I'.freeze
+
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/notification.rb

@@ -0,0 +1,156 @@
+require 'cgi'
+require 'digest'
+
+module GenesisRuby
+  module Api
+    # Gateway Notification handler
+    class Notification
+
+      attr_reader :unique_id, :notification, :reconciliation
+
+      # Signature algorithms
+      SHA1_SIGNATURE_TYPE   = 'SHA1'.freeze
+      SHA256_SIGNATURE_TYPE = 'SHA256'.freeze
+      SHA512_SIGNATURE_TYPE = 'SHA512'.freeze
+
+      # Possible request/response identifier fields
+      API_UNIQUE_FIELD = 'unique_id'.freeze
+      WPF_UNIQUE_FIELD = 'wpf_unique_id'.freeze
+      KYC_UNIQUE_FIELD = 'reference_id'.freeze
+
+      # Class constructor
+      def initialize(configuration, data)
+        @configuration = configuration
+
+        parse_notification data
+      end
+
+      # Check if the given data is API notification
+      def api_notification?
+        notification.key? :unique_id
+      end
+
+      # Check if the given data is Web Payment Form notification
+      def wpf_notification?
+        notification.key? :wpf_unique_id
+      end
+
+      # Check if the given data is Know Your Customer notification
+      def kyc_notification?
+        notification.key? :reference_id
+      end
+
+      # Generates XML document expected from the Gateway
+      def generate_response
+        response = {
+          notification_echo: [[fetch_response_unique_field, unique_id]].to_h
+        }
+
+        builder = GenesisRuby::Builder.new Builder::XML
+        builder.parse_structure response
+
+        builder.document
+      end
+
+      # Execute Reconcile API Request
+      def reconcile
+        request_object = fetch_reconciliation_request
+
+        begin
+          genesis = Genesis.for config: @configuration, request: request_object do |req|
+            req.unique_id = unique_id
+          end.execute
+
+          @reconciliation = genesis.response
+        rescue Error
+          @reconciliation = nil
+        end
+      end
+
+      # Determinate if the executed reconciliation response contains transaction data
+      def transaction_reconciliation?
+        response_object = reconciliation&.response_object
+
+        return false if response_object.nil?
+
+        response_object.key?(:unique_id) && response_object.key?(:transaction_id) && response_object.key?(:status)
+      end
+
+      private
+
+      # Parse the given notification data
+      def parse_notification(data, authenticate: true)
+        @notification = parse_raw_data data
+        @unique_id    = fetch_unique_id
+
+        raise ParameterError, 'Invalid Genesis Notification!' if authenticate && !authentic?
+      end
+
+      # Parse the given raw data
+      def parse_raw_data(data)
+        normalize_data data.to_h
+      rescue StandardError => e
+        raise ParameterError, "Given notification data doesn't respond to_h! #{e.message}"
+      end
+
+      # Normalize the given notification data
+      def normalize_data(data)
+        data.map { |key, value| [CGI.unescape(key.to_s).to_sym, CGI.unescape(value.strip)] }.to_h
+      end
+
+      # Assign the unique_id property based on the given notification data
+      def fetch_unique_id
+        return @notification[API_UNIQUE_FIELD.to_sym] if api_notification?
+        return @notification[WPF_UNIQUE_FIELD.to_sym] if wpf_notification?
+        return @notification[KYC_UNIQUE_FIELD.to_sym] if kyc_notification?
+
+        nil
+      end
+
+      # Validate the Notification signature
+      def authentic?
+        if unique_id.nil? || notification[:signature].nil?
+          raise ParameterError, 'Missing Notification attributes: unique_id or signature'
+        end
+
+        generated_signature = fetch_signature_generator.hexdigest "#{unique_id}#{@configuration.password}"
+
+        notification[:signature] == generated_signature
+      end
+
+      # Fetch the hash generator based on the hash type
+      def fetch_signature_generator
+        Digest.const_get fetch_hash_type
+      end
+
+      # Fetch the hash algorithm by the given signature length
+      def fetch_hash_type
+        case notification[:signature].length
+        when 40 then SHA1_SIGNATURE_TYPE
+        when 64 then SHA256_SIGNATURE_TYPE
+        when 128 then SHA512_SIGNATURE_TYPE
+        else
+          SHA1_SIGNATURE_TYPE
+        end
+      end
+
+      # Fetches the response field identifier name witch is expected from the Gateway
+      def fetch_response_unique_field
+        return API_UNIQUE_FIELD if api_notification?
+        return WPF_UNIQUE_FIELD if wpf_notification?
+        return KYC_UNIQUE_FIELD if kyc_notification?
+
+        raise ParameterError, 'Unknown notification type!'
+      end
+
+      # Fetch the Reconcile object
+      def fetch_reconciliation_request
+        return Requests::NonFinancial::Reconcile::Transaction if api_notification?
+        return Requests::Wpf::Reconcile if wpf_notification?
+
+        raise ParameterError, 'Unsupported notification type for Reconciliation'
+      end
+
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/base/financials/credit_card.rb

@@ -1,5 +1,3 @@
-require 'genesis_ruby/api/requests/base/financial'
-
 module GenesisRuby
   module Api
     module Requests

data/lib/genesis_ruby/api/requests/base/reference.rb

@@ -0,0 +1,29 @@
+module GenesisRuby
+  module Api
+    module Requests
+      module Base
+        # Base class used in the Reference transaction requests
+        class Reference < Financial
+
+          include Mixins::Requests::Financial::PaymentAttributes
+          include Mixins::Requests::Financial::ReferenceAttributes
+
+          protected
+
+          # Reference transaction request structure
+          def reference_transaction_structure
+            raise NotImplementedError, 'Reference transaction structure must be implemented.'
+          end
+
+          # Payment transaction structure sent to the Gateway
+          def payment_transaction_structure
+            {
+              reference_id: reference_id
+            }.merge payment_attributes_structure, reference_transaction_structure
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/financial/capture.rb

@@ -0,0 +1,30 @@
+module GenesisRuby
+  module Api
+    module Requests
+      module Financial
+        # Capture settles a transaction which has been authorized before
+        class Capture < Requests::Base::Reference
+
+          include Mixins::Requests::Financial::Business::BusinessAttributes
+          include Mixins::Requests::RestrictedSetter
+
+          protected
+
+          # Capture Transaction Request type
+          def transaction_type
+            Api::Constants::Transactions::CAPTURE
+          end
+
+          # Capture Transaction Request Structure
+          def reference_transaction_structure
+            {
+              reference_id:        reference_id,
+              business_attributes: business_attributes_structure
+            }
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/financial/cards/threeds/v2/method_continue.rb

@@ -0,0 +1,145 @@
+require 'genesis_ruby/utils/threeds/v2'
+
+module GenesisRuby
+  module Api
+    module Requests
+      module Financial
+        module Cards
+          module Threeds
+            module V2
+              # Method Continue API request
+              class MethodContinue < Request
+
+                include Mixins::Requests::Financial::PaymentAttributes
+                include Mixins::Requests::RestrictedSetter
+
+                attr_writer :url, :transaction_unique_id, :signature
+
+                class << self
+
+                  def build_from_response_object(configuration, response_object)
+                    if response_object[:threeds_method_continue_url].nil? ||
+                       response_object[:unique_id].nil? ||
+                       response_object[:amount].nil? || response_object[:currency].nil? ||
+                       response_object[:timestamp].nil? || !response_object[:timestamp].is_a?(DateTime)
+
+                      raise ParameterError, 'Response object is incomplete or required attributes are missing!'
+                    end
+
+                    build_method_continue_request configuration, response_object
+                  end
+
+                  private
+
+                  # Build Method Continue Request
+                  def build_method_continue_request(configuration, response_object)
+                    request = new configuration
+
+                    request.url                   = response_object[:threeds_method_continue_url]
+                    request.transaction_unique_id = response_object[:unique_id]
+                    request.amount                = response_object[:amount]
+                    request.currency              = response_object[:currency]
+                    request.transaction_timestamp = response_object[:timestamp].strftime(
+                      Constants::DateTimeFormats::YYYY_MM_DD_H_I_S_ZULU
+                    )
+
+                    GenesisRuby::Genesis.new configuration, request
+                  end
+
+                end
+
+                # Override default constructor with FORM Builder Interface
+                def initialize(configuration, _builder_interface = nil)
+                  super(configuration, Builder::FORM)
+                end
+
+                # A link between the customer's browser and the card issuer must be opened with a hidden iframe
+                def url
+                  return @url = generate_endpoint_url if @url.nil?
+
+                  @url
+                end
+
+                # Equivalent to the value of the unique_id,
+                # received from the response of the initial transaction request
+                def transaction_unique_id
+                  return extract_unique_id_from_url @url if @transaction_unique_id.nil?
+
+                  @transaction_unique_id
+                end
+
+                # SHA512 of а concatenated string (unique_id, amount, timestamp, merchant_api_password)
+                def signature
+                  return @signature unless @signature.nil?
+
+                  payment_amount = @currency.nil? ? amount : transform_amount(amount, currency)
+
+                  Utils::Threeds::V2.generate_signature(
+                    unique_id: transaction_unique_id,
+                    amount: payment_amount,
+                    timestamp: transaction_timestamp,
+                    merchant_password: @configuration.password
+                  )
+                end
+
+                # The timestamp from the initial transaction response
+                def transaction_timestamp
+                  @transaction_timestamp&.strftime(
+                    GenesisRuby::Api::Constants::DateTimeFormats::YYYY_MM_DD_H_I_S_ZULU
+                  )
+                end
+
+                # The timestamp from the initial transaction response
+                def transaction_timestamp=(value)
+                  parse_date attribute: __method__, value: value, allow_empty: true
+                end
+
+                protected
+
+                # Init Method Continue Request configuration
+                def init_configuration
+                  init_form_configuration
+
+                  @api_config.type = Request::METHOD_PUT
+
+                  init_api_gateway_configuration request_path: 'threeds/threeds_method/:unique_id', include_token: false
+                end
+
+                # Build correct endpoint url during runtime
+                def process_request_parameters
+                  @api_config.url = url
+
+                  super
+                end
+
+                # Method Continue Request structure
+                def populate_structure
+                  @tree_structure = {
+                    unique_id: transaction_unique_id,
+                    signature: signature
+                  }
+                end
+
+                private
+
+                # Fills the Unique Id in the endpoint URL
+                def generate_endpoint_url
+                  @api_config.url&.sub! ':unique_id', transaction_unique_id.to_s
+                end
+
+                # Extract the Unique Id
+                def extract_unique_id_from_url(url)
+                  uri           = URI.parse url || ''
+                  exploded_path = uri.path&.split('/')
+
+                  exploded_path.last
+                end
+
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/financial/refund.rb

@@ -0,0 +1,48 @@
+require 'genesis_ruby/api/constants/transactions/parameters/refund/bank_account_types'
+
+module GenesisRuby
+  module Api
+    module Requests
+      module Financial
+        # Refund reference transaction request
+        class Refund < Requests::Base::Reference
+
+          include Mixins::Requests::RestrictedSetter
+
+          attr_accessor :beneficiary_bank_code, :beneficiary_name, :beneficiary_account_number, :bank, :bank_branch,
+                        :bank_account
+          attr_reader :bank_account_type
+
+          # The type of account
+          def bank_account_type=(value)
+            allowed_options attribute:   __method__,
+                            allowed:     Api::Constants::Transactions::Parameters::Refund::BankAccountTypes.all,
+                            value:       value,
+                            allow_empty: true
+          end
+
+          protected
+
+          # Refund Transaction Request type
+          def transaction_type
+            Api::Constants::Transactions::REFUND
+          end
+
+          # Refund Transaction Request Structure
+          def reference_transaction_structure
+            {
+              beneficiary_bank_code:      beneficiary_bank_code,
+              beneficiary_name:           beneficiary_name,
+              beneficiary_account_number: beneficiary_account_number,
+              bank:                       bank,
+              bank_branch:                bank_branch,
+              bank_account:               bank_account,
+              bank_account_type:          bank_account_type
+            }
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/financial/void.rb

@@ -0,0 +1,28 @@
+module GenesisRuby
+  module Api
+    module Requests
+      module Financial
+        # Void or undo payment transaction request
+        class Void < Base::Financial
+
+          include Mixins::Requests::Financial::ReferenceAttributes
+
+          protected
+
+          # Void transaction type
+          def transaction_type
+            Api::Constants::Transactions::VOID
+          end
+
+          # Void transaction request structure
+          def payment_transaction_structure
+            {
+              reference_id: reference_id
+            }
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/non_financial/reconcile/date_range.rb

@@ -0,0 +1,95 @@
+module GenesisRuby
+  module Api
+    module Requests
+      module NonFinancial
+        module Reconcile
+          # Date range based reconciliation allows you to fetch information for all payment transactions from
+          # a terminal within a given date range.
+          # The response is paginated, each request will return 100 entries max.
+          class DateRange < Api::Request
+
+            include Mixins::Requests::RestrictedSetter
+
+            attr_reader :page
+
+            # Start of the requested date range (time is optional)
+            def start_date
+              format = if start_date_time?
+                         Constants::DateTimeFormats::YYYY_MM_DD_H_I_S
+                       else
+                         Constants::DateTimeFormats::YYYY_MM_DD_ISO_8601
+                       end
+
+              @start_date&.strftime format
+            end
+
+            # Start of the requested date range (time is optional)
+            def start_date=(value)
+              self.start_date_time = Utils::Common.date_has_time? value
+
+              parse_date attribute: __method__, value: value, allow_empty: false
+            end
+
+            # Start of the requested date range (time is optional)
+            def end_date
+              format = if end_date_time?
+                         Constants::DateTimeFormats::YYYY_MM_DD_H_I_S
+                       else
+                         Constants::DateTimeFormats::YYYY_MM_DD_ISO_8601
+                       end
+
+              @end_date&.strftime format
+            end
+
+            # End of the requested date range (time is optional)
+            def end_date=(value)
+              self.end_date_time = Utils::Common.date_has_time? value
+
+              parse_date attribute: __method__, value: value, allow_empty: true
+            end
+
+            # The page within the paginated result, defaults to 1
+            def page=(value)
+              @page = value&.to_i
+            end
+
+            protected
+
+            # Set Gateway API configuration
+            def init_configuration
+              init_xml_configuration
+              init_api_gateway_configuration request_path: 'reconcile/by_date'
+              @api_config.parser_skip_root_node = false
+            end
+
+            # API Request structure
+            def populate_structure
+              @tree_structure = {
+                reconcile: {
+                  start_date: start_date,
+                  end_date:   end_date,
+                  page:       page
+                }
+              }
+            end
+
+            private
+
+            attr_accessor :start_date_time, :end_date_time
+
+            # Start Date has time within the given string
+            def start_date_time?
+              self.start_date_time ||= false
+            end
+
+            # End Date has time within the given string
+            def end_date_time?
+              self.end_date_time ||= false
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/non_financial/reconcile/transaction.rb

@@ -0,0 +1,37 @@
+module GenesisRuby
+  module Api
+    module Requests
+      module NonFinancial
+        module Reconcile
+          # Reconcile can be used to retrieve data about a transaction.
+          # This can be useful if you want to retrieve information about a transaction whose status is timeout,
+          # which returned an error or has changed eg. has beed chargebacked.
+          class Transaction < Api::Request
+
+            attr_accessor :arn, :transaction_id, :unique_id
+
+            protected
+
+            # Set Gateway API configuration
+            def init_configuration
+              init_xml_configuration
+              init_api_gateway_configuration request_path: 'reconcile'
+            end
+
+            # API Request structure
+            def populate_structure
+              @tree_structure = {
+                reconcile: {
+                  arn:            arn,
+                  transaction_id: transaction_id,
+                  unique_id:      unique_id
+                }
+              }
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/requests/wpf/reconcile.rb

@@ -0,0 +1,33 @@
+module GenesisRuby
+  module Api
+    module Requests
+      module Wpf
+        # Reconcile can be used to retrieve data about a payment.
+        # This can be useful if you want to retrieve information about a payment whose status is timeout,
+        # which returned an error or has changed eg. has beed chargebacked.
+        class Reconcile < Request
+
+          attr_accessor :unique_id
+
+          protected
+
+          # Define WPF Reconcile request configuration
+          def init_configuration
+            init_xml_configuration
+            @api_config.url = build_request_url subdomain: 'wpf', path: 'wpf/reconcile'
+          end
+
+          # WPF Reconcile request structure
+          def populate_structure
+            @tree_structure = {
+              wpf_reconcile: {
+                unique_id: unique_id
+              }
+            }
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/genesis_ruby/api/response.rb

@@ -10,10 +10,11 @@ module GenesisRuby
     # Response - process/format an incoming Genesis response
     class Response
 
-      def initialize(configuration)
+      def initialize(configuration, request_api_config = {})
         @configuration      = configuration
         @object_formatter   = GenesisRuby::Utils::ObjectFormatter.new
         @response_formatter = GenesisRuby::Utils::Formatters::Response::Loader.new
+        @request_api_config = request_api_config
       end
 
       # Default Response Object initialization
@@ -54,11 +55,11 @@ module GenesisRuby
       # Load the corresponding parser based on the Network header
       def load_parser(network)
         @parser = GenesisRuby::Parsers.new(GenesisRuby::Parser::JSON) if network.json?
+        @parser = GenesisRuby::Parser.new(GenesisRuby::Parser::XML) if network.xml?
 
-        if network.xml?
-          @parser = GenesisRuby::Parser.new(GenesisRuby::Parser::XML)
-          @parser.skip_root_node
-        end
+        raise NetworkError, network.server_message if @parser.nil? || @response_raw.empty?
+
+        @parser.skip_root_node if @request_api_config[:parser_skip_root_node]
 
         @parser
       end

data/lib/genesis_ruby/builder.rb

@@ -1,4 +1,5 @@
 require 'genesis_ruby/builders/xml'
+require 'genesis_ruby/builders/form'
 require 'genesis_ruby/errors/builder_error'
 
 module GenesisRuby
@@ -17,8 +18,8 @@ module GenesisRuby
     # Initialize the Builder Interface based on the Request requirements
     def initialize(request_interface)
       case request_interface
-      when XML
-        @builder_context = GenesisRuby::Builders::Xml.new
+      when XML then @builder_context = Builders::Xml.new
+      when FORM then @builder_context = Builders::Form.new
       else
         raise GenesisRuby::BuilderError, 'Invalid Builder interface!'
       end