buckaruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ca0648f0a6575163b3684b909a613114b6f7634d
+  data.tar.gz: 58d4b4baf6dbf494a39839352c24c522a415ea87
+SHA512:
+  metadata.gz: dfc7886aaa82c537c786ed16543abd0934d28529e1c40a76709699c6f4d9f3ee49b7caca09aac5c79de733b88397cfac1a29209a3f2df6960df2fb1227c5519f
+  data.tar.gz: dacded44324296a0af0c05063047d87f6764bd613ab438091995caf7abcb6d80b25a1d06235b6283da0a1701940c7f061a11ce7cd4d3395be72d10c5302ff418

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+.ruby-version
+.ruby-gemset
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rubocop.yml

@@ -0,0 +1,49 @@
+# Buckaruby RuboCop configuration
+
+AllCops:
+  TargetRubyVersion: 2.2
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Max: 8
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Max: 8
+
+Style/AccessorMethodName:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/MutableConstant:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+sudo: false
+cache: bundler
+rvm:
+  - 2.2.5
+  - 2.3.1

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Kentaa
+
+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,137 @@
+# Buckaruby
+
+[![Build Status](https://travis-ci.org/KentaaNL/buckaruby.svg?branch=master)](https://travis-ci.org/KentaaNL/buckaruby)
+
+The Buckaruby gem provides a Ruby library for communicating with the Buckaroo Payment Engine 3.0.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'buckaruby'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install buckaruby
+
+## Usage
+
+Configure Buckaruby to use it in test or production (live) mode:
+
+```ruby
+Buckaruby::Gateway.mode = :production  # defaults to :test
+```
+
+### Initialization
+
+Create the gateway and configure it using your Buckaroo website key and secret key:
+
+```ruby
+gateway = Buckaruby::Gateway.new(
+  website: "123456789",       # website key
+  secret: "abcdef1234567890"  # secret key for digital signing
+)
+```
+
+As hashing method for the digital signature, Buckaruby uses SHA-1 by default. You can change this to SHA-256 or SHA-512 by setting the parameter `hash_method` when creating the gateway:
+
+```ruby
+gateway = Buckaruby::Gateway.new(
+  website: "123456789",
+  secret: "abcdef1234567890",
+  hash_method: :sha512        # hash method for the digital signature (:sha1, :sha256 or :sha512)
+)
+```
+
+### Start transaction
+
+To start a new transaction, use the method `setup_transaction`:
+
+```ruby
+options = {
+  amount: 10,
+  payment_method: Buckaruby::PaymentMethod::IDEAL,
+  payment_issuer: Buckaruby::Ideal::ISSUERS.keys.first,
+  invoicenumber: "12345",
+  return_url: "http://www.return.url/"
+}
+
+response = gateway.setup_transaction(options)
+```
+
+On success this will return a `Buckaruby::SetupTransactionResponse`.
+
+### Recurrent transaction
+
+Recurrent transactions are supported for all credit cards, PayPal and SEPA Direct Debit.
+
+You first need to execute a normal transaction, with the parameter `recurring` set to true.
+
+```ruby
+options = {
+  amount: 10,
+  payment_method: Buckaruby::PaymentMethod::PAYPAL,
+  invoicenumber: "12345",
+  return_url: "http://www.return.url/",
+  recurring: true
+}
+
+response = gateway.setup_transaction(options)
+```
+
+The response will include a `transaction_id` which you must use to make a recurrent transaction:
+
+```ruby
+options = {
+  amount: 10,
+  payment_method: Buckaruby::PaymentMethod::PAYPAL,
+  invoicenumber: "12345",
+  transaction_id: "abcdefg"
+}
+
+response = gateway.recurrent_transaction(options)
+```
+
+On success this will return a `Buckaruby::RecurrentTransactionResponse`.
+
+### Push response
+
+Buckaroo can be configured to send push notifications for transactions. You can use the method `callback` to verify and parse the push response:
+
+```ruby
+response = gateway.callback(params)
+```
+
+On success this will return a `Buckaruby::CallbackResponse`.
+
+### Get status
+
+To query the status of any transaction, use the method `status` with either the parameter `transaction_id` or `payment_id`:
+
+```ruby
+response = gateway.status(transaction_id: 12345)
+```
+
+On success this will return a `Buckaruby::StatusResponse`.
+
+### Error handling
+
+When missing or invalid parameters are passed to any method, an `ArgumentError` will be raised.
+
+When a request to Buckaroo fails because of connection problems, a `Buckaruby::ConnectionException` will be raised.
+
+When an API call to Buckaroo results in a "Fail" returned, a `Buckaruby::ApiException` will be raised.
+
+When the signature could not be verified, a `Buckaruby::SignatureException` will be raised.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/KentaaNL/buckaruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+
+task default: [:spec, :rubocop]

data/buckaruby.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'buckaruby/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "buckaruby"
+  spec.version       = Buckaruby::VERSION
+  spec.authors       = ["Kentaa"]
+  spec.email         = ["support@kentaa.nl"]
+  spec.summary       = "Ruby library for communicating with the Buckaroo Payment Engine 3.0."
+  spec.description   = "The Buckaruby gem provides a Ruby library for communicating with the Buckaroo Payment Engine 3.0."
+  spec.homepage      = "http://www.buckaroo.nl/"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.0.0"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.5.0", ">= 3.5.0"
+end

data/lib/buckaruby/action.rb

@@ -0,0 +1,7 @@
+module Buckaruby
+  module Action
+    PAY = "Pay"
+    PAY_RECURRENT = "PayRecurrent"
+    EXTRA_INFO = "ExtraInfo"
+  end
+end

data/lib/buckaruby/currency.rb

@@ -0,0 +1,5 @@
+module Buckaruby
+  module Currency
+    EURO = "EUR"
+  end
+end

data/lib/buckaruby/exception.rb

@@ -0,0 +1,54 @@
+module Buckaruby
+  # Base class for exceptions.
+  class BuckarooException < StandardError
+  end
+
+  # Exception raised when an API call to Buckaroo results in a "Fail".
+  class ApiException < BuckarooException
+    attr_reader :params
+
+    def initialize(params = {})
+      @params = params
+
+      if status_message && status_code
+        message = "API request failed: #{status_message} (#{status_code})"
+      elsif error_message
+        message = "API request failed: #{error_message}"
+      else
+        message = "API request failed"
+      end
+
+      super(message)
+    end
+
+    def status_message
+      params[:brq_statusmessage]
+    end
+
+    def status_code
+      params[:brq_statuscode]
+    end
+
+    def error_message
+      params[:brq_apierrormessage]
+    end
+  end
+
+  # Exception raised when a request to Buckaroo fails because of connection problems.
+  class ConnectionException < BuckarooException
+    def initialize(exception)
+      message = "Error connecting to Buckaroo: #{exception.message} (#{exception.class})"
+
+      super(message)
+    end
+  end
+
+  # Exception raised when the signature could not be verified.
+  class SignatureException < BuckarooException
+    def initialize(sent_signature = "", generated_signature = "")
+      message = "Sent signature (#{sent_signature}) doesn't match generated signature (#{generated_signature})"
+
+      super(message)
+    end
+  end
+end

data/lib/buckaruby/gateway.rb

@@ -0,0 +1,204 @@
+require 'bigdecimal'
+require 'logger'
+
+module Buckaruby
+  # Implementation of the BPE 3.0 NVP Gateway.
+  class Gateway
+    class << self
+      # Buckaroo mode can be set as class setting
+      attr_accessor :mode
+    end
+
+    attr_reader :options
+
+    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)
+    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."
+      end
+
+      return Ideal::ISSUERS
+    end
+
+    # Setup a new transaction.
+    def setup_transaction(options = {})
+      @logger.debug("[setup_transaction] options=#{options.inspect}")
+
+      validate_setup_transaction_params!(options)
+
+      normalize_account_iban!(options) if options[:payment_method] == PaymentMethod::SEPA_DIRECT_DEBIT
+
+      request = build_request(:setup_transaction)
+      response = request.execute(options)
+
+      return SetupTransactionResponse.new(response, @options)
+    end
+
+    # Setup a recurrent transaction.
+    def recurrent_transaction(options = {})
+      @logger.debug("[recurrent_transaction] options=#{options.inspect}")
+
+      validate_recurrent_transaction_params!(options)
+
+      request = build_request(:recurrent_transaction)
+      response = request.execute(options)
+
+      return RecurrentTransactionResponse.new(response, @options)
+    end
+
+    # Get transaction status.
+    def status(options = {})
+      @logger.debug("[status] options=#{options.inspect}")
+
+      validate_status_params!(options)
+
+      request = build_request(:status)
+      response = request.execute(options)
+
+      return StatusResponse.new(response, @options)
+    end
+
+    # Verify the response / callback.
+    def callback(response = {})
+      if response.empty?
+        raise ArgumentError, "No callback parameters found"
+      end
+
+      return CallbackResponse.new(response, @options)
+    end
+
+    private
+
+    # Validate required parameters.
+    def validate_required_params!(params, *required)
+      required.flatten.each do |param|
+        if !params.key?(param) || params[param].to_s.empty?
+          raise ArgumentError, "Missing required parameter: #{param}."
+        end
+      end
+    end
+
+    # Validate params for setup transaction.
+    def validate_setup_transaction_params!(options)
+      required_params = [:amount, :payment_method, :invoicenumber]
+      required_params << :return_url if options[:payment_method] != PaymentMethod::SEPA_DIRECT_DEBIT
+
+      case options[:payment_method]
+      when PaymentMethod::IDEAL
+        required_params << :payment_issuer
+      when PaymentMethod::SEPA_DIRECT_DEBIT
+        required_params << [:account_iban, :account_name]
+      end
+
+      validate_required_params!(options, required_params)
+
+      validate_amount!(options)
+
+      valid_payment_methods = [
+        PaymentMethod::IDEAL, PaymentMethod::VISA, PaymentMethod::MASTER_CARD, PaymentMethod::MAESTRO,
+        PaymentMethod::SEPA_DIRECT_DEBIT, PaymentMethod::PAYPAL, PaymentMethod::BANCONTACT_MISTER_CASH
+      ]
+      validate_payment_method!(options, valid_payment_methods)
+
+      validate_payment_issuer!(options)
+    end
+
+    # Validate amount of money, must be greater than 0.
+    def validate_amount!(options)
+      money = BigDecimal.new(options[:amount].to_s)
+      if money <= 0
+        raise ArgumentError, "Invalid amount: #{options[:amount]} (must be greater than 0)"
+      end
+    end
+
+    # Validate the payment method.
+    def validate_payment_method!(options, valid)
+      unless valid.include?(options[:payment_method])
+        raise ArgumentError, "Invalid payment method: #{options[:payment_method]}"
+      end
+    end
+
+    # Validate the payment issuer when iDEAL is selected as payment method.
+    def validate_payment_issuer!(options)
+      if options[:payment_method] == PaymentMethod::IDEAL
+        unless Ideal::ISSUERS.include?(options[:payment_issuer])
+          raise ArgumentError, "Invalid payment issuer: #{options[:payment_issuer]}"
+        end
+      end
+    end
+
+    # Validate params for recurrent transaction.
+    def validate_recurrent_transaction_params!(options)
+      required_params = [:amount, :payment_method, :invoicenumber, :transaction_id]
+
+      validate_required_params!(options, required_params)
+
+      validate_amount!(options)
+
+      valid_payment_methods = [
+        PaymentMethod::VISA, PaymentMethod::MASTER_CARD, PaymentMethod::MAESTRO,
+        PaymentMethod::SEPA_DIRECT_DEBIT, PaymentMethod::PAYPAL
+      ]
+      validate_payment_method!(options, valid_payment_methods)
+    end
+
+    # Validate params for transaction status.
+    def validate_status_params!(options)
+      if !options[:transaction_id] && !options[:payment_id]
+        raise ArgumentError, "Missing parameters: transaction_id or payment_id should be present"
+      end
+    end
+
+    # Strip spaces from the IBAN.
+    def normalize_account_iban!(options)
+      iban = options[:account_iban].to_s.gsub(/\s/, "")
+
+      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
+
+    # Factory method for constructing a request.
+    def build_request(request_type)
+      case request_type
+      when :setup_transaction
+        SetupTransactionRequest.new(@options)
+      when :recurrent_transaction
+        RecurrentTransactionRequest.new(@options)
+      when :status
+        StatusRequest.new(@options)
+      end
+    end
+  end
+end

data/lib/buckaruby/iban.rb

@@ -0,0 +1,25 @@
+module Buckaruby
+  # Helper for calculating the IBAN for a given account number, bank code and country code.
+  class Iban
+    def self.calculate_iban(account_number, bank_code, country_code = "NL")
+      if account_number.nil? || account_number.to_s.empty?
+        raise ArgumentError, "Invalid account number"
+      end
+
+      if bank_code.nil? || bank_code.to_s.empty?
+        raise ArgumentError, "Invalid bank code"
+      end
+
+      if country_code.nil? || !country_code.match(/^[A-Z]{2}$/)
+        raise ArgumentError, "Invalid or unknown country code"
+      end
+
+      account_identification = bank_code + account_number.rjust(10, '0')
+      country_code_added = account_identification + country_code
+      all_numbers = country_code_added.gsub(/[A-Z]/) { |p| (p.respond_to?(:ord) ? p.ord : p[0]) - 55 } + '00'
+      verification_number = (98 - (all_numbers.to_i % 97)).to_s.rjust(2, '0')
+
+      return country_code + verification_number + account_identification
+    end
+  end
+end

data/lib/buckaruby/ideal.rb

@@ -0,0 +1,16 @@
+module Buckaruby
+  module Ideal
+    ISSUERS = {
+      "ABNANL2A" => "ABN AMRO",
+      "ASNBNL21" => "ASN Bank",
+      "BUNQNL2A" => "Bunq",
+      "INGBNL2A" => "ING",
+      "KNABNL2H" => "Knab bank",
+      "RABONL2U" => "Rabobank",
+      "RBRBNL21" => "RegioBank",
+      "SNSBNL2A" => "SNS Bank",
+      "TRIONL2U" => "Triodos Bank",
+      "FVLBNL22" => "Van Lanschot"
+    }
+  end
+end

data/lib/buckaruby/language.rb

@@ -0,0 +1,8 @@
+module Buckaruby
+  module Language
+    DUTCH = 'nl-NL'
+    ENGLISH = 'en-GB'
+    FRENCH = 'fr-FR'
+    DEUTSCH = 'de-DE'
+  end
+end

data/lib/buckaruby/operation.rb

@@ -0,0 +1,6 @@
+module Buckaruby
+  module Operation
+    TRANSACTION_REQUEST = "TransactionRequest"
+    TRANSACTION_STATUS = "TransactionStatus"
+  end
+end

data/lib/buckaruby/payment_method.rb

@@ -0,0 +1,14 @@
+module Buckaruby
+  module PaymentMethod
+    IDEAL = "ideal"
+    SEPA_DIRECT_DEBIT = "sepadirectdebit"
+    PAYPAL = "paypal"
+    BANCONTACT_MISTER_CASH = "bancontactmrcash"
+    TRANSFER = "transfer"
+
+    # Credit cards
+    VISA = "visa"
+    MASTER_CARD = "mastercard"
+    MAESTRO = "maestro"
+  end
+end