docdata 0.0.1 → 0.0.2

data/lib/docdata/docdata_error.rb

@@ -0,0 +1,8 @@
+class DocdataError < StandardError
+  attr_reader :object
+  
+
+  def initialize(object)
+    @object = object
+  end
+end

data/lib/docdata/engine.rb

@@ -0,0 +1,13 @@
+module Docdata
+  #
+  # Simpel extend on the +Rails::Engine+ to add support for a new config section within
+  # the environment configs
+  #
+  # @example default
+  #   # /config/environments/development.rb
+  #   config.ideal_mollie.partner_id = 123456
+  #
+  class Engine < Rails::Engine
+    config.docdata = Docdata
+  end
+end

data/lib/docdata/ideal.rb

@@ -0,0 +1,40 @@
+module Docdata
+  #
+  # This class bundles all the needed logic and methods for IDEAL specific stuff.
+  #
+  class Ideal
+
+    #
+    # List of supported banks.
+    #
+    # @visibility public
+    #
+    # @example
+    #   Docdata.banks
+    #
+    # For the lack of an available list of banks by Docdata,
+    # this gem uses the list provided by competitor Mollie.
+    # 
+    # @return [Array<Docdata::Ideal>] list of supported +Bank+'s.
+    def self.banks
+      begin
+        @source ||= open('https://secure.mollie.nl/xml/ideal?a=banklist')
+      rescue 
+        # in case the mollie API isn't available
+        # use the cached version (august 2014) of the XML file
+        @source = open("#{File.dirname(__FILE__)}/xml/bank-list.xml")
+      end
+      @response ||= Nokogiri::XML(@source)
+      @list = []
+      @response.xpath("//bank").each do |b|
+        bank = Docdata::Bank.new(
+          id: b.xpath("bank_id").first.content,
+          name: b.xpath("bank_name").first.content
+        )
+        @list << bank
+      end
+      return @list
+    end
+
+  end
+end

data/lib/docdata/line_item.rb

@@ -0,0 +1,99 @@
+module Docdata
+  
+
+  # Creates a validator
+  class LineItemValidator
+    include Veto.validator
+
+    validates :name, presence: true
+    validates :quantity, presence: true, integer: true
+    validates :price_per_unit, presence: true, integer: true
+    validates :description, presence: true
+    validates :code, presence: true
+  end
+
+
+  #
+  # Object representing a "LineItem"
+  #
+  # @example
+  #   LineItem.new({
+  #     :name => "Ham and Eggs by dr. Seuss",
+  #     :code => "EAN312313235",
+  #     :quantity => 1,
+  #     :description => "The famous childrens book",
+  #     :image => "http://blogs.slj.com/afuse8production/files/2012/06/GreenEggsHam1.jpg",
+  #     :price_per_unit => 1299,
+  #     :vat_rate => 17.5,
+  #     :vat_included => true
+  #   })
+  #  @note Warning: do not use this part of the gem, for it will break. Be warned!
+  class LineItem
+    attr_accessor :errors
+    attr_accessor :name
+    attr_accessor :code
+    attr_accessor :quantity
+    attr_accessor :unit_of_measure
+    attr_accessor :description
+    attr_accessor :image
+    attr_accessor :price_per_unit
+    attr_accessor :vat_rate
+    attr_accessor :vat_included
+
+    #
+    # Initializer to transform a +Hash+ into an LineItem object
+    #
+    # @param [Hash] args
+    def initialize(args=nil)
+      @unit_of_measure = "PCS"
+      @vat_rate        = 0
+      @vat_included    = true
+      return if args.nil?
+      args.each do |k,v|
+        instance_variable_set("@#{k}", v) unless v.nil?
+      end
+    end
+
+    # @return [Boolean] true/false, depending if this instanciated object is valid
+    def valid?
+      validator = LineItemValidator.new
+      validator.valid?(self)
+    end
+
+    # @return [String] the string that contains all the errors for this line_item
+    def error_message
+      "One of your line_items is invalid. Error messages: #{errors.full_messages.join(', ')}"
+    end
+
+    # @return [Integer] total price of this line item
+    def total_price
+      price_per_unit * quantity
+    end
+
+    def gross_amount
+      if vat_included
+        total_price
+      else
+        total_price + vat
+      end
+    end
+
+    def nett_amount
+      if vat_included
+        total_price - vat
+      else
+        total_vat
+      end
+    end
+
+    # @return [Integer] the total amount of VAT (in cents) that is applicable for this line item,
+    # based on the vat_rate, quantity and price_per_unit
+    def vat
+      if vat_included
+        ((gross_amount.to_f * "1.#{vat_rate.to_s.gsub('.','')}".to_f) - gross_amount) * -1
+      else
+        ((nett_amount.to_f * "1.#{vat_rate.to_s.gsub('.','')}".to_f) - nett_amount)
+      end
+    end
+  end
+end

data/lib/docdata/payment.rb

@@ -0,0 +1,196 @@
+module Docdata
+
+  # Creates a validator
+  class PaymentValidator
+    include Veto.validator
+    validates :amount, presence: true, integer: true
+    validates :profile, presence: true
+    validates :currency, presence: true, format: /[A-Z]{3}/
+    validates :order_reference, presence: true
+  end
+
+
+
+  #
+  # Object representing a "WSDL" object with attributes provided by Docdata
+  #
+  # @example
+  #   Payment.new({
+  #     :amount => 2500,
+  #     :currency => "EUR",
+  #     :order_reference => "TJ123"
+  #     :profile => "MyProfile"
+  #     :shopper => @shopper
+  #   })
+  # 
+  # @return [Array] Errors
+  # @param :amount [Integer] The total price in cents
+  # @param :currency [String] ISO currency code (USD, EUR, GBP, etc.)
+  # @param :order_reference [String] A unique order reference
+  # @param :profile [String] The DocData payment profile (e.g. 'MyProfile')
+  # @param :description [String] Description for this payment
+  # @param :receipt_text [String] A receipt text
+  # @param :shopper [Docdata::Shopper] A shopper object (instance of Docdata::Shopper)
+  # @param :bank_id [String] (optional) in case you want to redirect the consumer
+  # directly to the bank page (iDeal), you can set the bank id ('0031' for ABN AMRO for example.)
+  # @param :prefered_payment_method [String] (optional) set a prefered payment method.
+  # any of: [IDEAL, AMAX, VISA, etc.]
+  # @param :line_items [Array] (optional) Array of objects of type Docdata::LineItem
+  # @param :default_act [Boolean] (optional) Should the redirect URL contain a default_act=true parameter?
+  # 
+  class Payment
+    attr_accessor :errors
+    attr_accessor :amount
+    @@amount = "?"
+    attr_accessor :description
+    attr_accessor :receipt_text
+    attr_accessor :currency
+    attr_accessor :order_reference
+    attr_accessor :profile
+    attr_accessor :shopper
+    attr_accessor :bank_id
+    attr_accessor :prefered_payment_method
+    attr_accessor :line_items
+    attr_accessor :key
+    attr_accessor :default_act
+
+
+
+    #
+    # Initializer to transform a +Hash+ into an Payment object
+    #
+    # @param [Hash] args
+    def initialize(args=nil)
+      @line_items = []
+      return if args.nil?
+      args.each do |k,v|
+        instance_variable_set("@#{k}", v) unless v.nil?
+      end
+    end
+
+
+    # @return [Boolean] true/false, depending if this instanciated object is valid
+    def valid?
+      validator = PaymentValidator.new
+      validator.valid?(self)
+    end
+
+    # 
+    # This is the most importent method. It uses all the attributes
+    # and performs a `create` action on Docdata Payments SOAP API. 
+    # @return [Docdata::Response] response object with `key`, `message` and `success?` methods
+    # 
+    def create
+      # if there are any line items, they should all be valid.
+      validate_line_items
+
+      # puts
+
+      # make the SOAP API call
+      response        = Docdata.client.call(:create, xml: xml)
+      response_object = Docdata::Response.parse(:create, response)
+      if response_object.success?
+        self.key = response_object.key
+      end
+      return response_object
+    end
+
+    # @return [String] the xml to send in the SOAP API
+    def xml
+      xml_file        = "#{File.dirname(__FILE__)}/xml/create.xml.erb"
+      template        = File.read(xml_file)      
+      namespace       = OpenStruct.new(payment: self, shopper: shopper)
+      xml             = ERB.new(template).result(namespace.instance_eval { binding })
+    end
+
+    # Initialize a Payment object with the key set
+    def self.find(api_key)
+      p = self.new(key: api_key)
+      if p.status.success
+        return p
+      else
+        raise DocdataError.new(p), p.status.message
+      end
+    end
+
+    # 
+    # This is one of the other native SOAP API methods.
+    # @return [Docdata::Response]
+    def status
+      # read the xml template
+      xml_file        = "#{File.dirname(__FILE__)}/xml/status.xml.erb"
+      template        = File.read(xml_file)      
+      namespace       = OpenStruct.new(payment: self)
+      xml             = ERB.new(template).result(namespace.instance_eval { binding })
+
+      # puts xml
+
+      response        = Docdata.client.call(:status, xml: xml)
+      response_object = Docdata::Response.parse(:status, response)
+
+      return response_object # Docdata::Response
+    end
+
+    # @return [String] The URI where the consumer can be redirected to in order to pay
+    def redirect_url
+      url = {}
+      
+      base_url = Docdata.return_url
+      if Docdata.test_mode
+        redirect_base_url = 'https://test.docdatapayments.com/ps/menu'
+      else
+        redirect_base_url = 'https://secure.docdatapayments.com/ps/menu'
+      end
+      url[:command]             = "show_payment_cluster"
+      url[:payment_cluster_key] = key
+      url[:merchant_name]       = Docdata.username
+      # only include return URL if present
+      if base_url.present?
+        url[:return_url_success]  = "#{base_url}/success?key=#{url[:payment_cluster_key]}"
+        url[:return_url_pending]  = "#{base_url}/pending?key=#{url[:payment_cluster_key]}"
+        url[:return_url_canceled] = "#{base_url}/canceled?key=#{url[:payment_cluster_key]}"
+        url[:return_url_error]    = "#{base_url}/error?key=#{url[:payment_cluster_key]}"
+      end
+      url[:client_language]      = shopper.language_code
+      if default_act
+        url[:default_act]     = true
+      end
+      if bank_id.present?
+        url[:ideal_issuer_id] = bank_id
+        url[:default_pm]      = "IDEAL"
+      end
+      params = URI.encode_www_form(url)
+      uri = "#{redirect_base_url}?#{params}"
+    end
+
+
+    private
+
+    # In case there are any line_items, validate them all and
+    # raise an error for the first invalid LineItem
+    def validate_line_items
+      if @line_items.any?
+        for line_item in @line_items
+          if line_item.valid?
+            # do nothing, this line_item seems okay
+          else
+            raise DocdataError.new(line_item), line_item.error_message
+          end
+        end
+      end
+    end
+
+    # @return [Hash] list of VAT-rates and there respective totals
+    def vat_rates
+      rates = {}
+      for item in @line_items
+        rates["vat_#{item.vat_rate.to_s}"] ||= {}
+        rates["vat_#{item.vat_rate.to_s}"][:rate] ||= item.vat_rate
+        rates["vat_#{item.vat_rate.to_s}"][:total] ||= 0
+        rates["vat_#{item.vat_rate.to_s}"][:total] += item.vat
+      end
+      return rates
+    end
+
+  end
+end

data/lib/docdata/response.rb

@@ -0,0 +1,173 @@
+module Docdata
+
+  #
+  # Object representing a "response" with attributes provided by Docdata
+  #
+  # @example
+  #   :create_success=>{
+  #     :success=>"Operation successful.", 
+  #     :key=>"A7B623A3A7DB5949316F82049450C3F3"
+  #   }
+  class Response
+
+    # @return [String] Payment key for future correspondence about this transaction
+    attr_accessor :key
+    # @return [Boolean] true/false, depending of the API response
+    attr_accessor :success
+    @@success = false
+    alias_method :success?, :success
+    
+
+
+    # @return [String] Response message from DocData
+    attr_accessor :message
+
+    # @return [Hash] The parsed report node of the reponse-xml
+    attr_accessor :report
+
+    # @return [String] The raw XML returned by the API
+    attr_accessor :xml
+
+
+    #
+    # Initializer to transform a +Hash+ into an Response object
+    #
+    # @param [Hash] args
+    def initialize(args=nil)
+      @report = {}
+      return if args.nil?
+      args.each do |k,v|
+        instance_variable_set("@#{k}", v) unless v.nil?
+      end
+    end
+
+
+    # 
+    # Parses the returned response hash and turns it
+    # into a new Docdata::Response object
+    # 
+    # @param [String] method_name (name of the method: create, start, cancel, etc.)
+    # @param [Hash] response
+    def self.parse(method_name, response)
+      body, xml = self.response_body(response)
+      if body["#{method_name}_response".to_sym] && body["#{method_name}_response".to_sym]["#{method_name}_error".to_sym]
+        raise DocdataError.new(response), body["#{method_name}_response".to_sym]["#{method_name}_error".to_sym][:error]
+      else
+        m = body["#{method_name}_response".to_sym]["#{method_name}_success".to_sym]
+        r = self.new(key: m[:key], message: m[:success], success: true)
+        r.xml    = xml #save the raw xml
+        if m[:report]
+          r.report = m[:report]
+        end
+        return r
+      end
+    end
+
+    # @return [Hash] the body of the response. In the test environment, this uses
+    # plain XML files, in normal use, it uses a `Savon::Response`
+    def self.response_body(response)
+      if response.is_a?(File)
+        parser = Nori.new(:convert_tags_to => lambda { |tag| tag.snakecase.to_sym })
+        xml = response.read 
+        body = parser.parse(xml).first.last.first.last
+      else
+        body = response.body.to_hash
+        xml = response.xml
+      end
+      return body, xml
+    end
+
+    methods = [:total_registered, :total_shopper_pending, :total_acquier_pending, :total_acquirer_approved, :total_captured, :total_refunded, :total_chargedback]
+    methods.each do |method|
+      define_method method do
+        report[:approximate_totals][method].to_i
+      end
+    end
+
+    # @return [String] the payment method of this transaction
+    def payment_method
+      if report[:payment]
+        report[:payment][:payment_method]
+      else
+        nil
+      end
+    end
+
+    # @return [String] the status string provided by the API. One of [AUTHORIZED, CANCELED]
+    def payment_status
+      report[:payment][:authorization][:status]
+    end
+
+    # @return [Boolean] true/false, depending wether this payment is considered paid.
+    # @note Docdata doesn't explicitly say 'paid' or 'not paid', this is a little bit a gray area.
+    # There are several approaches to determine if a payment is paid, some slow and safe, other quick and unreliable.
+    # The reason for this is that some payment methods have a much longer processing time. For each payment method
+    # a different 'paid'.
+    # @note This method is never 100% reliable. If you need to finetune this, please implement your own method, using
+    # the available data (total_captured, total_registered, etc.)
+    def paid
+      if payment_method
+        case payment_method
+        # ideal (dutch)
+        when "IDEAL" 
+          (total_registered == total_captured) && (capture_status == "CAPTURED")
+        # creditcard
+        when "MASTERCARD", "VISA", "AMEX"
+          (total_registered == total_acquirer_approved)
+        # sofort überweisung (german)
+        when "SOFORT_UEBERWEISUNG"
+          (total_registered == total_acquirer_approved)
+        # fallback: if total_registered equals total_caputured,
+        # we can assume that this order is paid. No 100% guarantee.
+        else
+          total_registered == total_captured
+        end
+      else
+        false
+      end
+    end
+    alias_method :paid?, :paid
+
+    # @return [Boolean]
+    def authorized
+      payment_status == "AUTHORIZED"
+    end
+    alias_method :authorized?, :authorized
+
+    # @return [Boolean]
+    def canceled
+      payment_status == "CANCELED" || capture_status == "CANCELED"
+    end
+    alias_method :canceled?, :canceled
+
+    # @return [String] the status of the capture, if exists
+    def capture_status
+      report[:payment][:authorization][:capture][:status]
+    end
+
+    # @return [Integer] the caputred amount in cents
+    def amount
+      report[:payment][:authorization][:amount].to_i
+    end
+    
+    # @return [String] the currency if this transaction
+    def currency
+      status_xml.xpath("//amount").first.attributes["currency"].value
+    end
+
+    # @return [Nokogiri::XML::Document] object
+    def doc
+      # remove returns and whitespaces between tags
+      xml_string = xml.gsub("\n", "").gsub(/>\s+</, "><")
+      # return Nokogiri::XML::Document
+      @doc ||= Nokogiri.XML(xml_string)
+    end
+
+    # @return [Nokogiri::XML::Document] object, containing only the status section
+    # @note This is a fix for Nokogiri's trouble finding xpath elements after 'xlmns' attribute in a node.
+    def status_xml
+      @status_xml ||= Nokogiri.XML(doc.xpath("//S:Body").first.children.first.children.first.to_xml)
+    end
+
+  end
+end