sps_king 0.1.0

data/lib/sps_king.rb

@@ -0,0 +1,22 @@
+require 'active_model'
+require 'bigdecimal'
+require 'date'
+require 'nokogiri'
+require 'iban-tools'
+
+require 'sps_king/error'
+require 'sps_king/converter'
+require 'sps_king/validator'
+require 'sps_king/version'
+require 'sps_king/account'
+require 'sps_king/account/debtor_account'
+require 'sps_king/account/debtor_address'
+require 'sps_king/account/creditor_account'
+require 'sps_king/account/creditor_address'
+require 'sps_king/structured_remittance_information'
+require 'sps_king/transaction'
+require 'sps_king/transaction/direct_debit_transaction'
+require 'sps_king/transaction/credit_transfer_transaction'
+require 'sps_king/message'
+require 'sps_king/message/direct_debit'
+require 'sps_king/message/credit_transfer'

data/lib/sps_king/account.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+module SPS
+  class Account
+    include ActiveModel::Validations
+    extend Converter
+
+    attr_accessor :name,
+                  :iban,
+                  :bic
+
+    convert :name, to: :text
+
+    validates_length_of :name, within: 1..70
+    validates_with BICValidator,
+                   IBANValidator,
+                   message: "%{value} is invalid"
+
+    def initialize(attributes = {})
+      attributes.each do |name, value|
+        public_send("#{name}=", value)
+      end
+    end
+  end
+end

data/lib/sps_king/account/creditor_account.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+module SPS
+  class CreditorAccount < Account
+    attr_accessor :creditor_identifier,
+                  :isr_participant_number
+
+    validates_with CreditorIdentifierValidator,
+                   message: "%{value} is invalid"
+    validates_format_of :isr_participant_number, with: /\A\d{9}\z/, allow_nil: true
+  end
+end

data/lib/sps_king/account/creditor_address.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+module SPS
+  class CreditorAddress
+    include ActiveModel::Validations
+    extend Converter
+
+    attr_accessor :street_name,
+                  :building_number,
+                  :post_code,
+                  :town_name,
+                  :country_code,
+                  :address_line1,
+                  :address_line2
+
+    convert :street_name,     to: :text
+    convert :building_number, to: :text
+    convert :post_code,       to: :text
+    convert :town_name,       to: :text
+    convert :country_code,    to: :text
+    convert :address_line1,   to: :text
+    convert :address_line2,   to: :text
+
+    validates_length_of :street_name,     maximum: 70
+    validates_length_of :building_number, maximum: 16
+    validates_length_of :post_code,       maximum: 16
+    validates_length_of :town_name,       maximum: 35
+    validates_length_of :country_code,    is: 2
+    validates_length_of :address_line1,   maximum: 70
+    validates_length_of :address_line2,   maximum: 70
+
+    def initialize(attributes = {})
+      attributes.each do |name, value|
+        public_send("#{name}=", value)
+      end
+    end
+  end
+end

data/lib/sps_king/account/debtor_account.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+module SPS
+  class DebtorAccount < Account
+  end
+end

data/lib/sps_king/account/debtor_address.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+module SPS
+  class DebtorAddress
+    include ActiveModel::Validations
+    extend Converter
+
+    attr_accessor :street_name,
+                  :post_code,
+                  :town_name,
+                  :country_code,
+                  :address_line1,
+                  :address_line2
+
+    convert :street_name,     to: :text
+    convert :post_code,       to: :text
+    convert :town_name,       to: :text
+    convert :country_code,    to: :text
+    convert :address_line1,   to: :text
+    convert :address_line2,   to: :text
+
+    validates_length_of :street_name,     maximum: 70
+    validates_length_of :post_code,       maximum: 16
+    validates_length_of :town_name,       maximum: 35
+    validates_length_of :country_code,    is: 2
+    validates_length_of :address_line1,   maximum: 70
+    validates_length_of :address_line2,   maximum: 70
+
+    def initialize(attributes = {})
+      attributes.each do |name, value|
+        public_send("#{name}=", value)
+      end
+    end
+  end
+end

data/lib/sps_king/converter.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+module SPS
+  module Converter
+    def convert(*attributes, options)
+      include InstanceMethods
+
+      method_name = "convert_#{options[:to]}"
+      unless InstanceMethods.method_defined?(method_name)
+        raise ArgumentError.new("Converter '#{options[:to]}' does not exist!")
+      end
+
+      attributes.each do |attribute|
+        define_method "#{attribute}=" do |value|
+          instance_variable_set("@#{attribute}", send(method_name, value))
+        end
+      end
+    end
+
+    module InstanceMethods
+      def convert_text(value)
+        return unless value
+
+        value.to_s.
+          # Replace some special characters described as "Best practices" in Chapter 6.2 of this document:
+          # http://www.europeanpaymentscouncil.eu/index.cfm/knowledge-bank/epc-documents/sepa-requirements-for-an-extended-character-set-unicode-subset-best-practices/
+          gsub('€','E').
+          gsub('@','(at)').
+          gsub('_','-').
+
+          # Replace linebreaks by spaces
+          gsub(/\n+/,' ').
+
+          # Remove all invalid characters
+          gsub(/[^a-zA-Z0-9ÄÖÜäöüß&*$%\ \'\:\?\,\-\(\+\.\)\/]/, '').
+
+          # Remove leading and trailing spaces
+          strip
+      end
+
+      def convert_decimal(value)
+        return unless value
+        value = begin
+          BigDecimal(value.to_s)
+        rescue ArgumentError
+        end
+
+        if value && value.finite? && value > 0
+          value.round(2)
+        end
+      end
+    end
+  end
+end

data/lib/sps_king/error.rb

@@ -0,0 +1,4 @@
+module SPS
+  class Error < RuntimeError
+  end
+end

data/lib/sps_king/message.rb

@@ -0,0 +1,163 @@
+# encoding: utf-8
+
+module SPS
+  PAIN_008_001_02_CH_03 = 'pain.008.001.02.ch.03'
+  PAIN_001_001_03_CH_02 = 'pain.001.001.03.ch.02'
+
+  class Message
+    include ActiveModel::Validations
+
+    attr_reader :account, :grouped_transactions
+
+    validates_presence_of :transactions
+    validate do |record|
+      record.errors.add(:account, record.account.errors.full_messages) unless record.account.valid?
+    end
+
+    class_attribute :account_class, :transaction_class, :xml_main_tag, :known_schemas
+
+    def initialize(account_options={})
+      @grouped_transactions = {}
+      @account = account_class.new(account_options)
+    end
+
+    def add_transaction(options)
+      transaction = transaction_class.new(options)
+      raise ArgumentError.new(transaction.errors.full_messages.join("\n")) unless transaction.valid?
+      @grouped_transactions[transaction_group(transaction)] ||= []
+      @grouped_transactions[transaction_group(transaction)] << transaction
+    end
+
+    def transactions
+      grouped_transactions.values.flatten
+    end
+
+    # @return [String] xml
+    def to_xml(schema_name=self.known_schemas.first)
+      raise SPS::Error.new(errors.full_messages.join("\n")) unless valid?
+      raise SPS::Error.new("Incompatible with schema #{schema_name}!") unless schema_compatible?(schema_name)
+
+      builder = Nokogiri::XML::Builder.new do |builder|
+        builder.Document(xml_schema(schema_name)) do
+          builder.__send__(xml_main_tag) do
+            build_group_header(builder)
+            build_payment_informations(builder)
+          end
+        end
+      end
+
+      validate_final_document!(builder.doc, schema_name)
+      builder.to_xml
+    end
+
+    def amount_total(selected_transactions=transactions)
+      selected_transactions.inject(0) { |sum, t| sum + t.amount }
+    end
+
+    def schema_compatible?(schema_name)
+      raise ArgumentError.new("Schema #{schema_name} is unknown!") unless self.known_schemas.include?(schema_name)
+
+      case schema_name
+        when PAIN_001_001_03_CH_02
+          transactions.all? { |t| t.schema_compatible?(schema_name) }
+        when PAIN_008_001_02_CH_03
+          transactions.all? { |t| t.schema_compatible?(schema_name) } &&
+          !account.iban.to_s.match(/^(CH|LI)/).nil? # Only allowed for switzerland or liechtenstein
+      end
+    end
+
+    # Set unique identifer for the message
+    def message_identification=(value)
+      raise ArgumentError.new('message_identification must be a string!') unless value.is_a?(String)
+
+      regex = /\A([A-Za-z0-9]|[\+|\?|\/|\-|\:|\(|\)|\.|\,|\'|\ ]){1,35}\z/
+      raise ArgumentError.new("message_identification does not match #{regex}!") unless value.match(regex)
+
+      @message_identification = value
+    end
+
+    # Get unique identifer for the message (with fallback to a random string)
+    def message_identification
+      @message_identification ||= "SPS-KING/#{SecureRandom.hex(11)}"
+    end
+
+    # Set creation date time for the message
+    # p.s. Rabobank in the Netherlands only accepts the more restricted format [0-9]{4}[-][0-9]{2,2}[-][0-9]{2,2}[T][0-9]{2,2}[:][0-9]{2,2}[:][0-9]{2,2}
+    def creation_date_time=(value)
+      raise ArgumentError.new('creation_date_time must be a string!') unless value.is_a?(String)
+
+      regex = /[0-9]{4}[-][0-9]{2,2}[-][0-9]{2,2}(?:\s|T)[0-9]{2,2}[:][0-9]{2,2}[:][0-9]{2,2}/
+      raise ArgumentError.new("creation_date_time does not match #{regex}!") unless value.match(regex)
+
+      @creation_date_time = value
+    end
+
+    # Get creation date time for the message (with fallback to Time.now.iso8601)
+    def creation_date_time
+      @creation_date_time ||= Time.now.iso8601
+    end
+
+    # Returns the id of the batch to which the given transaction belongs
+    # Identified based upon the reference of the transaction
+    def batch_id(transaction_reference)
+      grouped_transactions.each do |group, transactions|
+        if transactions.select { |transaction| transaction.reference == transaction_reference }.any?
+          return payment_information_identification(group)
+        end
+      end
+    end
+
+    def batches
+      grouped_transactions.keys.collect { |group| payment_information_identification(group) }
+    end
+
+  private
+    # @return {Hash<Symbol=>String>} xml schema information used in output xml
+    def xml_schema(schema_name)
+      {
+        :xmlns                => "http://www.six-interbank-clearing.com/de/#{schema_name}.xsd",
+        :'xmlns:xsi'          => 'http://www.w3.org/2001/XMLSchema-instance',
+        :'xsi:schemaLocation' => "http://www.six-interbank-clearing.com/de/#{schema_name}.xsd #{schema_name}.xsd"
+      }
+    end
+
+    def build_group_header(builder)
+      builder.GrpHdr do
+        builder.MsgId(message_identification)
+        builder.CreDtTm(creation_date_time)
+        builder.NbOfTxs(transactions.length)
+        builder.CtrlSum('%.2f' % amount_total)
+        builder.InitgPty do
+          builder.Nm(account.name)
+          builder.Id do
+            builder.OrgId do
+              builder.Othr do
+                builder.Id(account.creditor_identifier)
+              end
+            end
+          end if account.respond_to? :creditor_identifier
+        end
+      end
+    end
+
+    # Unique and consecutive identifier (used for the <PmntInf> blocks)
+    def payment_information_identification(group)
+      "#{message_identification}/#{grouped_transactions.keys.index(group)+1}"
+    end
+
+    # Returns a key to determine the group to which the transaction belongs
+    def transaction_group(transaction)
+      transaction
+    end
+
+    def validate_final_document!(document, schema_name)
+      xsd = Nokogiri::XML::Schema(
+              File.read(
+                File.expand_path("../../../lib/schema/#{schema_name}.xsd", __FILE__)
+              )
+            )
+      errors = xsd.validate(document).map { |error| error.message }
+      raise SPS::Error.new("Incompatible with schema #{schema_name}: #{errors.join(', ')}") if errors.any?
+    end
+  end
+end

data/lib/sps_king/message/credit_transfer.rb

@@ -0,0 +1,140 @@
+# encoding: utf-8
+
+module SPS
+  class CreditTransfer < Message
+    self.account_class = DebtorAccount
+    self.transaction_class = CreditTransferTransaction
+    self.xml_main_tag = 'CstmrCdtTrfInitn'
+    self.known_schemas = [
+      PAIN_001_001_03_CH_02
+    ]
+
+  private
+    # Find groups of transactions which share the same values of some attributes
+    def transaction_group(transaction)
+      {
+        requested_date:   transaction.requested_date,
+        batch_booking:    transaction.batch_booking,
+        service_level:    transaction.service_level,
+        category_purpose: transaction.category_purpose
+      }
+    end
+
+    def build_payment_informations(builder)
+      # Build a PmtInf block for every group of transactions
+      grouped_transactions.each do |group, transactions|
+        # All transactions with the same requested_date are placed into the same PmtInf block
+        builder.PmtInf do
+          builder.PmtInfId(payment_information_identification(group))
+          builder.PmtMtd('TRF')
+          builder.BtchBookg(group[:batch_booking])
+          builder.NbOfTxs(transactions.length)
+          builder.CtrlSum('%.2f' % amount_total(transactions))
+          builder.PmtTpInf do
+            if group[:service_level]
+              builder.SvcLvl do
+                builder.Cd(group[:service_level])
+              end
+            end
+            if group[:category_purpose]
+              builder.CtgyPurp do
+                builder.Cd(group[:category_purpose])
+              end
+            end
+          end
+          builder.ReqdExctnDt(group[:requested_date].iso8601)
+          builder.Dbtr do
+            builder.Nm(account.name)
+          end
+          builder.DbtrAcct do
+            builder.Id do
+              builder.IBAN(account.iban)
+            end
+          end
+          builder.DbtrAgt do
+            builder.FinInstnId do
+              builder.BIC(account.bic)
+            end
+          end
+          builder.ChrgBr('SLEV')
+
+          transactions.each do |transaction|
+            build_transaction(builder, transaction)
+          end
+        end
+      end
+    end
+
+    def build_transaction(builder, transaction)
+      builder.CdtTrfTxInf do
+        builder.PmtId do
+          if transaction.instruction.present?
+            builder.InstrId(transaction.instruction)
+          end
+          builder.EndToEndId(transaction.reference)
+        end
+        builder.Amt do
+          builder.InstdAmt('%.2f' % transaction.amount, Ccy: transaction.currency)
+        end
+        if transaction.bic
+          builder.CdtrAgt do
+            builder.FinInstnId do
+              builder.BIC(transaction.bic)
+            end
+          end
+        end
+        builder.Cdtr do
+          builder.Nm(transaction.name)
+          if transaction.creditor_address
+            builder.PstlAdr do
+              # Only set the fields that are actually provided.
+              # StrtNm, BldgNb, PstCd, TwnNm provide a structured address
+              # separated into its individual fields.
+              # AdrLine provides the address in free format text.
+              # Both are currently allowed and the actual preference depends on the bank.
+              # Also the fields that are required legally may vary depending on the country
+              # or change over time.
+              if transaction.creditor_address.street_name
+                builder.StrtNm transaction.creditor_address.street_name
+              end
+
+              if transaction.creditor_address.building_number
+                builder.BldgNb transaction.creditor_address.building_number
+              end
+
+              if transaction.creditor_address.post_code
+                builder.PstCd transaction.creditor_address.post_code
+              end
+
+              if transaction.creditor_address.town_name
+                builder.TwnNm transaction.creditor_address.town_name
+              end
+
+              if transaction.creditor_address.country_code
+                builder.Ctry transaction.creditor_address.country_code
+              end
+
+              if transaction.creditor_address.address_line1
+                builder.AdrLine transaction.creditor_address.address_line1
+              end
+
+              if transaction.creditor_address.address_line2
+                builder.AdrLine transaction.creditor_address.address_line2
+              end
+            end
+          end
+        end
+        builder.CdtrAcct do
+          builder.Id do
+            builder.IBAN(transaction.iban)
+          end
+        end
+        if transaction.remittance_information
+          builder.RmtInf do
+            builder.Ustrd(transaction.remittance_information)
+          end
+        end
+      end
+    end
+  end
+end