buckaruby 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bf24f7ed57a0ee1afd17a9d85d696be81c7e28f3
-  data.tar.gz: 472afa4186eb0cb9e6dda801b6fc80ea52ca0654
+SHA256:
+  metadata.gz: 4c5c39e48aa11568771e7f89251560e47ac6a9ce8f151a05e146a8281ab58483
+  data.tar.gz: 450e2c0daa5a9bb0c12a119f6dd6b3aa0bf616ba35ba2403c6d47b214246e7ca
 SHA512:
-  metadata.gz: 59deba4cfcf3006f9a20d5072619cf42550da007912cec0bf5ade166be9c9191810cf87066dcb1576c79e7d3d154e1098ba8e8d4aa1372883b1ad1fa547f8568
-  data.tar.gz: 11d4aa501936edcaff85f77e163ee88732ba1ecea6b52415e24783a9c477c6894a1b3453045ee030d32cb1b8bc1dcbd2b92b4b2fba1f6403f04a492f1d1a1a1f
+  metadata.gz: a0ab66f241e872cde63993bca6d996b3a773be5336850cd2495677cc39caf1e1c3286ff681c789d49362278b4d1afdfddecf4fb366bbabb75de384b4ffa2efc5
+  data.tar.gz: 41712687c28b2a086cedb478938b79985b50d0bd6b4aedfba21a0143f3a60a3b92fade5de73782f3a8f481184a9ec08510842a7887db045cbaad569af0a00efe

data/.rubocop.yml

@@ -1,10 +1,14 @@
 # Buckaruby RuboCop configuration
 
 AllCops:
-  TargetRubyVersion: 2.2
+  TargetRubyVersion: 2.3
   DisplayCopNames: true
   DisplayStyleGuide: true
 
+# We target 2.3, but still want to support 2.0.
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
 Metrics/AbcSize:
   Max: 30
 
@@ -24,10 +28,16 @@ Metrics/LineLength:
 Metrics/MethodLength:
   Enabled: false
 
+Metrics/ModuleLength:
+  Enabled: false
+
 Metrics/PerceivedComplexity:
   Max: 9
 
-Style/AccessorMethodName:
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
   Enabled: false
 
 Style/BlockDelimiters:
@@ -37,14 +47,20 @@ Style/BlockDelimiters:
 Style/ConditionalAssignment:
   Enabled: false
 
+Style/ExpandPathArguments:
+  Enabled: false
+
 Style/GuardClause:
   Enabled: false
 
 Style/IfUnlessModifier:
   Enabled: false
 
-Style/MutableConstant:
+Style/StringLiterals:
+  Enabled: false
+
+Style/SafeNavigation:
   Enabled: false
 
-Style/StringLiterals:
+Style/SymbolArray:
   Enabled: false

data/.travis.yml

@@ -1,7 +1,11 @@
 language: ruby
 sudo: false
 cache: bundler
+before_install:
+  - gem update --system
+  - gem install bundler
 rvm:
-  - 2.2.7
-  - 2.3.4
-  - 2.4.1
+  - 2.2.10
+  - 2.3.7
+  - 2.4.4
+  - 2.5.1

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Buckaruby changelog
 
+## 1.1.0 (2018-06-01)
+- Added payment method iDEAL processing.
+- Added Moneyou to the list of iDEAL issuers.
+- Implemented refund transaction.
+- Implemented cancel transaction.
+
 ## 1.0.2 (2017-08-25)
 
 - Recognize credit card transactions via Atos.

data/Gemfile

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in buckaruby.gemspec
 gemspec
 
-gem 'rubocop', '~> 0.47.1', group: :test
+gem 'rubocop', '~> 0.55.0', group: :test

data/README.md

@@ -49,6 +49,8 @@ gateway = Buckaruby::Gateway.new(
 )
 ```
 
+You can override the default mode with the parameter `mode`.
+
 ### Start transaction
 
 To start a new transaction, use the method `setup_transaction`:
@@ -65,7 +67,9 @@ options = {
 response = gateway.setup_transaction(options)
 ```
 
-On success this will return a `Buckaruby::SetupTransactionResponse`.
+The response includes a `status` to check if the transaction was successful and a `redirect_url` which you can use to redirect the user to when present.
+
+See `Buckaruby::SetupTransactionResponse` for more details.
 
 ### Recurrent transaction
 
@@ -83,6 +87,8 @@ options = {
 }
 
 response = gateway.setup_transaction(options)
+
+transaction = response.transaction_id  # use this for the recurrent transaction
 ```
 
 The response will include a `transaction_id` which you must use to make a recurrent transaction:
@@ -98,7 +104,51 @@ options = {
 response = gateway.recurrent_transaction(options)
 ```
 
-On success this will return a `Buckaruby::RecurrentTransactionResponse`.
+The response includes a `status` to check if the transaction was successful.
+
+See `Buckaruby::RecurrentTransactionResponse` for more details.
+
+### Refund transaction
+
+For some transactions it's possible to do a refund: Buckaroo creates a new "reverse" transaction based on the original transaction.
+
+First check if the transaction is refundable, with the parameter `transaction_id` set to the original transaction ID:
+
+```ruby
+response = gateway.refundable?(transaction_id: "abcdefg")
+```
+
+If the reponse is positive then you can refund the transaction with:
+
+```ruby
+response = gateway.refund_transaction(transaction_id: "abcdefg")
+```
+
+The response includes a `status` to check if the refund was successful.
+
+If you try to refund a transaction that's not refundable, then a `Buckaruby::NonRefundableTransactionException` will be raised.
+
+See `Buckaruby::RefundTransactionResponse` for more details.
+
+### Cancel transaction
+
+Sometimes a transaction can be cancelled, for example a SEPA Direct Debit transaction before it has been offered to the bank.
+
+You can check if the transaction is cancellable, by using the method `cancellable?` with the parameter `transaction_id`:
+
+```ruby
+response = gateway.cancellable?(transaction_id: "abcdefg")
+```
+
+If the response is positive then you can cancel the transaction with:
+
+```ruby
+response = gateway.cancel_transaction(transaction_id: "abcdefg")
+```
+
+If this does not result in an exception, then the cancel was successful.
+
+If you try to cancel a transaction that's not cancellable, then a `Buckaruby::NonCancellableTransactionException` will be raised.
 
 ### Push response
 
@@ -108,7 +158,7 @@ Buckaroo can be configured to send push notifications for transactions. You can
 response = gateway.callback(params)
 ```
 
-On success this will return a `Buckaruby::CallbackResponse`.
+See `Buckaruby::CallbackResponse` for more details.
 
 ### Get status
 
@@ -118,7 +168,7 @@ To query the status of any transaction, use the method `status` with either the
 response = gateway.status(transaction_id: 12345)
 ```
 
-On success this will return a `Buckaruby::StatusResponse`.
+See `Buckaruby::StatusResponse` for more details.
 
 ### Error handling
 
@@ -134,6 +184,10 @@ When the signature could not be verified, a `Buckaruby::SignatureException` will
 
 All Buckaruby exceptions listed here inherit from the class `Buckaruby::BuckarooException`.
 
+## Example
+
+For a complete and working example project check out [Buckaruby PoC](https://github.com/KentaaNL/buckaruby-poc).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/KentaaNL/buckaruby.

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"

data/buckaruby.gemspec

@@ -1,4 +1,4 @@
-# coding: utf-8
+# frozen_string_literal: true
 
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)

data/lib/buckaruby.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'buckaruby/support/case_insensitive_hash'
 
 require_relative 'buckaruby/action'
@@ -8,8 +10,8 @@ require_relative 'buckaruby/operation'
 require_relative 'buckaruby/payment_method'
 require_relative 'buckaruby/transaction_status'
 require_relative 'buckaruby/transaction_type'
-require_relative 'buckaruby/urls'
 
+require_relative 'buckaruby/configuration'
 require_relative 'buckaruby/exception'
 require_relative 'buckaruby/gateway'
 require_relative 'buckaruby/iban'

data/lib/buckaruby/action.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 module Buckaruby
   module Action
     PAY = "Pay"
     PAY_RECURRENT = "PayRecurrent"
+    REFUND = "Refund"
     EXTRA_INFO = "ExtraInfo"
   end
 end

data/lib/buckaruby/configuration.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Buckaruby
+  # Configuration settings for the Buckaruby Gateway.
+  class Configuration
+    TEST_URL = "https://testcheckout.buckaroo.nl/nvp/"
+    PRODUCTION_URL = "https://checkout.buckaroo.nl/nvp/"
+
+    attr_reader :website, :secret, :mode, :hash_method, :logger
+
+    def initialize(options)
+      set_website(options)
+      set_secret(options)
+      set_buckaroo_mode(options)
+      set_hash_method(options)
+      set_logger(options)
+    end
+
+    def test?
+      @mode == :test
+    end
+
+    def production?
+      @mode == :production
+    end
+
+    def api_url
+      test? ? TEST_URL : PRODUCTION_URL
+    end
+
+    private
+
+    def set_website(options)
+      @website = options[:website]
+
+      raise ArgumentError, "Missing required parameter: website" if @website.to_s.empty?
+    end
+
+    def set_secret(options)
+      @secret = options[:secret]
+
+      raise ArgumentError, "Missing required parameter: secret" if @secret.to_s.empty?
+    end
+
+    # Set Buckaroo mode from options, class setting or the default (test).
+    def set_buckaroo_mode(options)
+      @mode = options.key?(:mode) ? options[:mode] : Gateway.mode
+      @mode ||= :test
+
+      if @mode != :test && @mode != :production
+        raise ArgumentError, "Invalid Buckaroo mode provided: #{@mode} (expected :test or :production)"
+      end
+    end
+
+    # Set the hash method from options or default (SHA-1).
+    def set_hash_method(options)
+      @hash_method = (options[:hash_method] || "SHA1").downcase.to_sym
+
+      unless [:sha1, :sha256, :sha512].include?(@hash_method)
+        raise ArgumentError, "Invalid hash method provided: #{@hash_method} (expected :sha1, :sha256 or :sha512)"
+      end
+    end
+
+    # Set the logger from options, to Rails or to stdout.
+    def set_logger(options)
+      @logger   = options[:logger]
+      @logger ||= Rails.logger if defined?(Rails)
+      @logger ||= Logger.new(STDOUT)
+    end
+  end
+end

data/lib/buckaruby/currency.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
 module Buckaruby
   module Currency
     EURO = "EUR"
+    BRITISH_POUND = "GBP"
+    US_DOLLAR = "USD"
   end
 end

data/lib/buckaruby/exception.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Buckaruby
   # Base class for exceptions.
   class BuckarooException < StandardError
@@ -66,4 +68,28 @@ module Buckaruby
       super(message)
     end
   end
+
+  # Exception raised when trying to refund a non refundable transaction.
+  class NonRefundableTransactionException < BuckarooException
+    attr_reader :transaction_id
+
+    def initialize(transaction_id)
+      @transaction_id = transaction_id
+
+      message = "Not a refundable transaction: #{transaction_id}"
+      super(message)
+    end
+  end
+
+  # Exception raised when trying to cancel a non cancellable transaction.
+  class NonCancellableTransactionException < BuckarooException
+    attr_reader :transaction_id
+
+    def initialize(transaction_id)
+      @transaction_id = transaction_id
+
+      message = "Not a cancellable transaction: #{transaction_id}"
+      super(message)
+    end
+  end
 end

data/lib/buckaruby/gateway.rb

@@ -1,5 +1,6 @@
+# frozen_string_literal: true
+
 require 'bigdecimal'
-require 'logger'
 
 module Buckaruby
   # Implementation of the BPE 3.0 NVP Gateway.
@@ -9,22 +10,17 @@ module Buckaruby
       attr_accessor :mode
     end
 
-    attr_reader :options
+    attr_reader :config
 
     def initialize(options = {})
-      validate_required_params!(options, :website, :secret)
-
-      @logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
-      @options = options
-
-      set_buckaroo_mode!(@options)
-      set_hash_method!(@options)
+      @config = Configuration.new(options)
+      @logger = config.logger
     end
 
     # Get a list with payment issuers.
     def issuers(payment_method)
-      if payment_method != PaymentMethod::IDEAL
-        raise ArgumentError, "Invalid payment method, only #{PaymentMethod::IDEAL} is supported."
+      if payment_method != PaymentMethod::IDEAL && payment_method != PaymentMethod::IDEAL_PROCESSING
+        raise ArgumentError, "Invalid payment method, only iDEAL is supported."
       end
 
       Ideal::ISSUERS
@@ -50,6 +46,40 @@ module Buckaruby
       execute_request(:recurrent_transaction, options)
     end
 
+    # Checks if a transaction is refundable.
+    def refundable?(options = {})
+      @logger.debug("[refundable?] options=#{options.inspect}")
+
+      validate_required_params!(options, :transaction_id)
+
+      response = execute_request(:refund_info, options)
+      response.refundable?
+    end
+
+    # Refund a transaction.
+    def refund_transaction(options = {})
+      @logger.debug("[refund_transaction] options=#{options.inspect}")
+
+      validate_refund_transaction_params!(options)
+
+      response = execute_request(:refund_info, options)
+      unless response.refundable?
+        raise NonRefundableTransactionException, options[:transaction_id]
+      end
+
+      # Pick maximum refundable amount if amount is not supplied.
+      options[:amount] = response.maximum_amount unless options[:amount]
+
+      # Fill required parameters with data from refund info request.
+      options.merge!(
+        payment_method: response.payment_method,
+        invoicenumber: response.invoicenumber,
+        currency: response.currency
+      )
+
+      execute_request(:refund_transaction, options)
+    end
+
     # Get transaction status.
     def status(options = {})
       @logger.debug("[status] options=#{options.inspect}")
@@ -59,13 +89,37 @@ module Buckaruby
       execute_request(:status, options)
     end
 
+    # Checks if a transaction is cancellable.
+    def cancellable?(options = {})
+      @logger.debug("[cancellable?] options=#{options.inspect}")
+
+      validate_required_params!(options, :transaction_id)
+
+      response = execute_request(:status, options)
+      response.cancellable?
+    end
+
+    # Cancel a transaction.
+    def cancel_transaction(options = {})
+      @logger.debug("[cancel_transaction] options=#{options.inspect}")
+
+      validate_required_params!(options, :transaction_id)
+
+      response = execute_request(:status, options)
+      unless response.cancellable?
+        raise NonCancellableTransactionException, options[:transaction_id]
+      end
+
+      execute_request(:cancel, options)
+    end
+
     # Verify the response / callback.
     def callback(response = {})
       if response.empty?
         raise ArgumentError, "No callback parameters found"
       end
 
-      CallbackResponse.new(response, @options)
+      CallbackResponse.new(response, config)
     end
 
     private
@@ -85,7 +139,7 @@ module Buckaruby
       required_params << :return_url if options[:payment_method] != PaymentMethod::SEPA_DIRECT_DEBIT
 
       case options[:payment_method]
-      when PaymentMethod::IDEAL
+      when PaymentMethod::IDEAL, PaymentMethod::IDEAL_PROCESSING
         required_params << :payment_issuer
       when PaymentMethod::SEPA_DIRECT_DEBIT
         required_params << [:account_iban, :account_name]
@@ -96,7 +150,7 @@ module Buckaruby
       validate_amount!(options)
 
       valid_payment_methods = [
-        PaymentMethod::IDEAL, PaymentMethod::VISA, PaymentMethod::MASTER_CARD, PaymentMethod::MAESTRO,
+        PaymentMethod::IDEAL, PaymentMethod::IDEAL_PROCESSING, PaymentMethod::VISA, PaymentMethod::MASTER_CARD, PaymentMethod::MAESTRO,
         PaymentMethod::SEPA_DIRECT_DEBIT, PaymentMethod::PAYPAL, PaymentMethod::BANCONTACT_MISTER_CASH
       ]
       validate_payment_method!(options, valid_payment_methods)
@@ -106,7 +160,7 @@ module Buckaruby
 
     # Validate amount of money, must be greater than 0.
     def validate_amount!(options)
-      money = BigDecimal.new(options[:amount].to_s)
+      money = BigDecimal(options[:amount].to_s)
       if money <= 0
         raise ArgumentError, "Invalid amount: #{options[:amount]} (must be greater than 0)"
       end
@@ -121,7 +175,7 @@ module Buckaruby
 
     # Validate the payment issuer when iDEAL is selected as payment method.
     def validate_payment_issuer!(options)
-      if options[:payment_method] == PaymentMethod::IDEAL
+      if options[:payment_method] == PaymentMethod::IDEAL || options[:payment_method] == PaymentMethod::IDEAL_PROCESSING
         unless Ideal::ISSUERS.include?(options[:payment_issuer])
           raise ArgumentError, "Invalid payment issuer: #{options[:payment_issuer]}"
         end
@@ -143,6 +197,17 @@ module Buckaruby
       validate_payment_method!(options, valid_payment_methods)
     end
 
+    # Validate params for refund transaction.
+    def validate_refund_transaction_params!(options)
+      unless options[:transaction_id]
+        raise ArgumentError, "Missing required parameter: transaction_id"
+      end
+
+      if options[:amount]
+        validate_amount!(options)
+      end
+    end
+
     # Validate params for transaction status.
     def validate_status_params!(options)
       if !options[:transaction_id] && !options[:payment_id]
@@ -157,29 +222,6 @@ module Buckaruby
       options[:account_iban] = iban
     end
 
-    # Set Buckaroo mode from options, class setting or the default (test).
-    def set_buckaroo_mode!(options)
-      mode = options.key?(:mode) ? options[:mode] : Gateway.mode
-      mode ||= :test
-
-      if mode != :test && mode != :production
-        raise ArgumentError, "Invalid Buckaroo mode provided: #{mode} (expected :test or :production)"
-      end
-
-      options[:mode] = mode
-    end
-
-    # Set the hash method from options or default (SHA-1).
-    def set_hash_method!(options)
-      hash_method = (options[:hash_method] || "SHA1").downcase.to_sym
-
-      unless [:sha1, :sha256, :sha512].include?(hash_method)
-        raise ArgumentError, "Invalid hash method provided: #{options[:hash_method]} (expected :sha1, :sha256 or :sha512)"
-      end
-
-      options[:hash_method] = hash_method
-    end
-
     # Build and execute a request.
     def execute_request(request_type, options)
       request = build_request(request_type)
@@ -187,11 +229,17 @@ module Buckaruby
 
       case request_type
       when :setup_transaction
-        SetupTransactionResponse.new(response, @options)
+        SetupTransactionResponse.new(response, config)
       when :recurrent_transaction
-        RecurrentTransactionResponse.new(response, @options)
+        RecurrentTransactionResponse.new(response, config)
+      when :refund_transaction
+        RefundTransactionResponse.new(response, config)
+      when :refund_info
+        RefundInfoResponse.new(response, config)
       when :status
-        StatusResponse.new(response, @options)
+        StatusResponse.new(response, config)
+      when :cancel
+        CancelResponse.new(response, config)
       end
     end
 
@@ -199,11 +247,17 @@ module Buckaruby
     def build_request(request_type)
       case request_type
       when :setup_transaction
-        SetupTransactionRequest.new(@options)
+        SetupTransactionRequest.new(config)
       when :recurrent_transaction
-        RecurrentTransactionRequest.new(@options)
+        RecurrentTransactionRequest.new(config)
+      when :refund_transaction
+        RefundTransactionRequest.new(config)
+      when :refund_info
+        RefundInfoRequest.new(config)
       when :status
-        StatusRequest.new(@options)
+        StatusRequest.new(config)
+      when :cancel
+        CancelRequest.new(config)
       end
     end
   end