comgate_ruby 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7d8a030a101f774292a7f3214a1d3338238afa11fbc9c98e348db15259d6fde
+  data.tar.gz: 6253ba9e4d7e3a1737f491b3efccbd82bd85afc1c802c97c4939e3114dcc88ed
+SHA512:
+  metadata.gz: 47713672ee0beed059c9e26b90bbaebded0cdc29db78f08e20c9e406678c2ffd59562a439f81c8b5a2a9d0716ab7b637af9dcc86068a9010df0e0350c4984ff9
+  data.tar.gz: 9d2a09ac2489566918c5f131764636c34113bfb92cc57be659b72d349bbd78c7ebbec0fb7c2d5108e28261a4f728dc6ef4ca312dc684f331a12981ad7c6cf988

data/.rubocop.yml

@@ -0,0 +1,26 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 25

data/.tool-versions

@@ -0,0 +1,3 @@
+ruby 3.1.2
+
+

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [0.5.0] - 2023-04-20
+
+- Initial release
+
+

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in comgate_ruby.gemspec
+gemspec
+
+gem "minitest", "~> 5.0"
+gem "pry-byebug"
+gem "rake", "~> 13.0"
+gem "rspec-expectations"
+gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -0,0 +1,60 @@
+PATH
+  remote: .
+  specs:
+    comgate_ruby (0.5.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    diff-lcs (1.5.0)
+    json (2.6.3)
+    method_source (1.0.0)
+    minitest (5.18.0)
+    parallel (1.22.1)
+    parser (3.2.0.0)
+      ast (~> 2.4.1)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.2)
+    rexml (3.2.5)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.44.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.4.2)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  comgate_ruby!
+  minitest (~> 5.0)
+  pry-byebug
+  rake (~> 13.0)
+  rspec-expectations
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.3.22

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Sinfin
+
+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/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Petr Mlčoch
+
+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,185 @@
+# comgate_ruby
+Client for Comgate payment gateway
+
+## API docs for Comgate
+https://help.comgate.cz/docs/api-protokol
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add comgate_ruby
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install comgate_ruby
+
+## Usage
+### 1) set gateway object
+  As singleton on app init or for each transaction:
+  ```ruby
+    gateway = Commgate::Gateway.new(merchant_gateway_id: ":comgate_id",
+                                    test_calls: false,
+                                    secret: ":comgate_secret")
+  ```
+
+### 2) prepare endpoint
+ Comgate sends POST requests to your app about transactions updates. The URL of it needs to be setup in Comgate Client portal. At endpoint, just call `gateway.process_payment_callback(params)`, which will return
+    `{state: :paid, transaction_id: ":transID"}` (at least). See bullets 4) and 5) in Single payment process bellow.
+### 3) call appropriate method
+ (see bellow)
+
+## Usecases
+### Single payment process
+1) Start transaction by `gateway.start_transaction(payment_data)`. Response is
+      ```ruby
+        #<Comgate::Response:0x00007f56800295a8
+          @array=nil,
+          @errors=nil,
+          @hash={:code=>0, :message=>"OK", :transaction_id=>"AB12-CD34-EF56", :redirect_to=>"https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56"},
+          @http_code=200,
+          @params_conversion_hash=
+            { .... }
+          @redirect_to="https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56">
+      ```
+   Important part is `response.hash` :
+      ```ruby
+         {
+           code: 0,
+           message: "OK",
+           transaction_id: "AB12-CD34-EF56"
+           redirect_to: "https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56",
+         }
+      ```
+2) Redirect user to `response.redirect_to` page (=> display Comgate form).
+3) Client will (not) pay.
+4) Comgate will send request to your defined endpoint about status change of transaction. Call `gateway.process_state_change(payload)`, which will return
+  `{state: :paid, transaction_id: ":transID"}`(and maybe some more informations).
+5) Now is Your time to handle payment (or other state like `cancelled`, `authorized`).
+
+### Recurring payments
+1) Use `gateway.start_recurring_transaction(payment_data)` and store `transaction_id`.
+2) Create following payments `gateway.repeat_recurring_transaction(payment_data: new_payment_data.merge({transaction_id: ":transID"}) }})`. No redirection here. Price can change in each payment.
+3) Handle status change like bullets 4) and 5) in single payment
+
+### Preauthorized payments
+1) Use `gateway.start_preauthorized_transaction(payment_data)` and store `transaction_id`.
+2a) Confirm payment by `gateway.confirm_preauthorized_transaction(payment_data.merge({transaction_id: ":transID"}))` (price cannot exceed preauthorized amount)
+2b) Cancel payment by `gateway.cancel_preauthorized_transaction(transaction_id: ":transID")`
+3) Handle status change like bullets 4) and 5) in single payment
+
+### Verification payments
+1) Use `gateway.start_verification_transaction(payment_data)` and store `transaction_id`.
+2) If payment is succesfull, bank will refund payment immediatelly.
+3) Then you can create (repeat) payments like reccuring payments.
+
+### Refund payment
+1) Call `gateway.refund_transaction(payment_data.merge({transaction_id: ":transID"}))` (refunded value cannot exceed paid amount)
+2) Handle status change like bullets 4) and 5) in single payment
+
+### Cancel payment
+1) Call `gateway.cancel_transaction(transaction_id: ":transID")`
+2) Handle status change like bullets 4) and 5) in single payment
+
+### Check payment state (ad-hoc)
+0) The endpoint must be always implemented, this is just additional way to check payment state
+1) Call `gateway.check_state(transaction_id: ":transID")`. It will return `{state: :paid, transaction_id: ":transID"}` and some more infos.
+2) Handle status change like bullet 5) in single payment
+
+### Get payment methods allowed to merchant
+1) Call `gateway.allowed_payment_methods(params)`. It will return array of allowed payment methods in `response.array`.
+   ```ruby
+    [
+      { id: "BANK_CZ_CS_P",
+        name: "Česká spořitelna - PLATBA 24",
+        description: "On-line platba pro majitele účtu u České spořitelny.",
+        logo_url: "https://payments.comgate.cz/assets/images/logos/BANK_CZ_CS_P.png" },
+      { id: "BANK_CZ_FB_P",
+        name: "Fio banka - PayMyway",
+        description: "On-line platba pro majitele účtu u Fio banky.",
+        logo_url: "https://payments.comgate.cz/assets/images/logos/BANK_CZ_FB.png" }
+    ]
+   ```
+
+### Get list of transfers for date
+1) Call `gateway.transfers_from(date)`. Array of transfers will be returned in `response.array`.
+    ```ruby
+      [
+        { transfer_id: 1234567,
+          transfer_date: date,
+          account_counter_party: "0/0000",
+          account_outgoing: "123456789/0000",
+          variable_symbol: "12345678"}
+      ]
+    ```
+
+## Parameters
+Structure of parameters is unchanged across most of methods, but you can leave out unused keys. You will get error if You  do not pass required key.
+See `test/comgate/test_gateway.rb` for examples.
+Also returned hash have consistent structure (very similar to input params)
+Maximal mixed version looks like:
+```ruby
+  {
+    code: 0, # output
+    message: "OK", # output
+    transfer_id: "1234-abcd-45678", # input/output
+    test: true, # input (handle as test call)/ output (created by test call)
+    state: :paid, # output (:pending, :paid, :cancelled, :authorized)
+    merchant: {
+      gateway_id: "some_id_from_comgate", # output (input is set at gateway init)
+      target_shop_account: "12345678/1234", # input (change against default)/ output
+    },
+    payment: {
+        amount_in_cents: 12_900, # input/output
+        currency: "CZK", # input/output
+        label: "Payment for 2 straws", # input/output
+        reference_id: "our eshop order #1 reference", # input/output
+        method: "CARD_CZ_CSOB_2", # input (selected method; or use "ALL") / output
+        product_name: "product name ABC", # input/output
+        fee: nil, # output ( if automatic deduction of the payment fee is set at Comgate)
+        variable_symbol: 739_689_656, # output (so I acctually do not know where it came from)
+        apple_pay_payload: "raw apple pay payload", # input
+        dynamic_expiration: false, # input (see  https://help.comgate.cz/v1/docs/expirace-plateb )
+        expiration_time: "10h", # input ( use "m" or  "h" or "d", but only one of them; allowed rage "30m".."7d")
+    },
+    payer: {
+        email: "payer1@gmail.com", # input/output
+        phone: "+420778899", # input/output
+        account_number: "account_num", # output
+        account_name: "payer account name" # output
+    },
+    options: {
+      country_code: "DE", # input (can restrict allowed  payment methods)
+      language_code: "sk" # input
+    },
+    headers: {} # not actually used now
+  }
+```
+## Response
+ Response returned from `gateway` call is `Comgate::Response` instance.
+ You can check redirection `response.redirect? ? response.redirect_to : nil`.
+ Most of the time, the response shoul be hash-like, stored in `response.hash`. But for lists there will be array in `response.array`.
+ If there are errors from API call , they will be in `response.errors`. But note, that gateway will raise them and not return `Comgate::Response` instance.
+ And you can also check `result.http_code` (which is surprisingly 200 from API errors)
+
+## Errors
+Connection errors or API error responses are raised as RuntimeError with message like ` "{:api=>[\"[Error #1309] incorrect amount\"]}"`.
+Error Number and text can be found in `lib/comgate/response.rb`.
+This may be refactored in future.
+
+## One more thing
+This gem extends `Hash` with methods `deep_symbolize_keys` and `deep_merge` (if needed).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/comgate_ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/comgate_ruby.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/comgate/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "comgate_ruby"
+  spec.version = Comgate::VERSION
+  spec.authors = ["Petr Mlčoch"]
+  spec.email = ["foton@centrum.cz"]
+
+  spec.summary = "Client for Comgate payment gateway"
+  spec.description = "Write a longer description or delete this line."
+  spec.homepage = "https://github.com/sinfin/comgate_ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/sinfin/comgate_ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/sinfin/comgate_ruby/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/lib/base_service.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class BaseService
+  attr_reader :result, :errors
+
+  def self.call(*args, **keyword_args)
+    if args.empty?
+      new(**keyword_args).call
+    elsif keyword_args.empty?
+      new(*args).call
+    else
+      new(*args, **keyword_args).call
+    end
+  end
+
+  def call
+    build_result
+    self # always returnning service itself, to get to `errors`, `result`
+  end
+
+  def initialize(*_args, **_keyword_args)
+    @result = nil
+    @errors = {}
+  end
+
+  def success?
+    errors.empty?
+  end
+
+  def failure?
+    !success?
+  end
+  alias failed? failure?
+end

data/lib/comgate/api_caller.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "net/http"
+require "json"
+
+module Comgate
+  class ApiCaller < BaseService
+    KNOWN_CONNECTION_ERRORS = [
+      Timeout::Error,
+      Errno::EINVAL,
+      Errno::ECONNRESET,
+      EOFError,
+      SocketError,
+      Net::ReadTimeout,
+      Net::HTTPBadResponse,
+      Net::HTTPHeaderSyntaxError,
+      Net::ProtocolError
+    ].freeze
+
+    attr_reader :payload, :url
+
+    def initialize(url:, payload:, test_call: false)
+      super()
+      @url = url
+      @payload = payload
+      @payload.merge!(test: "true") if test_call
+    end
+
+    def build_result
+      call_api
+      process_response
+    end
+
+    private
+
+    attr_accessor :response
+
+    def call_api
+      self.response = https_conn.request(request)
+    rescue *KNOWN_CONNECTION_ERRORS => e
+      handle_connection_error(e)
+    end
+
+    def process_response
+      return unless errors.empty?
+
+      api_log(:debug, "Comgate API RESPONSE: #{response} with body:\n#{response.body}")
+
+      @result = {
+        http_code: response.code.to_i,
+        redirect_to: find_redirect_to,
+        response_body: decoded_response_body
+      }
+
+      record_api_error
+    end
+
+    def https_conn
+      @https_conn ||= Net::HTTP.start(service_uri.host, service_uri.port, connection_options)
+    end
+
+    def request
+      request = Net::HTTP::Post.new service_uri.request_uri, headers
+      request.body = encoded_request_body
+
+      debug_msg = "Commgate API REQUEST: #{request} to #{service_uri} " \
+                  "with headers: #{headers}\n and body:\n#{request.body}"
+      api_log(:debug, debug_msg)
+
+      request
+    end
+
+    def service_uri
+      @service_uri ||= URI.parse(url)
+    end
+
+    def headers
+      { "Content-Type" => "application/x-www-form-urlencoded" }
+    end
+
+    def connection_options
+      {
+        use_ssl: true,
+        verify_mode: OpenSSL::SSL::VERIFY_PEER,
+        keep_alive_timeout: 30
+        # ciphers: secure_and_available_ciphers,
+        # cert: OpenSSL::X509::Certificate.new(File.read(configuration.certificate_path)),
+        # cert_password: configuration.certificate_password,
+        # key: OpenSSL::PKey::RSA.new(File.read(configuration.private_key_path), configuration.private_key_password),
+        # cert_store: post_signum_ca_store
+      }
+    end
+
+    def find_redirect_to
+      case response&.code&.to_i
+      when 302
+        response_location
+      when 200
+        decoded_response_body.is_a?(Hash) ? decoded_response_body["redirect"] : nil
+      end
+    end
+
+    def response_redirect?
+      !redirect_to.nil?
+    end
+
+    def record_api_error
+      return unless api_error?
+
+      errors[:api] = ["[Error ##{result[:response_body]["error"]}] #{result[:response_body]["message"]}"]
+      @result[:errors] = { api: { code: result[:response_body]["error"].to_i,
+                                  message: result[:response_body]["message"] } }
+    end
+
+    def api_error?
+      return false unless decoded_response_body.is_a?(Hash)
+
+      decoded_response_body["error"].to_i.positive?
+    end
+
+    def handle_connection_error(error)
+      errors[:connection] = ["#{error.class} > #{service_uri} - #{error}"]
+
+      @result = {
+        http_code: 500,
+        errors: { connection: [{ code: 500, message: "#{error.class} > #{service_uri} - #{error}" }] }
+      }
+    end
+
+    def encoded_request_body
+      URI.encode_www_form(payload)
+    end
+
+    def decoded_response_body
+      @decoded_response_body ||= case response_content_type
+                                 when :url_encoded
+                                   URI.decode_www_form(response.body).to_h
+                                 when :json
+                                   JSON.parse(response.body)
+                                 end
+    end
+
+    def api_log(level, message)
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger.send(forced_log_level(level), message)
+      else
+        puts("#{Time.now} [#{forced_log_level(level)}] #{message}")
+      end
+    end
+
+    def forced_log_level(original_level)
+      levels = { debug: 0, info: 1, error: 2 }
+      minimal_level = :error
+      levels[original_level] > levels[minimal_level] ? original_level : minimal_level
+    end
+
+    def response_location
+      path_or_url = response["location"]
+      return nil if path_or_url == ""
+
+      response_uri = URI.parse(path_or_url)
+      response_uri = URI.join(url, response_uri) if response_uri.relative?
+      response_uri.to_s
+    end
+
+    def response_content_type
+      rct = response["content-type"]
+      return nil if rct.nil?
+
+      if rct.include?("json")
+        :json
+      elsif rct.include?("form-urlencoded")
+        :url_encoded
+      else
+        raise "Uncaptured content type: '#{rct}'"
+      end
+    end
+  end
+end

data/lib/comgate/gateway.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Comgate
+  class Gateway
+    BASE_URL = "https://payments.comgate.cz/v1.0"
+    DATA_CONVERSION_HASH = {
+      curr: %i[payment currency],
+      email: %i[payer email],
+      label: %i[payment label],
+      method: %i[payment method],
+      price: %i[payment amount_in_cents],
+      amount: %i[payment amount_in_cents],
+      refId: %i[payment reference_id],
+      account: %i[merchant target_shop_account],
+      applePayPayload: %i[payment apple_pay_payload],
+      country: %i[options country_code],
+      dynamicExpiration: %i[payment dynamic_expiration],
+      embedded: %i[options embedded_iframe],
+      expirationTime: %i[payment expiration_time],
+      lang: %i[options language_code],
+      name: %i[payment product_name],
+      phone: %i[payer phone],
+      preauth: %i[payment preauthorization],
+      verification: %i[payment verification_payment],
+
+      # responses
+      transId: %i[transaction_id],
+      transferId: %i[transfer_id],
+      code: %i[code],
+      message: %i[message],
+      payerId: %i[payer id],
+      payerName: %i[payer account_name],
+      payer_name: %i[payer account_name],
+      payerAcc: %i[payer account_number],
+      payer_acc: %i[payer account_number],
+      fee: %i[payment fee],
+      methods: %i[methods],
+      vs: %i[payment variable_symbol],
+      variableSymbol: %i[variable_symbol],
+      transferDate: %i[transfer_date],
+      accountCounterparty: %i[account_counterparty],
+      accountOutgoing: %i[account_outgoing],
+      status: %i[state],
+      test: %i[test],
+      merchant: %i[merchant gateway_id],
+      secret: %i[secret],
+      redirect: %i[redirect_to]
+    }.freeze
+
+    attr_reader :options
+
+    def initialize(options)
+      @options = options
+      return unless options[:merchant_gateway_id].nil? || options[:secret].nil? || options[:test_calls].nil?
+
+      raise ArgumentError "options have to include :merchant_gateway_id, :secret and :test_calls"
+    end
+
+    def test_calls_used?
+      options[:test_calls] == true
+    end
+
+    def start_transaction(payment_data)
+      make_call(url: "#{BASE_URL}/create",
+                payload: single_payment_payload(payment_data),
+                test_call: test_call?(payment_data[:test]))
+    end
+
+    def start_recurring_transaction(payment_data)
+      make_call(url: "#{BASE_URL}/create",
+                payload: single_payment_payload(payment_data).merge(initRecurring: true),
+                test_call: test_call?(payment_data[:test]))
+    end
+
+    def repeat_recurring_transaction(payment_data)
+      transaction_id = payment_data.delete(:transaction_id)
+      make_call(url: "#{BASE_URL}/recurring",
+                payload: single_payment_payload(payment_data).merge(initRecurringId: transaction_id),
+                test_call: test_call?(payment_data[:test]))
+    end
+
+    def start_verification_transaction(payment_data)
+      make_call(url: "#{BASE_URL}/create",
+                payload: single_payment_payload(payment_data).merge(verification: true),
+                test_call: test_call?(payment_data[:test]))
+    end
+
+    def start_preauthorized_transaction(payment_data)
+      make_call(url: "#{BASE_URL}/create",
+                payload: single_payment_payload(payment_data).merge(preauth: true),
+                test_call: test_call?(payment_data[:test]))
+    end
+
+    def confirm_preauthorized_transaction(payment_data)
+      params = convert_data_to_comgate_params(%i[transId amount], payment_data, required: true)
+
+      make_call(url: "#{BASE_URL}/capturePreauth",
+                payload: gateway_params.merge(params),
+                test_call: false)
+    end
+
+    def cancel_preauthorized_transaction(transaction_id:)
+      make_call(url: "#{BASE_URL}/cancelPreauth",
+                payload: gateway_params.merge(transId: transaction_id),
+                test_call: false)
+    end
+
+    def refund_transaction(payment_data)
+      refund_params = convert_data_to_comgate_params(%i[transId amount], payment_data, required: true)
+      refund_params.merge!(convert_data_to_comgate_params(%i[curr refId], payment_data, required: false))
+
+      make_call(url: "#{BASE_URL}/refund",
+                payload: gateway_params.merge(refund_params),
+                test_call: test_call?(payment_data[:test]))
+    end
+
+    def cancel_transaction(transaction_id:)
+      make_call(url: "#{BASE_URL}/cancel",
+                payload: gateway_params.merge(transId: transaction_id),
+                test_call: false)
+    end
+
+    def check_state(transaction_id:)
+      make_call(url: "#{BASE_URL}/status",
+                payload: gateway_params.merge(transId: transaction_id),
+                test_call: false)
+    end
+
+    def process_payment_callback(comgate_params)
+      Comgate::Response.new({ response_body: comgate_params }, DATA_CONVERSION_HASH)
+    end
+
+    def allowed_payment_methods(payment_data)
+      ph = gateway_params.merge(convert_data_to_comgate_params(%i[curr lang country], payment_data, required: false))
+
+      response = make_call(url: "#{BASE_URL}/methods",
+                           payload: ph,
+                           test_call: false,
+                           conversion_hash: { name: [:name] })
+      response.array = response.hash[:methods]
+      response.hash = nil
+      response
+    end
+
+    def transfers_from(date_or_time)
+      date_str = date_or_time.strftime("%Y-%m-%d")
+
+      make_call(url: "#{BASE_URL}/transferList",
+                payload: gateway_params.merge({ date: date_str }),
+                test_call: false)
+    end
+
+    private
+
+    attr_reader :payment_data
+
+    def make_call(url:, payload:, test_call:, conversion_hash: DATA_CONVERSION_HASH)
+      raise "There are errors in pre-api-call phase: #{payload[:errors]}" unless payload[:errors].nil?
+
+      srv = Comgate::ApiCaller.call(url: url, payload: payload, test_call: test_call)
+      if srv.success?
+        Comgate::Response.new(srv.result, conversion_hash)
+      else
+        handle_failure_from(srv.errors)
+      end
+    end
+
+    def test_call?(test_from_data = nil)
+      test_from_data.nil? ? test_calls_used? : (test_from_data == true)
+    end
+
+    def handle_failure_from(errors)
+      raise errors.to_s
+    end
+
+    def single_payment_payload(payment_data)
+      required_keys = %i[curr email label method price refId]
+      optional_keys = %i[account applePayPayload country dynamicExpiration embedded expirationTime lang name phone
+                         preauth verification]
+
+      ph = gateway_params.merge({ prepareOnly: true })
+      ph.merge!(convert_data_to_comgate_params(required_keys, payment_data, required: true))
+      ph.merge!(convert_data_to_comgate_params(optional_keys, payment_data, required: false))
+      ph[:applePayPayload] = Base64.encode64(ph[:applePayPayload]) unless ph[:applePayPayload].nil?
+      ph
+    end
+
+    def gateway_params
+      { merchant: options[:merchant_gateway_id],
+        secret: options[:secret] }
+    end
+
+    def convert_data_to_comgate_params(comgate_keys, data, required:)
+      h = {}
+      comgate_keys.each do |comg_key|
+        dig_keys = DATA_CONVERSION_HASH[comg_key.to_sym]
+        raise "comgate key '#{comg_key}' is not setup in conversion_hash" if dig_keys.nil?
+
+        value = data.dig(*dig_keys)
+        if value.nil?
+          if required
+            h[:errors] = [] if h[:errors].nil?
+            h[:errors] << "Missing value for `params#{dig_keys.collect { |k| "[:#{k}]" }.join}` in `#{data}`"
+          end
+        else
+          h[comg_key] = value
+        end
+      end
+      h
+    end
+  end
+end

data/lib/comgate/response.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Comgate
+  class Response
+    RESPONSE_CODES = {
+      0 => "OK",
+      1100 => "unknown error",
+      1102 => "the specified language is not supported",
+      1103 => "method incorrectly specified",
+      1104 => "unable to load payment",
+      1107 => "payment price is not supported",
+      1200 => "database error",
+      1301 => "unknown e-shop",
+      1303 => "the link or language is missing",
+      1304 => "invalid category",
+      1305 => "product description is missing",
+      1306 => "select the correct method",
+      1308 => "the selected payment method is not allowed",
+      1309 => "incorrect amount",
+      1310 => "unknown currency",
+      1311 => "invalid e-shop bank account identifier",
+      1316 => "e-shop does not allow recurring payments",
+      1317 => "invalid method - does not support recurring payments",
+      1318 => "initial payment not found",
+      1319 => "can not create a payment, a problem on the part of the bank",
+      1399 => "unexpected result from database",
+      1400 => "wrong query",
+      1401 => "the refunded payment is in the CANCELED state",
+      # or 1401 =>"Transaction FVN0-NS40-NA5B has not been authorized, current status: READY"
+      1402 => "refund amount higher than allowed",
+      1500 => "unexpected error"
+    }.freeze
+
+    attr_accessor :http_code, :redirect_to, :hash, :array, :errors
+    attr_reader :params_conversion_hash
+
+    def initialize(caller_result, params_conversion_hash = {})
+      @params_conversion_hash = params_conversion_hash
+
+      @http_code = caller_result[:http_code].to_i
+      @errors = fill_error_messages(caller_result[:errors])
+      @redirect_to = caller_result[:redirect_to]
+
+      converted_body = convert_comgate_params_to_data(caller_result[:response_body])
+
+      case converted_body
+      when Hash
+        @hash = converted_body
+        @array = nil
+      when Array
+        @array = converted_body
+        @hash = nil
+      end
+    end
+
+    def redirect?
+      !redirect_to.nil?
+    end
+
+    def error?
+      !errors.nil?
+    end
+
+    private
+
+    def convert_comgate_params_to_data(comgate_params)
+      h = transform_comgate_params(comgate_params)
+      return h unless h.is_a?(Hash)
+
+      cleanup_hash(h)
+    end
+
+    def cleanup_hash(rsp_hash) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      rsp_hash.delete(:secret)
+
+      rsp_hash[:state] = rsp_hash[:state].to_s.downcase.to_sym unless rsp_hash[:state].nil?
+      unless rsp_hash.dig(:payment, :variable_symbol).nil?
+        rsp_hash[:payment][:variable_symbol] = rsp_hash.dig(:payment, :variable_symbol).to_i
+      end
+      unless rsp_hash.dig(:payment, :amount_in_cents).nil?
+        rsp_hash[:payment][:amount_in_cents] = rsp_hash.dig(:payment, :amount_in_cents).to_i
+      end
+      rsp_hash[:variable_symbol] = rsp_hash[:variable_symbol].to_i unless rsp_hash[:variable_symbol].nil?
+      if (fee = rsp_hash.dig(:payment, :fee))
+        rsp_hash[:payment][:fee] = fee == "unknown" ? nil : fee.to_f
+      end
+
+      rsp_hash[:code] = rsp_hash[:code].to_i if rsp_hash[:code]
+      rsp_hash[:error] = rsp_hash[:error].to_i if rsp_hash[:error]
+
+      rsp_hash[:message] = RESPONSE_CODES[rsp_hash[:code]] if rsp_hash[:message].to_s == "" && rsp_hash[:code]
+      rsp_hash
+    end
+
+    def transform_comgate_params(comgate_params)
+      case comgate_params
+      when Hash
+        transform_comgate_hash(comgate_params)
+      when Array
+        comgate_params.collect { |item| transform_comgate_params(item) }
+      when "true"
+        true
+      when "false"
+        false
+      else
+        comgate_params
+      end
+    end
+
+    def transform_comgate_hash(comgate_params)
+      h = {}
+      comgate_params.each_pair do |k, v|
+        build_keys = params_conversion_hash[k.to_sym]&.dup
+        transformed_value = transform_comgate_params(v)
+
+        if build_keys.nil? # not covered in params_conversion_hash
+          h[k.to_sym] = transformed_value
+        else
+          last_key = build_keys.delete(build_keys.last)
+          hash_at_level = h
+          build_keys.each do |bk|
+            hash_at_level[bk] = {} if hash_at_level[bk].nil?
+            hash_at_level = hash_at_level[bk]
+          end
+          hash_at_level[last_key] = transformed_value
+        end
+      end
+      h
+    end
+
+    def fill_error_messages(caller_errors)
+      return nil if caller_errors.nil?
+      return caller_errors if caller_errors[:api].nil?
+
+      caller_errors[:api] = caller_errors[:api].collect do |err_h|
+        err_h[:message] = RESPONSE_CODES[err_h[:code]] if err_h[:message].to_s == ""
+        err_h
+      end
+      caller_errors
+    end
+  end
+end

data/lib/comgate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Comgate
+  VERSION = "0.5.0"
+end

data/lib/comgate_ruby.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "hash_enhancements"
+require_relative "base_service"
+require_relative "comgate/version"
+require_relative "comgate/response"
+require_relative "comgate/api_caller"
+require_relative "comgate/gateway"

data/lib/hash_enhancements.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+unless {}.respond_to?(:deep_merge)
+  class Hash
+    def deep_merge(other_hash)
+      result = dup
+      other_hash.each do |key, value|
+        existing_value = result[key]
+        result[key] = if existing_value.is_a?(Hash)
+                        existing_value.deep_merge(value)
+                      else
+                        value
+                      end
+      end
+      result
+    end
+  end
+end
+
+unless {}.respond_to?(:deep_symbolize_keys)
+  class Hash
+    def deep_symbolize_keys
+      result = {}
+      each_pair do |k, v|
+        result[k.to_sym] = case v
+                           when Hash
+                             v.deep_symbolize_keys
+                           when Array
+                             v.collect { |item| item.is_a?(Hash) ? item.deep_symbolize_keys : item }
+                           else
+                             v
+                           end
+      end
+      result
+    end
+  end
+end

data/sig/comgate_ruby.rbs

@@ -0,0 +1,4 @@
+module ComgateRuby
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: comgate_ruby
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Petr Mlčoch
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-04-20 00:00:00.000000000 Z
+dependencies: []
+description: Write a longer description or delete this line.
+email:
+- foton@centrum.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".tool-versions"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- comgate_ruby.gemspec
+- lib/base_service.rb
+- lib/comgate/api_caller.rb
+- lib/comgate/gateway.rb
+- lib/comgate/response.rb
+- lib/comgate/version.rb
+- lib/comgate_ruby.rb
+- lib/hash_enhancements.rb
+- sig/comgate_ruby.rbs
+homepage: https://github.com/sinfin/comgate_ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/sinfin/comgate_ruby
+  source_code_uri: https://github.com/sinfin/comgate_ruby
+  changelog_uri: https://github.com/sinfin/comgate_ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Client for Comgate payment gateway
+test_files: []