onlinepayments-sdk-ruby 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b972879b30e86122019cb9683a9c0f9bb22e930f3cdb70202dcd71d9b5b3fb48
+  data.tar.gz: 85d3c34d68492ea5b77e641d3a1283d312a054105e7421ec19c9c048b3eb3d42
+SHA512:
+  metadata.gz: 1d2c66697f92e16a30dff1e09199261b8208acbe58162a2d92f1a48cc1751adf58559d2227b1b27af30be5d77f77a9bb6090983b6bb9d49edbfc2d9a53530f3c
+  data.tar.gz: 979d0f48a0d1be1b16d392d0178dd562896fd31095892ee032d646cf43c8b0506f7af5171454cabdf95d2f8354f0bd8998c7425fccd5d40cf78214b4b3b57c2f

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Global Collect Services B.V.
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# Online Payments Ruby SDK
+
+## Introduction
+
+The Ruby SDK helps you to communicate with the payment platform server API. Its primary features are:
+
+* convenient Ruby library for the API calls and responses
+    * marshalls Ruby request objects to HTTP requests
+    * unmarshalls HTTP responses to Ruby response objects or Ruby exceptions
+* handling of all the details concerning authentication
+* handling of required meta data
+
+Its use is demonstrated by an example for each possible call. The examples execute a call using the provided API keys. 
+
+## Structure of this repository
+
+This repository consists out of three main components:
+
+1. The source code of the SDK itself: `/lib/onlinepayments/sdk/`
+2. The source code of the SDK unit tests: `/spec/lib/`
+3. The source code of the SDK integration tests: `/spec/integration/`
+
+Note that the source code of the unit tests and integration tests can only be found on GitHub.
+
+## Requirements
+
+Ruby 2.3 or higher is required.
+As for JRuby, version 9.0.0.0 and higher are supported.
+In addition, the following packages are required:
+
+* [httpclient](https://github.com/nahi/httpclient) 2.8 or higher
+* [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) 1.0 or higher
+
+## Installation
+
+### Using RubyGems
+
+To install the SDK using `gem`, execute the following command:
+
+    gem install onlinepayments-sdk-ruby
+
+### Using a pre-built gem
+
+1. Download the latest version of the Ruby SDK from GitHub. Choose the `onlinepayments-sdk-ruby-x.y.z.gem` file from the [releases](https://github.com/wl-online-payments-direct/sdk-ruby/releases) page, where `x.y.z` is the version number.
+2. Navigate into the folder where the gem file is downloaded to, and execute the following command:
+
+    ```
+    gem install onlinepayments-sdk-ruby-x.y.z.gem
+    ```
+3. Feel free to delete the gem file at this point, it is no longer required.
+
+### From source
+
+1. Download the latest version of the Ruby SDK from GitHub. Choose the `onlinepayments-sdk-ruby-x.y.z.zip` file from the [releases](https://github.com/wl-online-payments-direct/sdk-ruby/releases) page, where `x.y.z` is the version number.
+1. Download the latest version of the Ruby SDK from GitHub. Choose the `onlinepayments-sdk-ruby-x.y.z.zip` file from the releases page of the Github repository, where `x.y.z` is the version number.
+2. Unzip the file, navigate into the folder where the file is unzipped to, and execute the following commands:
+
+    ```
+    gem build onlinepayments-sdk-ruby.gemspec
+    gem install onlinepayments-sdk-ruby-x.y.z.gem
+    ```
+3. Feel free to delete the unzipped archive, the zip file, and the gem file at this point; they are no longer required.
+
+## Uninstalling
+
+After the Ruby SDK has been installed, it can be uninstalled using the
+following command:
+
+    gem uninstall onlinepayments-sdk-ruby
+
+The required packages can be uninstalled in the same way.
+
+## Usage
+
+After the Ruby SDK has been installed, it can be required in Ruby program as follows:
+
+    require 'onlinepayments/sdk'
+
+## Running tests
+
+There are two types of tests: unit tests and integration tests. The unit tests will work out-of-the-box; for the integration tests some configuration is required.
+First, some environment variables need to be set:
+
+* `onlinePayments_api_apiKeyId` for the API key id to use. This can be retrieved from the Configuration Center.
+* `onlinePayments_api_secretApiKey` for the secret API key to use. This can be retrieved from the Configuration Center.
+* `onlinePayments_api_merchantId` for your merchant ID.
+
+In addition, to run the proxy integration tests, the proxy URI, username and password should be set in the `spec/fixtures/resources/properties.proxy.yml` file.
+
+In order to run the unit and integration tests, some additional dependencies are required:
+
+* [rake](https://ruby.github.io/rake/) 12.3.3 or higher
+* [rspec](https://github.com/rspec/rspec) 3.5 or higher
+* [webmock](https://github.com/bblimke/webmock) 2.1 or higher
+* [sinatra](https://github.com/sinatra/sinatra) 1.4 or higher
+
+They can be installed using the following command:
+
+    gem install rake rspec webmock sinatra
+
+*Note: if rake is already installed as part of the Ruby installation, this will cause a conflict error. This can safely be ignored.*
+
+The following commands can now be executed from the root directory of the SDK folder (/) to execute the tests:
+
+* Unit tests:
+
+    ```
+    rake unit
+    ```
+
+* Integration tests:
+
+    ```
+    rake integration
+    ```
+
+* Both unit and integration tests:
+
+    ```
+    rake spec
+    ```
+
+## Generating documentation
+
+Documentation can be generated with YARD. YARD can be installed as a gem. The gems required to generate documentation are:
+
+* [rake](https://ruby.github.io/rake/) 12.3.3 or higher
+* [yard](https://github.com/lsegal/yard) 0.9.5 or higher
+
+They can be installed using the following command:
+
+    gem install rake yard
+
+*Note: if rake is already installed as part of the Ruby installation, this will cause a conflict error. This can safely be ignored.*
+
+Once YARD and rake are installed, documentation can be generated with the following command (ran from the root folder):
+
+    rake yard
+
+Documentation will be generated in the `/doc` folder. The file `/doc/index.html` is the main documentation file.

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec) do |t|  # supports automated testing using the command *rake* *spec*
+    t.rspec_opts = '--color --format documentation'
+  end
+
+  RSpec::Core::RakeTask.new(:unit) do |t|  # supports automated testing using unit tests using the command *rake* *unit*
+    t.rspec_opts = '--color --format documentation'
+    t.exclude_pattern = 'spec/integration/**'
+  end
+
+  RSpec::Core::RakeTask.new(:integration) do |t|  # supports automated testing of integration using the command *rake* *integration*
+    t.rspec_opts = '--color --format documentation'
+    t.pattern = 'spec/integration/**_spec.rb'
+  end
+
+  task :default => :spec
+rescue LoadError
+  puts '[*] error -- development dependency is not installed'
+end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new(:yard) do |t|  # supports generating documentation using the command *rake* *yard*
+      # t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+      t.options = ['--no-private']
+  end
+
+  task :doc => :yard  # alternative alias to generate documentation
+rescue LoadError
+  puts '[*] error -- development dependency is not installed'
+end

data/lib/onlinepayments/sdk/api_exception.rb

@@ -0,0 +1,42 @@
+module OnlinePayments::SDK
+
+  # Base class for many exceptions raised by the SDK.
+  # It is raised when an error response is received from the Online Payments platform.
+  # It contains data about the returned response.
+  #
+  # @attr_reader [Integer] status_code   HTTP status code of the returned response.
+  # @attr_reader [String]  response_body Message body of the returned response.
+  # @attr_reader [String]  error_id      An error id corresponding to the error that occurred, if available.
+  # @attr_reader [Array<OnlinePayments::SDK::Domain::APIError>] errors A list of errors received from the Online Payments platform;
+  #              may be empty but never _nil_
+  class ApiException < RuntimeError
+
+    # Creates a new ApiException that reports an error response from the Online Payments platform.
+    #
+    # @param status_code   (Integer) HTTP status code the response
+    # @param response_body (String) HTTP response body
+    # @param error_id      (String) error id of the error, may be _nil_
+    # @param errors        (Array<OnlinePayments::SDK::Domain::APIError>) a list of errors that occurred, may be empty
+    # @param message       (String) error message to include
+    def initialize(status_code, response_body, error_id, errors,
+                   message = 'the Online Payments platform returned an error response')
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+      @error_id = error_id
+      @errors = errors || [].freeze
+    end
+
+    attr_reader :status_code
+    attr_reader :response_body
+    attr_reader :error_id
+    attr_reader :errors
+
+    def to_s
+      str = super.to_s
+      str += "; status_code=#{@status_code}" if @status_code.positive?
+      str += "; response_body='#{@response_body}'" if @response_body&.length&.positive?
+      str.to_s
+    end
+  end
+end

data/lib/onlinepayments/sdk/api_resource.rb

@@ -0,0 +1,115 @@
+require 'onlinepayments/sdk/domain/error_response'
+
+module OnlinePayments::SDK
+
+  # Base class of all Online Payments platform API resources.
+  # Provides shared functionality to facilitate communication with the Online Payments platform.
+  #
+  # @attr_reader [OnlinePayments::SDK::Communicator] communicator Communicator instance that provides communication with the Online Payments platform.
+  # @attr_reader [String] client_meta_info JSON string containing client info specific to the current client.
+  class ApiResource
+
+    # Creates a new ApiResource.
+    #
+    # @param arg              [OnlinePayments::SDK::ApiResource, OnlinePayments::SDK::Communicator] parent class or Communicator instance.
+    #                         If a parent class is given its communicator will be used for communication.
+    # @param path_context     [Hash, nil] hash that contains substitutions for generic locations in the URL path.
+    #                         This hash will be used to instantiate a concrete URL used to access specific resources.
+    #                         For example in the URL https://payment.preprod.online-payments.com/!{version}/!{merchantId}/payments
+    #                         !{version} and !{merchantId} can be instantiated using the hash
+    #                         !{'version' => 'v2', 'merchantId' => '1'}. The final URL in this case will be
+    #                         https://payment.preprod.online-payments.com/v2/1/payments.
+    # @param client_meta_info [String, nil] JSON string containing the meta data for the client.
+    def initialize(arg, path_context = nil, client_meta_info = false)
+      if client_meta_info == false
+        raise ArgumentError, 'parent is required' unless arg
+
+        @parent = arg
+        @communicator = arg.communicator
+        @client_meta_info = arg.client_meta_info
+      else
+        raise ArgumentError, 'communicator is required' unless arg
+
+        @parent = nil
+        @communicator = arg
+        @client_meta_info = client_meta_info
+      end
+      @path_context = path_context
+    end
+
+    attr_reader :communicator
+    attr_reader :client_meta_info
+
+    protected
+
+    # @return [Array<OnlinePayments::SDK::RequestHeader>, nil] the X-GCS-ClientMetaInfo header.
+    def client_headers
+      @client_meta_info ?
+        [RequestHeader.new('X-GCS-ClientMetaInfo', @client_meta_info)] :
+        nil
+    end
+
+    def instantiate_uri(uri, path_context = nil)
+      uri = replace_all(uri, path_context) if path_context
+      uri = replace_all(uri, @path_context)
+      @parent ? @parent.instantiate_uri(uri) : uri
+    end
+
+    def create_exception(status_code, response_body, error_object, context)
+      if error_object.nil?
+        error_id = nil
+        errors = []
+      elsif error_object.is_a?(OnlinePayments::SDK::Domain::PaymentErrorResponse) && error_object.payment_result
+        return DeclinedPaymentException.new(status_code, response_body, error_object)
+      elsif error_object.is_a?(OnlinePayments::SDK::Domain::PayoutErrorResponse) && error_object.payout_result
+        return DeclinedPayoutException.new(status_code, response_body, error_object)
+      elsif error_object.is_a?(OnlinePayments::SDK::Domain::RefundErrorResponse) && error_object.refund_result
+        return DeclinedRefundException.new(status_code, response_body, error_object)
+      elsif error_object.is_a?(OnlinePayments::SDK::Domain::PaymentErrorResponse) ||
+        error_object.is_a?(OnlinePayments::SDK::Domain::PayoutErrorResponse) ||
+        error_object.is_a?(OnlinePayments::SDK::Domain::RefundErrorResponse) ||
+        error_object.is_a?(OnlinePayments::SDK::Domain::ErrorResponse)
+        error_id = error_object.error_id
+        errors = error_object.errors
+      else
+        raise ArgumentError, "unsupported error object type: #{error_object.class.name}"
+      end
+
+      case status_code
+      when 400
+        return ValidationException.new(status_code, response_body, error_id, errors)
+      when 403
+        return AuthorizationException.new(status_code, response_body, error_id, errors)
+      when 404, 410
+        return ReferenceException.new(status_code, response_body, error_id, errors)
+      when 409
+        if is_idempotence_error(errors, context)
+          idempotence_key = context.idempotence_key
+          idempotence_request_timestamp = context.idempotence_request_timestamp
+          return IdempotenceException.new(status_code, response_body, error_id,
+                                          errors, idempotence_key,
+                                          idempotence_request_timestamp)
+        else
+          return ReferenceException.new(status_code, response_body, error_id, errors)
+        end
+      when 500, 502, 503
+        return PaymentPlatformException.new(status_code, response_body, error_id, errors)
+      else
+        return ApiException.new(status_code, response_body, error_id, errors)
+      end
+    end
+
+    private
+
+    def replace_all(uri, path_context)
+      path_context&.each do |key, value|
+        uri = uri.gsub("{#{key}}", value)
+      end
+      uri
+    end
+
+    def is_idempotence_error(errors, context)
+      context&.idempotence_key && errors.length == 1 && errors[0].code == '1409'
+    end
+  end
+end

data/lib/onlinepayments/sdk/authenticator.rb

@@ -0,0 +1,16 @@
+module OnlinePayments::SDK
+
+  # Abstract class that is responsible for authenticating requests sent to the Online Payments platform.
+  class Authenticator
+
+    # Creates a signature to authenticate a request.
+    #
+    # @param http_method     [String] 'GET', 'PUT', 'POST' or 'DELETE' indicating which HTTP method will be used with the request
+    # @param resource_uri    [URI::HTTP] URI object that includes #path and #query of the URL that will be used, #query may be *nil*
+    # @param request_headers [Array<OnlinePayments::SDK::RequestHeader>] all headers used by the request
+    # @return [String] the created signature
+    def create_simple_authentication_signature(http_method, resource_uri, request_headers)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/onlinepayments/sdk/authorization_exception.rb

@@ -0,0 +1,13 @@
+module OnlinePayments::SDK
+
+  # This exception is thrown when a request sent to the Online Payments platform is not correctly authenticated.
+  # Corresponds to a HTTP status code of 403.
+  # @see ApiException#initialize
+  class AuthorizationException < ApiException
+
+    def initialize(status_code, response_body, error_id, errors,
+                   message = 'the Online Payments platform returned an authorization error response')
+      super(status_code, response_body, error_id, errors, message)
+    end
+  end
+end

data/lib/onlinepayments/sdk/call_context.rb

@@ -0,0 +1,26 @@
+module OnlinePayments::SDK
+
+  # A CallContext is used to identify requests and manage idempotent requests.
+  # A CallContext contains the following:
+  #
+  # idempotence_key::               A randomly generated key used to identify requests
+  # idempotence_request_timestamp:: If a previous request arrived with the same idempotence key,
+  #                                 this value will be set to a timestamp of that request.
+  #
+  # @attr_reader [String] idempotence_key The idempotence key used to identify this request.
+  #              If two requests share the same _idempotence_key_, they are considered to be the same request
+  #              and only the first request will be processed.
+  # @attr        [Integer] idempotence_request_timestamp If two or more requests arrive at the Online Payments platform with the same _idempotence_key_,
+  #              the _idempotence_request_timestamp_ will be set to the arrival time of the first of these requests.
+  class CallContext
+    @idempotence_request_timestamp = nil
+    @idempotence_key = nil
+
+    def initialize(idempotence_key = nil)
+      @idempotence_key = idempotence_key
+    end
+
+    attr_reader :idempotence_key
+    attr_accessor :idempotence_request_timestamp
+  end
+end

data/lib/onlinepayments/sdk/client.rb

@@ -0,0 +1,82 @@
+#
+# This class was auto-generated.
+#
+require 'onlinepayments/sdk/api_resource'
+require 'onlinepayments/sdk/data_object'
+require 'onlinepayments/sdk/logging/logging_capable'
+require 'onlinepayments/sdk/merchant/merchant_client'
+require 'base64'
+
+module OnlinePayments
+  module SDK
+    # payment platform client.
+    #
+    # This client and all its child clients are bound to one specific value for the X-GCS-ClientMetaInfo header.
+    #
+    # To get a new client with a different header value, use with_client_meta_info.
+    #
+    # Thread safe.
+    class Client < ApiResource
+      include Logging::LoggingCapable
+
+      # @return [String]
+      def self.API_VERSION
+        'v2'
+      end
+
+      # @param communicator     [OnlinePayments::SDK::Communicator]
+      # @param client_meta_info [String, nil]
+      def initialize(communicator, client_meta_info = nil)
+        super(communicator, nil, client_meta_info)
+      end
+
+      # @param client_meta_info [String, nil] JSON string containing the meta data for the client
+      # @return [OnlinePayments::SDK::Client] a Client which uses the passed meta data for the X-GCS-ClientMetaInfo header.
+      # @raise [OnlinePayments::SDK::MarshallerSyntaxException] if the given clientMetaInfo is not a valid JSON string
+      def with_client_meta_info(client_meta_info)
+        if client_meta_info
+          # Checking to see if this is valid JSON (no JSON parse exceptions)
+          @communicator.marshaller.unmarshal(client_meta_info, DataObject)
+          client_meta_info = Base64.strict_encode64(client_meta_info)
+          return @client_meta_info == client_meta_info ? self : Client.new(@communicator, client_meta_info)
+        end
+        @client_meta_info ? Client.new(@communicator) : self
+      end
+
+      # Utility method that delegates the call to this client's communicator.
+      def close_idle_connections(idle_time)
+        @communicator.close_idle_connections(idle_time)
+      end
+
+      # Utility method that delegates the call to this client's communicator.
+      def close_expired_connections
+        @communicator.close_expired_connections
+      end
+
+      # Turns on logging using the given communicator logger.
+      # @param communicator_logger [OnlinePayments::SDK::Logging::CommunicatorLogger]
+      def enable_logging(communicator_logger)
+        @communicator.enable_logging(communicator_logger)
+      end
+
+      # Turns off logging.
+      def disable_logging
+        @communicator.disable_logging
+      end
+
+      # Releases any system resources associated with this object.
+      def close
+        @communicator.close
+      end
+
+      # Resource /v2/!{merchantId}
+      # @param merchant_id [String]
+      # @return [OnlinePayments::SDK::Merchant::MerchantClient]
+      def merchant(merchant_id)
+        OnlinePayments::SDK::Merchant::MerchantClient.new(self, {
+          'merchantId'.freeze => merchant_id
+        })
+      end
+    end
+  end
+end

data/lib/onlinepayments/sdk/communication_exception.rb

@@ -0,0 +1,16 @@
+module OnlinePayments::SDK
+
+  # This exception is used when an error occurs during network communication with the Online Payments platform.
+  # A common cause is a timeout while connecting or when receiving or sending data.
+  #
+  # @attr [Exception] cause The error that is the cause of this error.
+  class CommunicationException < RuntimeError
+
+    def initialize(cause)
+      super()
+      @cause = cause
+    end
+
+    attr_accessor :cause
+  end
+end