barzahlen 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d22d4228515d62a086a459066ed7d35a5fa596fb
+  data.tar.gz: add4528a9bb87a690c17609c81831f384bc9a06c
+SHA512:
+  metadata.gz: bf406f3231504cd7c6047a5df34e3f4253d1a79e4a730323cfd92718f54b7380a9fb8cc90624f37d3d28c2d74a3a727a12a347978a968e1401597caefae24854
+  data.tar.gz: 5f9ca948df4a0fdb4c032eaf11271b61456b0c89008d7bce56b2bac805b49ebb10f9f7ecf3bf33897bdbfecd3bb9e44a96ddc50a46ff61b4f1c81f80d87b57a3

data/Gemfile

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

data/README.md

@@ -0,0 +1,207 @@
+# Barzahlen Ruby-SDK
+
+The official Ruby-SDK for accessing the Barzalen Payment Service.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'barzahlen-sdk'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install barzahlen-sdk
+
+## Usage
+
+```Ruby
+require 'barzahlen/api/online'
+```
+
+### Configuration
+
+The configuration is a hash where :shop_id, :payment_key and :notification_key are required. For
+using the sandbox you can set the :host to 'api-sandbox.barzahlen.de'.
+
+```Ruby
+Barzahlen::Api::Online.config = {:shop_id => 'xxx',
+                                 :payment_key => 'xxx',
+                                 :notification_key => 'xxx',
+                                 :host => 'api-sandbox.barzahlen.de',}
+```
+
+The credentials, which are necessary to handle payments with Barzahlen, can be received at
+https://partner.barzahlen.de. After a successful registration a shop ID is assigned to you as
+well as a payment and a notification key. Furthermore you can set your callback URL which is used
+to send updates on payment and refund transactions.
+
+### Send requests
+
+After you set the config you can create the transaction-api object with the method
+Barzahlen::Api::Online.new_transaction_api.
+
+If there are any errors, a RuntimeError is thrown.
+
+#### Create transactions
+
+```Ruby
+transaction = {
+    :customer_email => 'barzahlen@example.com',
+    :amount => '13.37',
+    :currency => 'EUR',
+    :order_id => '123', #optional
+    :customer_street_nr => 'Wallstr. 14a',
+    :customer_zipcode => '10179',
+    :customer_city => 'Berlin',
+    :customer_country => 'DE',
+    :customer_custom_var_0 => 'customer_custom_var_0', #optional
+    :customer_custom_var_1 => 'customer_custom_var_1', #optional
+    :customer_custom_var_2 => 'customer_custom_var_2', #optional
+    :language => 'de',
+}
+api_transaction = Barzahlen::Api::Online.new_transaction_api
+response = api_transaction.create transaction
+# Response contains :transaction_id, :payment_slip_link, :expiration_notice, :infotext1,
+# :infotext2, :result, :hash
+```
+
+#### Update order-id of a transaction
+
+```Ruby
+transaction_id = 123
+order_id = 456
+api_transaction = Barzahlen::Api::Online.new_transaction_api
+response = api_transaction.update_order_id transaction_id, order_id
+# Response contains :transaction_id, :result, :hash
+```
+
+#### Resend E-Mail for a transaction
+
+```Ruby
+transaction_id = 123
+language = 'de'
+api_transaction = Barzahlen::Api::Online.new_transaction_api
+response = api_transaction.resend_email transaction_id, language
+# Response contains :transaction_id, :result, :hash
+```
+
+#### Cancel a transaction
+
+```Ruby
+transaction_id = 123
+language = 'de'
+api_transaction = Barzahlen::Api::Online.new_transaction_api
+response = api_transaction.cancel transaction_id, language
+# Response contains :transaction_id, :result, :hash
+```
+
+#### Create a refund for a transaction
+
+```Ruby
+transaction_id = 123
+amount = '1.23'
+currency = 'EUR'
+language = 'de'
+api_transaction = Barzahlen::Api::Online.new_transaction_api
+response = api_transaction.refund transaction_id, amount, currency, language
+# Response contains :origin_transaction_id, :refund_transaction_id, :result, :hash
+```
+
+### Handle notifications
+
+After you set the config you can create the notification-handler object with the method
+Barzahlen::Api::Online.new_notification_handler.
+
+#### Handle a transaction-paid notification
+
+```Ruby
+notification_handler = Barzahlen::Api::Online.new_notification_handler
+notification = notification_handler.validate_request(request_parameters)
+# Notification contains :state, :transaction_id, :shop_id, :customer_email, :amount, :currency,
+# :notification_key and, if set while request, :order_id, :custom_var_0, :custom_var_1, :custom_var_2
+if notification[:state] == Barzahlen::Api::Online::NotificationHandler::TRANSACTION_PAID
+  # ...
+end
+```
+
+#### Handle a transaction-expired notification
+
+```Ruby
+notification_handler = Barzahlen::Api::Online.new_notification_handler
+notification = notification_handler.validate_request(request_parameters)
+# Notification contains :state, :transaction_id, :shop_id, :customer_email, :amount, :currency,
+# :notification_key and, if set while request, :order_id, :custom_var_0, :custom_var_1, :custom_var_2
+if notification[:state] == Barzahlen::Api::Online::NotificationHandler::TRANSACTION_EXPIRED
+  # ...
+end
+```
+
+#### Handle a refund-completed notification
+
+```Ruby
+notification_handler = Barzahlen::Api::Online.new_notification_handler
+notification = notification_handler.validate_request(request_parameters)
+# Notification contains :state, :refund_transaction_id, :origin_transaction_id, :shop_id,
+#:customer_email, :amount, :currency, :notification_key and, if set while request, :origin_order_id,
+#:custom_var_0, :custom_var_1, :custom_var_2
+if notification[:state] == Barzahlen::Api::Online::NotificationHandler::REFUND_COMPLETED
+  # ...
+end
+```
+
+#### Handle a refund-expired notification
+
+```Ruby
+notification_handler = Barzahlen::Api::Online.new_notification_handler
+notification = notification_handler.validate_request(request_parameters)
+# Notification contains :state, :refund_transaction_id, :origin_transaction_id, :shop_id,
+#:customer_email, :amount, :currency, :notification_key and, if set while request, :origin_order_id,
+#:custom_var_0, :custom_var_1, :custom_var_2
+if notification[:state] == Barzahlen::Api::Online::NotificationHandler::REFUND_EXPIRED
+  # ...
+end
+```
+
+### Logging
+
+If you want to log all requests to the API and the raw responses, you have to implement your own
+http_client. As you can see this is not as hard is sounds.
+
+```Ruby
+class LoggingClient < Barzahlen::Api::Online::Http
+  def request(url, parameters)
+    response = super
+
+    puts url
+    puts parameters
+    puts response
+
+    response
+  end
+end
+
+config = {:shop_id => '13446',
+          :payment_key => '1c7439cda8256d9ead6602087462f0e478e3f2f4',
+          :notification_key => '390447f4a799dcae93d62bcd9567c1795188154b',
+          :host => 'api-sandbox.barzahlen.de',}
+
+http = LoggingClient.new
+Barzahlen::Api::Online.api = Barzahlen::Api::Online::Api.new http, config
+
+transaction_id = 123
+order_id = 456
+api_transaction = Barzahlen::Api::Online.new_transaction_api
+response = api_transaction.update_order_id transaction_id, order_id
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/barzahlen/Barzahlen-Ruby/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,3 @@
+# coding: utf-8
+
+require 'bundler/gem_tasks'

data/bin/test.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby_executable_hooks
+# coding: utf-8
+
+$:.unshift '/home/mathiashertlein/Development/sdk/ruby_sdk/lib'
+require 'barzahlen/api/online'
+
+class LoggingClient < Barzahlen::Api::Online::Http
+  def request(url, parameters)
+    response = super
+
+    puts url
+    puts parameters
+    puts response
+
+    response
+  end
+end
+
+config = {:shop_id => '13446',
+          :payment_key => '1c7439cda8256d9ead6602087462f0e478e3f2f4',
+          :notification_key => '390447f4a799dcae93d62bcd9567c1795188154b',
+          :host => 'api-sandbox.barzahlen.de',}
+
+http = LoggingClient.new
+Barzahlen::Api::Online.api = Barzahlen::Api::Online::Api.new http, config
+
+transaction_id = 123
+order_id = 456
+Barzahlen::Api::Online.new_transaction_api
+response = api_transaction.update_order_id transaction_id, order_id

data/lib/barzahlen/api/online/api.rb

@@ -0,0 +1,67 @@
+# coding: utf-8
+
+require 'openssl'
+require 'net/http'
+
+require 'barzahlen/api/online/hash_builder'
+require 'barzahlen/api/online/response_parser'
+
+module Barzahlen
+  module Api
+    module Online
+
+      # Is responsible for assemble requests and send them via https to the Barzahlen API. It can
+      # send requests or just build and return the hash.
+      class Api
+        def initialize(http, config)
+          @http = http
+          @config = config
+        end
+
+        # Assembles and sends Request to the Barzahlen API, and returns the parsed response
+        # path is the url path.
+        # key_name is the name of the config field, that contains the secret key.
+        # parameters_order is the order of the parameters, in which they are concatenated for
+        # hash building.
+        # parameters contains the parameters of the request.
+        def request(path, key_name, parameters_order, parameters)
+          request_url = build_url path
+          request_parameters = build_parameters key_name, parameters_order, parameters
+
+          response = @http.request request_url, request_parameters
+          parsed_response = ResponseParser.parse response.body
+
+          if response.code != '200'
+            raise RuntimeError, 'Barzahlen-API returned http-status: ' + response.code.to_s + ',' +
+                                'error-message: ' + parsed_response[:error_message] + ',' +
+                                'error-code: ' + parsed_response[:result]
+          end
+
+          parsed_response
+        end
+
+        # Calculates hash from passed parameters.
+        #
+        # key_name is the name of the config field, that contains the secret key.
+        # parameters_order is the order of the parameters, in which they are concatenated.
+        # parameters contains the parameters of the request.
+        def build_hash(key_name, parameters_order, parameters)
+          request_parameters = parameters.merge :shop_id => @config[:shop_id]
+
+          hash_builder = HashBuilder.new parameters_order, key_name
+          hash_builder.build_hash @config[key_name], request_parameters
+        end
+
+        private
+          def build_url(path)
+            URI('https://' + @config[:host] + '/' + path)
+          end
+
+          def build_parameters(key_name, parameters_order, parameters)
+            hash = build_hash key_name, parameters_order, parameters
+            parameters.merge :shop_id => @config[:shop_id], :hash => hash
+          end
+        end
+    end
+  end
+end

data/lib/barzahlen/api/online/hash_builder.rb

@@ -0,0 +1,43 @@
+# coding: utf-8
+
+require 'digest/sha2'
+
+module Barzahlen
+  module Api
+    module Online
+
+      # Creates hashes from a set of parameters with th following algorithm:
+      # SHA512(param1;param2;param3;key)
+      class HashBuilder
+        def initialize(parameters_order, key_parameter_name)
+          @parameters_order = parameters_order
+          @key_parameter_name = key_parameter_name
+        end
+
+        # Calculates hash from passed parameters and key
+        def build_hash(key, parameters)
+          parameters_string = build_parameters_string key, parameters
+          Digest::SHA512.hexdigest parameters_string
+        end
+
+        private
+          def build_parameters_string(key, parameters)
+            parameters_string = ''
+
+            @parameters_order.each_with_index do |parameter_name, index|
+              if parameter_name == @key_parameter_name
+                parameter_value = key.to_s
+              else
+                parameter_value = parameters[parameter_name].to_s
+              end
+
+              parameters_string += parameter_value.to_s
+              parameters_string += ';' unless index == @parameters_order.size - 1
+            end
+
+            parameters_string
+          end
+      end
+    end
+  end
+end

data/lib/barzahlen/api/online/http.rb

@@ -0,0 +1,31 @@
+# coding: utf-8
+
+require 'openssl'
+require 'net/http'
+
+require 'barzahlen/api/online/hash_builder'
+require 'barzahlen/api/online/response_parser'
+
+module Barzahlen
+  module Api
+    module Online
+
+      # A wrapper class for Net::HTTP
+      # If you want to use your own http client, you must implement the request method and let it
+      # return an HTTPResponse compatible object
+      class Http
+        # sends a request with specified parameters to url, and returns an HTTPResponse object
+        def request(url, parameters)
+          http_client = Net::HTTP.new url.host, 443
+          http_client.use_ssl = true
+          http_client.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+          request = Net::HTTP::Post.new url.to_s
+          request.set_form_data parameters
+
+          http_client.request request
+        end
+      end
+    end
+  end
+end

data/lib/barzahlen/api/online/notification_handler.rb

@@ -0,0 +1,50 @@
+# coding: utf-8
+
+module Barzahlen
+  module Api
+    module Online
+
+      # Checks requests from Barzahlen-API
+      class NotificationHandler
+        TRANSACTION_PAID = 'paid'
+        TRANSACTION_EXPIRED = 'expired'
+        REFUND_COMPLETED = 'refund_completed'
+        REFUND_EXPIRED = 'refund_expired'
+
+        def initialize(api)
+          @api = api
+        end
+
+        # validates request and return the parameters
+        def validate_request(request_parameters)
+          parameters_order = case request_parameters[:state]
+            when TRANSACTION_PAID then [:state, :transaction_id, :shop_id, :customer_email,
+                                        :amount, :currency, :order_id, :custom_var_0,
+                                        :custom_var_1, :custom_var_2, :notification_key]
+            when TRANSACTION_EXPIRED then [:state, :transaction_id, :shop_id, :customer_email,
+                                           :amount, :currency, :order_id, :custom_var_0,
+                                           :custom_var_1, :custom_var_2, :notification_key]
+            when REFUND_COMPLETED then [:state, :refund_transaction_id, :origin_transaction_id,
+                                        :shop_id, :customer_email, :amount, :currency,
+                                        :origin_order_id, :custom_var_0, :custom_var_1,
+                                        :custom_var_2, :notification_key]
+            when REFUND_EXPIRED then [:state, :refund_transaction_id, :origin_transaction_id,
+                                      :shop_id, :customer_email, :amount, :currency,
+                                      :origin_order_id, :custom_var_0, :custom_var_1,
+                                      :custom_var_2, :notification_key]
+            else raise RuntimeError, "Unknown state '#{request_parameters[:state]}'"
+          end
+
+          expected_hash = @api.build_hash(:notification_key, parameters_order, request_parameters)
+          if request_parameters[:hash] != expected_hash
+            raise RuntimeError, 'Expected hash does not equal passed hash.' +
+                'Passed: ' + request_parameters[:hash] + ', ' +
+                'Expected: ' + expected_hash
+          end
+
+          request_parameters
+        end
+      end
+    end
+  end
+end

data/lib/barzahlen/api/online/response_parser.rb

@@ -0,0 +1,26 @@
+# coding: utf-8
+
+require 'rexml/document'
+
+module Barzahlen
+  module Api
+    module Online
+
+      # Parses Barzahlen-API response
+      class ResponseParser
+
+        # Parses xml and returns hash
+        def self.parse(response_body)
+          response_parsed = {}
+
+          doc = REXML::Document.new response_body
+          doc.elements.each('/response/*') do |element|
+            response_parsed[element.name.gsub(/\-/, '_').to_sym] = element.text
+          end
+
+          response_parsed
+        end
+      end
+    end
+  end
+end

data/lib/barzahlen/api/online/transaction.rb

@@ -0,0 +1,57 @@
+# coding: utf-8
+
+module Barzahlen
+  module Api
+    module Online
+
+      # Manipulates transactions via Barzahlen-API
+      class Transaction
+        def initialize(api)
+          @api = api
+        end
+
+        # create a transaction
+        # necessary fields of the transaction are:
+        #    :customer_email, :amount, :currency, :language, :order_id,
+        #    :customer_street_nr, :customer_zipcode, :customer_city, :customer_country
+        # optional are:
+        #    :custom_var_0, :custom_var_1, :custom_var_2
+        def create(transaction)
+          parameters_order = [:shop_id, :customer_email, :amount, :currency, :language, :order_id, :customer_street_nr,
+                              :customer_zipcode, :customer_city, :customer_country, :custom_var_0, :custom_var_1,
+                              :custom_var_2, :payment_key]
+          @api.request('v1/transactions/create', :payment_key, parameters_order, transaction)
+        end
+
+        # update order-id of a transaction
+        def update_order_id(transaction_id, order_id)
+          parameters_order = [:shop_id, :transaction_id, :order_id, :payment_key]
+          @api.request('v1/transactions/update', :payment_key, parameters_order,
+                       {:transaction_id => transaction_id, :order_id => order_id})
+        end
+
+        # resend email for a transaction
+        def resend_email(transaction_id, language)
+          parameters_order = [:shop_id, :transaction_id, :language, :payment_key]
+          @api.request('v1/transactions/resend_email', :payment_key, parameters_order,
+                       {:transaction_id => transaction_id, :language => language})
+        end
+
+        # cancels a transaction
+        def cancel(transaction_id, language)
+          parameters_order = [:shop_id, :transaction_id, :language, :payment_key]
+          @api.request('v1/transactions/cancel', :payment_key, parameters_order,
+                       {:transaction_id => transaction_id, :language => language})
+        end
+
+        # create a refund for a transaction
+        def refund(transaction_id, amount, currency, language)
+          parameters_order = [:shop_id, :transaction_id, :amount, :currency, :language, :payment_key]
+          @api.request('v1/transactions/refund', :payment_key, parameters_order,
+                       {:transaction_id => transaction_id, :amount => amount,
+                        :currency => currency, :language => language})
+        end
+      end
+    end
+  end
+end

data/lib/barzahlen/api/online/version.rb

@@ -0,0 +1,9 @@
+# coding: utf-8
+
+module Barzahlen
+  module Api
+    module Online
+      VERSION = '1.0.0'
+    end
+  end
+end

data/lib/barzahlen/api/online.rb

@@ -0,0 +1,58 @@
+# coding: utf-8
+
+require 'net/http'
+require 'barzahlen/api/online/http'
+require 'barzahlen/api/online/api'
+
+module Barzahlen
+  module Api
+    module Online
+
+      # Is responsible for initializing objects to access the Barzahlen-API and check
+      # notifications. For using it, you must set a config, in seldom cases an api object.
+      #
+      # For using the sandbox mode, you must pass the host api.barzahlen.de in the config.
+      #
+      # = Examples
+      # Barzahlen::Api::Online.config = {
+      #     :shop_id => 'your shop id',
+      #     :payment_key => 'your payment key',
+      #     :notification_key => 'your notification key',
+      # }
+      # api_transaction = Barzahlen::Api::Online.new_transaction_api
+      class << self
+        HOST = 'api.barzahlen.de'
+
+        attr_writer :config
+        attr_writer :api
+
+        # Returns an object that represents the Barzahlen-API and all it's methods.
+        def new_transaction_api
+          autoload :Transaction, 'barzahlen/api/online/transaction'
+
+          initialize_api
+          Barzahlen::Api::Online::Transaction.new @api
+        end
+
+        # Returns an object that validates notification requests, which came from  Barzahlen
+        def new_notification_handler
+          autoload :NotificationHandler, 'barzahlen/api/online/notification_handler'
+
+          initialize_api
+          Barzahlen::Api::Online::NotificationHandler.new @api
+        end
+
+        private
+          def initialize_api
+            raise ArgumentError, 'You must set a config or api' if @config == nil && @api == nil
+            @config[:host] = HOST unless @config.include? :host
+
+            if @api == nil && @config != nil
+              http = Barzahlen::Api::Online::Http.new
+              @api = Barzahlen::Api::Online::Api.new http, @config
+            end
+          end
+      end
+    end
+  end
+end

data/lib/ruby_sdk/version.rb

@@ -0,0 +1,3 @@
+module RubySdk
+  VERSION = "0.0.1"
+end

data/lib/ruby_sdk.rb

@@ -0,0 +1,5 @@
+require "ruby_sdk/version"
+
+module RubySdk
+  # Your code goes here...
+end