acquiring-sdk-ruby 0.1.0

data/lib/worldline/acquiring/sdk/communication/default_connection.rb

@@ -0,0 +1,429 @@
+require 'httpclient'
+require 'securerandom'
+require 'uri'
+require 'worldline/acquiring/sdk/communication/communication_exception'
+require 'worldline/acquiring/sdk/communication/multipart_form_data_object'
+require 'worldline/acquiring/sdk/communication/pooled_connection'
+require 'worldline/acquiring/sdk/communication/response_header'
+require 'worldline/acquiring/sdk/logging/obfuscation/body_obfuscator'
+require 'worldline/acquiring/sdk/logging/obfuscation/header_obfuscator'
+require 'worldline/acquiring/sdk/logging/request_log_message_builder'
+require 'worldline/acquiring/sdk/logging/response_log_message_builder'
+
+# @private :nodoc: this is not our class
+module RefineHTTPClient
+  refine HTTPClient do
+    # (monkey) patch to gain access to the session pool size in HTTPClient
+    def session_count
+      sess_pool = @session_manager.instance_variable_get(:@sess_pool)
+      sess_pool.size
+    end
+  end
+end
+
+module Worldline
+  module Acquiring
+    module SDK
+      module Communication
+        class DefaultConnection < PooledConnection
+          using RefineHTTPClient
+
+          private
+
+          CONTENT_TYPE = 'Content-Type'.freeze
+          JSON_CONTENT_TYPE = 'application/json'.freeze
+
+          public
+
+          # @param args [Hash] the parameters to initialize the connection with
+          # @option args [Integer] :connect_timeout connection timeout in seconds.
+          # @option args [Integer] :socket_timeout socket timeout in seconds.
+          # @option args [Integer] :max_connections number of connections kept alive in the thread pool.
+          #              Uses {Worldline::Acquiring::SDK::CommunicatorConfiguration.default_max_connections} if not given.
+          # @option args [Worldline::Acquiring::SDK::ProxyConfiguration] :proxy_configuration object that stores the proxy to use.
+          #              If not given the system default proxy is used;
+          #              if there is no system default proxy set either, no proxy is used.
+          def initialize(args)
+            raise ArgumentError unless args.is_a? Hash
+
+            # Set timeouts to nil if they are negative
+            @connect_timeout = args[:connect_timeout]
+            @connect_timeout = nil unless @connect_timeout.nil? || @connect_timeout > 0
+            @socket_timeout = args[:socket_timeout]
+            @socket_timeout = nil unless @socket_timeout.nil? || @socket_timeout > 0
+            @max_connections = args[:max_connections] || CommunicatorConfiguration.default_max_connections
+            @proxy_configuration = args[:proxy_configuration]
+
+            # HTTPClient provides the following features:
+            # 1) thread safe, an instance can be used by multiple threads without
+            # explicit synchronization
+            # 2) use persistent connection if HTTP 1.1 is supported. The connection
+            # will be left open until explicitly closed or keep_alive_timeout
+            # 3) a built-in connection pool with no limit for max connections
+            @http_client = create_http_client
+            @http_client.connect_timeout = @connect_timeout
+            @http_client.send_timeout = @socket_timeout
+            @http_client.receive_timeout = @socket_timeout
+
+            @body_obfuscator = Worldline::Acquiring::SDK::Logging::Obfuscation::BodyObfuscator.default_obfuscator
+            @header_obfuscator = Worldline::Acquiring::SDK::Logging::Obfuscation::HeaderObfuscator.default_obfuscator
+          end
+
+          private
+
+          # Create a HTTPClient instance that uses @proxy_configuration or the system proxy if @proxy_configuration is not set
+          def create_http_client
+            if @proxy_configuration
+              httpclient = HTTPClient.new(@proxy_configuration.proxy_uri)
+              httpclient.set_proxy_auth(@proxy_configuration.username, @proxy_configuration.password)
+              httpclient.force_basic_auth = true unless @proxy_configuration.username.nil? || @proxy_configuration.password.nil?
+              httpclient
+            else
+              # use system settings
+              proxy_string = ENV['https_proxy'] || ENV['http_proxy']
+              # proxy string format = 'http://username:password@hostname:port'
+              proxy_string =~ %r{https?//(?<username>[^:]):(?<password>[^@])@.*}
+              username = Regexp.last_match(1)
+              password = Regexp.last_match(2)
+              httpclient = HTTPClient.new(proxy_string)
+              httpclient.set_proxy_auth(username, password) unless username.nil? || password.nil?
+              httpclient.force_basic_auth = true unless username.nil? || password.nil?
+              httpclient
+            end
+          end
+
+          public
+
+          # Closes all connections idle for longer than _idle_time_ seconds.
+          # In addition, the keep_alive_timeout is set to _idle_time_
+          # so any future connections idle for longer than _idle_time_ seconds will also be closed.
+          def close_idle_connections(idle_time)
+            # in sec
+            @http_client.keep_alive_timeout = idle_time # set timeout value
+            close_expired_connections
+          end
+
+          # HTTPClient automatically closes expired connections so _close_expired_connections_ is a no-operation.
+          def close_expired_connections
+            # By default the keep alive timeout is 15 sec, which is the HTTP 1.1
+            # standard. To change the value, use keep_alive_timeout= method
+            # do nothing, handled by HTTPClient
+          end
+
+          # Frees all networking resources used.
+          def close
+            @http_client.reset_all
+          end
+
+          # Returns the number of open connections
+          def session_count
+            @http_client.session_count
+          end
+
+          # Performs a GET request to the Worldline Acquiring platform
+          # @see request
+          def get(uri, request_headers)
+            request('get', uri, request_headers) do |response_status_code, response_headers, response_body|
+              yield response_status_code, response_headers, response_body
+            end
+          end
+
+          # Performs a DELETE request to the Worldline Acquiring platform
+          # @see request
+          def delete(uri, request_headers)
+            request('delete', uri, request_headers) do |response_status_code, response_headers, response_body|
+              yield response_status_code, response_headers, response_body
+            end
+          end
+
+          # Performs a POST request to the Worldline Acquiring platform
+          # @see request
+          def post(uri, request_headers, body)
+            request('post', uri, request_headers, body) do |response_status_code, response_headers, response_body|
+              yield response_status_code, response_headers, response_body
+            end
+          end
+
+          # Performs a PUT request to the Worldline Acquiring platform
+          # @see request
+          def put(uri, request_headers, body)
+            request('put', uri, request_headers, body) do |response_status_code, response_headers, response_body|
+              yield response_status_code, response_headers, response_body
+            end
+          end
+
+          # Performs a HTTP request and yields the response as the status code, headers and body.
+          # Also ensures the request is logged when sent and its response is logged when received.
+          #
+          # @param method          [String] 'GET', 'DELETE', 'POST' or 'PUT' depending on the HTTP method being used.
+          # @param uri             [URI::HTTP] full URI of the location the request is targeted at, including query parameters.
+          # @param request_headers [Array<Worldline::Acquiring::SDK::Communication::RequestHeader>] list of headers that should be used as HTTP headers in the request.
+          # @param body            [String, Worldline::Acquiring::SDK::Communication::MultipartFormDataObject] request body.
+          # @yield (Integer, Array<Worldline::Acquiring::SDK::Communication::ResponseHeader>, IO) The status code, headers and body of the response.
+          # @raise [Worldline::Acquiring::SDK::Communication::CommunicationException] when communication with the Worldline Acquiring platform was not successful.
+          def request(method, uri, request_headers, body = nil)
+            request_headers = convert_from_sdk_headers(request_headers)
+            request_id = SecureRandom.uuid
+            content_type = request_headers[CONTENT_TYPE]
+
+            info = { headers: request_headers, content_type: content_type }
+            info[:body] = body unless body.nil?
+
+            log_request(request_id, method.upcase, uri, info)
+
+            start_time = Time.now
+            begin
+              response_headers = nil
+              response_status_code = nil
+              response_content_type = nil
+              response_body = ''
+
+              if body.is_a? MultipartFormDataObject
+                multipart_request(method, uri, request_headers, body) do |status_code, headers, r_content_type, r_body|
+                  response_headers = headers
+                  response_status_code = status_code
+                  response_content_type = r_content_type
+                  unless binary_content_type? response_content_type
+                    response_body = r_body.read.force_encoding('UTF-8')
+                    r_body = StringIO.new(response_body)
+                  end
+
+                  yield status_code, headers, r_body
+                end
+              else
+                raw_request(method, uri, request_headers, body) do |status_code, headers, r_content_type, r_body|
+                  response_headers = headers
+                  response_status_code = status_code
+                  response_content_type = r_content_type
+                  unless binary_content_type? response_content_type
+                    response_body = r_body.read.force_encoding('UTF-8')
+                    r_body = StringIO.new(response_body)
+                  end
+
+                  yield status_code, headers, r_body
+                end
+              end
+
+              log_response(request_id, response_status_code, start_time,
+                           headers: response_headers, body: response_body,
+                           content_type: response_content_type)
+            rescue HTTPClient::TimeoutError => e
+              log_error(request_id, start_time, e)
+              raise CommunicationException, e
+            rescue HTTPClient::KeepAliveDisconnected, HTTPClient::RetryableResponse => e # retry these?
+              log_error(request_id, start_time, e)
+              raise CommunicationException, e
+            rescue StandardError => e
+              log_error(request_id, start_time, e)
+              raise CommunicationException, e
+            end
+          end
+
+          # logging code
+
+          # Sets the current body obfuscator to use.
+          # @param body_obfuscator [Worldline::Acquiring::SDK::Logging::Obfuscation::BodyObfuscator]
+          def set_body_obfuscator(body_obfuscator)
+            raise ArgumentError, 'body_obfuscator is required' unless body_obfuscator
+
+            @body_obfuscator = body_obfuscator
+          end
+
+          # Sets the current header obfuscator to use.
+          # @param header_obfuscator [Worldline::Acquiring::SDK::Logging::Obfuscation::HeaderObfuscator]
+          def set_header_obfuscator(header_obfuscator)
+            raise ArgumentError, 'header_obfuscator is required' unless header_obfuscator
+
+            @header_obfuscator = header_obfuscator
+          end
+
+          # Enables logging outgoing requests and incoming responses by registering the _communicator_logger_.
+          # Note that only one logger can be registered at a time and calling _enable_logging_
+          # a second time will override the old logger instance with the new one.
+          #
+          # @param communicator_logger [Worldline::Acquiring::SDK::Logging::CommunicatorLogger] the communicator logger the requests and responses are logged to
+          def enable_logging(communicator_logger)
+            raise ArgumentError, 'communicator_logger is required' unless communicator_logger
+
+            @communicator_logger = communicator_logger
+          end
+
+          # Disables logging by unregistering any previous logger that might be registered.
+          def disable_logging
+            @communicator_logger = nil
+          end
+
+          private
+
+          # Converts a {Worldline::Acquiring::SDK::Communication::RequestHeader} list headers to a hash
+          def convert_from_sdk_headers(headers)
+            headers.each_with_object({}) { |h, hash| hash[h.name] = h.value }
+          end
+
+          # Converts a hash to a {Worldline::Acquiring::SDK::Communication::ResponseHeader} list
+          def convert_to_sdk_response_headers(headers)
+            arr ||= []
+            headers.each { |k, v| arr << ResponseHeader.new(k, v) }
+            arr
+          end
+
+          def log_request(request_id, method, uri, args = {})
+            logger = @communicator_logger
+            return unless logger
+
+            headers = args[:headers]
+            body = args[:body]
+            content_type = args[:content_type]
+            log_msg_builder = Worldline::Acquiring::SDK::Logging::RequestLogMessageBuilder.new(request_id, method, uri,
+                                                                                             @body_obfuscator,
+                                                                                             @header_obfuscator)
+            headers.each { |k, v| log_msg_builder.add_headers(k, v) } if headers
+
+            if binary?(headers)
+              log_msg_builder.set_body('<binary content>', content_type)
+            else
+              log_msg_builder.set_body(body, content_type)
+            end
+
+            begin
+              logger.log(log_msg_builder.get_message)
+            rescue StandardError => e
+              logger.log("An error occurred trying to log request #{request_id}", e)
+            end
+          end
+
+          # Creates the log_response stream
+          # both based on whether or not it is binary and on the rest of the response
+          def log_response(request_id, status_code, start_time, args = {})
+            logger = @communicator_logger
+            return unless logger
+
+            duration = (Time.now - start_time) * 1000 # in milliseconds
+            headers = args[:headers]
+            body = args[:body] unless args[:body].nil?
+            content_type = args[:content_type]
+
+            log_msg_builder = Worldline::Acquiring::SDK::Logging::ResponseLogMessageBuilder.new(request_id, status_code, duration,
+                                                                                                @body_obfuscator,
+                                                                                                @header_obfuscator)
+            unless headers.nil?
+              headers = convert_from_sdk_headers(headers)
+              headers.each do |key, value|
+                log_msg_builder.add_headers(key, value)
+              end
+            end
+
+            if binary_content_type?(content_type)
+              log_msg_builder.set_body('<binary content>', content_type)
+            else
+              log_msg_builder.set_body(body, content_type)
+            end
+
+            begin
+              logger.log(log_msg_builder.get_message)
+            rescue StandardError => e
+              logger.log("An error occurred trying to log response #{request_id}", e)
+            end
+          end
+
+          def log_error(request_id, start_time, thrown)
+            logger = @communicator_logger
+            return unless logger
+
+            duration = (Time.now - start_time) * 1000 # in millisecs
+            logger.log("Error occurred for outgoing request (requestId='#{request_id}', #{duration} ms)", thrown)
+          end
+
+          # @param headers [Hash]
+          def binary?(headers)
+            unless headers.nil?
+              content_type = nil
+              headers.each { |k, v| content_type = v if k.casecmp(CONTENT_TYPE).zero? }
+
+              binary_content_type?(content_type)
+            end
+          end
+
+          # @param content_type [String, nil]
+          def binary_content_type?(content_type)
+            unless content_type.nil?
+              content_type = content_type.downcase
+              return !content_type.start_with?('text/') &&
+                !content_type.include?('json') &&
+                !content_type.include?('xml')
+            end
+            false
+          end
+
+          # Makes a request using the specified method
+          #
+          # Yields a status code, an array of {Worldline::Acquiring::SDK::Communication::ResponseHeader},
+          # the content_type and body
+          def raw_request(method, uri, headers, body = nil)
+            connection = if body
+                           @http_client.send(method + '_async', uri, body: body, header: headers)
+                         else
+                           @http_client.send(method + '_async', uri, header: headers)
+                         end
+
+            response = connection.pop
+            pipe = response.content
+            response_headers = convert_to_sdk_response_headers(response.headers)
+
+            begin
+              yield response.status_code, response_headers, response.content_type, pipe
+            ensure
+              pipe.close
+            end
+          end
+
+          # Makes a request using the specified method
+          #
+          # Yields a status code, an array of {Worldline::Acquiring::SDK::Communication::ResponseHeader},
+          # the content_type and body
+          def multipart_request(method, uri, headers, body = nil)
+            unless body.is_a? MultipartFormDataObject
+              raise ArgumentError, 'body should be a MultipartFormDataObject'
+            end
+
+            if method != 'post' && method != 'put'
+              raise ArgumentError, "method #{method} is not supported"
+            end
+
+            connection = @http_client.send method + '_async',
+                                           uri,
+                                           body: multipart_request_body(body),
+                                           header: headers
+
+            response = connection.pop
+            pipe = response.content
+            response_headers = convert_to_sdk_response_headers(response.headers)
+
+            begin
+              yield response.status_code, response_headers, response.content_type, pipe
+            ensure
+              pipe.close
+            end
+          end
+
+          # Creates a request body for the multipart request
+          def multipart_request_body(body)
+            request_body = []
+            body.files.each do |k, v|
+              request_body.push :content => v.content,
+                                'Content-Type' => v.content_type,
+                                'Content-Disposition' => "form-data; name=\"#{k}\"; filename=\"#{v.file_name}\"",
+                                'Content-Transfer-Encoding' => 'binary'
+            end
+
+            body.values.each do |k, v|
+              request_body << { :content => v,
+                                'Content-Disposition' => "form-data; name=\"#{k}\"" }
+            end
+            request_body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/worldline/acquiring/sdk/communication/metadata_provider.rb

@@ -0,0 +1,162 @@
+require 'base64'
+require 'worldline/acquiring/sdk/communication/request_header'
+require 'worldline/acquiring/sdk/domain/data_object'
+require 'worldline/acquiring/sdk/domain/shopping_cart_extension'
+require 'worldline/acquiring/sdk/json/default_marshaller'
+
+module Worldline
+  module Acquiring
+    module SDK
+      module Communication
+        # Manages metadata about the server using the SDK
+        #
+        # @attr_reader [Array<Worldline::Acquiring::SDK::Communication::RequestHeader>] metadata_headers List of headers that should be used in all requests.
+        class MetadataProvider
+          private
+
+          SDK_VERSION = '0.1.0'.freeze
+          SERVER_META_INFO_HEADER = 'X-WL-ServerMetaInfo'.freeze
+          PROHIBITED_HEADERS = [SERVER_META_INFO_HEADER, 'Date', 'Content-Type', 'Authorization'].sort!.freeze
+          CHARSET = 'utf-8'.freeze
+
+          public
+
+          # Stores metadata about the server so it can be sent to the Worldline Acquiring platform
+          class ServerMetaInfo < Worldline::Acquiring::SDK::Domain::DataObject
+            @platform_identifier = nil
+            @sdk_identifier = nil
+            @sdk_creator = nil
+            @integrator = nil
+            @shopping_cart_extension = nil
+
+            # String containing system information (Operating system and Ruby version).
+            attr_accessor :platform_identifier
+
+            # String containing this SDK version.
+            attr_accessor :sdk_identifier
+
+            attr_accessor :sdk_creator
+
+            attr_accessor :integrator
+
+            attr_accessor :shopping_cart_extension
+
+            # Returns the values of all attributes as a hash.
+            def to_h
+              hash = super
+              hash['platformIdentifier'] = @platform_identifier unless @platform_identifier.nil?
+              hash['sdkIdentifier'] = @sdk_identifier unless @sdk_identifier.nil?
+              hash['sdkCreator'] = @sdk_creator unless @sdk_creator.nil?
+              hash['integrator'] = @integrator unless @integrator.nil?
+              hash['shoppingCartExtension'] = @shopping_cart_extension.to_h unless @shopping_cart_extension.nil?
+              hash
+            end
+
+            # Initializes the ServerMetaInfo object with properties stored in the parameter hash
+            def from_hash(hash)
+              super
+              @platform_identifier = hash['platformIdentifier'] if hash.has_key? 'platformIdentifier'
+              @sdk_identifier = hash['sdkIdentifier'] if hash.has_key? 'sdkIdentifier'
+              @sdk_creator = hash['sdkCreator'] if hash.has_key? 'sdkCreator'
+              @integrator = hash['integrator'] if hash.has_key? 'integrator'
+              @shopping_cart_extension = Worldline::Acquiring::SDK::Domain::ShoppingCartExtension.new_from_hash(hash['shoppingCartExtension']) if hash.has_key? 'shoppingCartExtension'
+            end
+          end
+
+          # Create a new MetadataProvider instance that can be used to access platform-related information
+          #
+          # @param integrator                 [String] Name of the integrator
+          # @param shopping_cart_extension    [Worldline::Acquiring::SDK::Domain::ShoppingCartExtension] shopping cart-related metadata.
+          # @param additional_request_headers [Array<Worldline::Acquiring::SDK::Communication::RequestHeader>] list of additional headers to include in all requests made.
+          #                                   The following headers are not allowed due to conflicts with already added headers:
+          #                                   'Date', 'Content-Type', 'Authorization' and 'X-WL-ServerMetaInfo'
+          def initialize(integrator, shopping_cart_extension: nil, additional_request_headers: [].freeze)
+            raise ArgumentError.new('integrator is required') if integrator.nil? or integrator.strip.empty?
+            MetadataProvider.validate_additional_request_headers(additional_request_headers)
+            server_meta_info = ServerMetaInfo.new
+            server_meta_info.platform_identifier = get_platform_identifier
+            server_meta_info.sdk_identifier = get_sdk_identifier
+            server_meta_info.sdk_creator = 'Worldline'
+            server_meta_info.integrator = integrator
+            server_meta_info.shopping_cart_extension = shopping_cart_extension unless shopping_cart_extension.nil?
+            server_meta_info_string = Worldline::Acquiring::SDK::JSON::DefaultMarshaller.instance.marshal(server_meta_info)
+            server_meta_info_header = RequestHeader.new(
+              SERVER_META_INFO_HEADER, Base64.strict_encode64(
+              server_meta_info_string.force_encoding('iso-8859-1').encode(CHARSET)))
+            if additional_request_headers.nil? || additional_request_headers.empty?
+              @metadata_headers = [server_meta_info_header].freeze
+            else
+              request_headers = [server_meta_info_header]
+              request_headers += additional_request_headers
+              @metadata_headers = request_headers.freeze
+            end
+          end
+
+          # Checks that none of the {Worldline::Acquiring::SDK::Communication::RequestHeaders} in _additional_request_headers_ is equal to any of the forbidden headers.
+          # The forbidden headers are:
+          # 'Date', 'Content-Type', 'Authorization' and 'X-WL-ServerMetaInfo'
+          # If a header is found that is equal to one of the forbidden headers an ArgumentError is raised.
+          def self.validate_additional_request_headers(additional_request_headers)
+            unless additional_request_headers.nil?
+              additional_request_headers.each { |additional_request_header|
+                validate_additional_request_header(additional_request_header)
+              }
+            end
+          end
+
+          # Checks that the {Worldline::Acquiring::SDK::Communication::RequestHeaders} _additional_request_header_ is equal to any of the forbidden headers.
+          # The forbidden headers are:
+          # 'Date', 'Content-Type', 'Authorization' and 'X-WL-ServerMetaInfo'
+          # If the header is equal to one of the forbidden headers an ArgumentError is raised.
+          def self.validate_additional_request_header(additional_request_header)
+            if prohibited_headers.include? additional_request_header.name
+              raise ArgumentError.new('request header not allowed' + additional_request_header.name)
+            end
+          end
+
+          protected
+
+          # String containing information of the system using the SDK.
+          # It contains data like Operating System version and Ruby version
+          def get_platform_identifier
+            config = RbConfig::CONFIG['host_os']
+            if config.include? 'mingw'
+              s = 'Windows'
+            elsif config.include? 'linux'
+              s = 'Linux'
+            else
+              s = 'Mac OS X'
+            end
+            s + '/' + RUBY_DESCRIPTION
+          end
+
+          # String describing the version of the SDK being used
+          def get_sdk_identifier
+            'RubyServerSDK/v' + SDK_VERSION
+          end
+
+          public
+
+          # Version of this SDK being used
+          def self.sdk_version
+            SDK_VERSION
+          end
+
+          # A {Worldline::Acquiring::SDK::Communication::RequestHeader} that contains serialized and encoded
+          # {Worldline::Acquiring::SDK::Communication::MetadataProvider::ServerMetaInfo}.
+          def self.server_meta_info_header
+            SERVER_META_INFO_HEADER
+          end
+
+          # A list of header names that should not be used by any added headers.
+          # These headers are reserved for specific purposes.
+          def self.prohibited_headers
+            PROHIBITED_HEADERS
+          end
+
+          attr_reader :metadata_headers
+        end
+      end
+    end
+  end
+end

data/lib/worldline/acquiring/sdk/communication/multipart_form_data_object.rb

@@ -0,0 +1,54 @@
+require 'securerandom'
+
+module Worldline
+  module Acquiring
+    module SDK
+      module Communication
+        # A representation of a multipart/form-data object
+        #
+        # @attr_reader [String] boundary
+        # @attr_reader [String] content_type
+        # @attr_reader [Hash] values
+        # @attr_reader [Hash] files
+        class MultipartFormDataObject
+          def initialize
+            @boundary = SecureRandom.uuid
+            @content_type = 'multipart/form-data; boundary=' + @boundary
+            @values = {}
+            @files = {}
+          end
+
+          attr_reader :boundary
+          attr_reader :content_type
+          attr_reader :values
+          attr_reader :files
+
+          def add_value(parameter_name, value)
+            if parameter_name.nil? || parameter_name.strip.empty?
+              raise ArgumentError, 'parameter_name is required'
+            end
+            raise ArgumentError, 'value is required' if value.nil?
+            if @values.include?(parameter_name) || @files.include?(parameter_name)
+              raise ArgumentError, 'duplicate parameterName: ' + parameter_name
+            end
+
+            @values[parameter_name] = value
+          end
+
+          # Adds a file to the multipart Form Data Object
+          def add_file(parameter_name, uploadable_file)
+            if parameter_name.nil? || parameter_name.strip.empty?
+              raise ArgumentError, 'parameter_name is required'
+            end
+            raise ArgumentError, 'uploadable_file is required' if uploadable_file.nil?
+            if @values.include?(parameter_name) || @files.include?(parameter_name)
+              raise ArgumentError, 'duplicate parameterName: ' + parameter_name
+            end
+
+            @files[parameter_name] = uploadable_file
+          end
+        end
+      end
+    end
+  end
+end

data/lib/worldline/acquiring/sdk/communication/multipart_form_data_request.rb

@@ -0,0 +1,15 @@
+module Worldline
+  module Acquiring
+    module SDK
+      module Communication
+        # A representation of a multipart/form-data request
+        class MultipartFormDataRequest
+          # @return [Worldline::Acquiring::SDK::Communication::MultipartFormDataObject]
+          def to_multipart_form_data_object
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/worldline/acquiring/sdk/communication/not_found_exception.rb

@@ -0,0 +1,21 @@
+module Worldline
+  module Acquiring
+    module SDK
+      module Communication
+        # Raised when a resource is not found on the Worldline Acquiring platform.
+        # This error corresponds to a 404 HTTP response.
+        #
+        # @attr [Exception] cause The error that is the cause of this error.
+        class NotFoundException < RuntimeError
+
+          def initialize(cause, message = nil)
+            super(message)
+            @cause = cause
+          end
+
+          attr_accessor :cause
+        end
+      end
+    end
+  end
+end