sepa_king_extended 0.10.1

data/lib/sepa_king/converter.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+module SEPA
+  module Converter
+    def convert(*attributes, options)
+      include InstanceMethods
+
+      method_name = "convert_#{options[:to]}"
+      raise ArgumentError.new("Converter '#{options[:to]}' does not exist!") unless InstanceMethods.method_defined?(method_name)
+
+      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/sepa_king/message/credit_transfer.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+module SEPA
+  class CreditTransfer < Message
+    self.account_class = DebtorAccount
+    self.transaction_class = CreditTransferTransaction
+    self.xml_main_tag = 'CstmrCdtTrfInitn'
+    self.known_schemas = [ PAIN_001_003_03, PAIN_001_002_03, PAIN_001_001_03 ]
+
+  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
+      }
+    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))
+          unless group[:service_level].blank?
+            builder.PmtTpInf do
+              builder.SvcLvl do
+                builder.Cd(group[:service_level])
+              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
+              if account.bic
+                builder.BIC(account.bic)
+              else
+                builder.Othr do
+                  builder.Id('NOTPROVIDED')
+                end
+              end
+            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)
+        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

data/lib/sepa_king/message/direct_debit.rb

@@ -0,0 +1,151 @@
+# encoding: utf-8
+
+module SEPA
+  class DirectDebit < Message
+    self.account_class = CreditorAccount
+    self.transaction_class = DirectDebitTransaction
+    self.xml_main_tag = 'CstmrDrctDbtInitn'
+    self.known_schemas = [ PAIN_008_003_02, PAIN_008_002_02, PAIN_008_001_02 ]
+
+    validate do |record|
+      if record.transactions.map(&:local_instrument).uniq.size > 1
+        errors.add(:base, 'CORE, COR1 AND B2B must not be mixed in one message!')
+      end
+    end
+
+  private
+    # Find groups of transactions which share the same values of some attributes
+    def transaction_group(transaction)
+      { requested_date:   transaction.requested_date,
+        local_instrument: transaction.local_instrument,
+        sequence_type:    transaction.sequence_type,
+        batch_booking:    transaction.batch_booking,
+        account:          transaction.creditor_account || account
+      }
+    end
+
+    def build_payment_informations(builder)
+      # Build a PmtInf block for every group of transactions
+      grouped_transactions.each do |group, transactions|
+        builder.PmtInf do
+          builder.PmtInfId(payment_information_identification(group))
+          builder.PmtMtd('DD')
+          builder.BtchBookg(group[:batch_booking])
+          builder.NbOfTxs(transactions.length)
+          builder.CtrlSum('%.2f' % amount_total(transactions))
+          builder.PmtTpInf do
+            builder.SvcLvl do
+              builder.Cd('SEPA')
+            end
+            builder.LclInstrm do
+              builder.Cd(group[:local_instrument])
+            end
+            builder.SeqTp(group[:sequence_type])
+          end
+          builder.ReqdColltnDt(group[:requested_date].iso8601)
+          builder.Cdtr do
+            builder.Nm(group[:account].name)
+          end
+          builder.CdtrAcct do
+            builder.Id do
+              builder.IBAN(group[:account].iban)
+            end
+          end
+          builder.CdtrAgt do
+            builder.FinInstnId do
+              if group[:account].bic
+                builder.BIC(group[:account].bic)
+              else
+                builder.Othr do
+                  builder.Id('NOTPROVIDED')
+                end
+              end
+            end
+          end
+          builder.ChrgBr('SLEV')
+          builder.CdtrSchmeId do
+            builder.Id do
+              builder.PrvtId do
+                builder.Othr do
+                  builder.Id(group[:account].creditor_identifier)
+                  builder.SchmeNm do
+                    builder.Prtry('SEPA')
+                  end
+                end
+              end
+            end
+          end
+
+          transactions.each do |transaction|
+            build_transaction(builder, transaction)
+          end
+        end
+      end
+    end
+
+    def build_amendment_informations(builder, transaction)
+      return unless transaction.original_debtor_account || transaction.same_mandate_new_debtor_agent
+      builder.AmdmntInd(true)
+      builder.AmdmntInfDtls do
+        if transaction.original_debtor_account
+          builder.OrgnlDbtrAcct do
+            builder.Id do
+              builder.IBAN(transaction.original_debtor_account)
+            end
+          end
+        else
+          builder.OrgnlDbtrAgt do
+            builder.FinInstnId do
+              builder.Othr do
+                builder.Id('SMNDA')
+              end
+            end
+          end
+        end
+      end
+    end
+
+    def build_transaction(builder, transaction)
+      builder.DrctDbtTxInf do
+        builder.PmtId do
+          if transaction.instruction.present?
+            builder.InstrId(transaction.instruction)
+          end
+          builder.EndToEndId(transaction.reference)
+        end
+        builder.InstdAmt('%.2f' % transaction.amount, Ccy: transaction.currency)
+        builder.DrctDbtTx do
+          builder.MndtRltdInf do
+            builder.MndtId(transaction.mandate_id)
+            builder.DtOfSgntr(transaction.mandate_date_of_signature.iso8601)
+            build_amendment_informations(builder, transaction)
+          end
+        end
+        builder.DbtrAgt do
+          builder.FinInstnId do
+            if transaction.bic
+              builder.BIC(transaction.bic)
+            else
+              builder.Othr do
+                builder.Id('NOTPROVIDED')
+              end
+            end
+          end
+        end
+        builder.Dbtr do
+          builder.Nm(transaction.name)
+        end
+        builder.DbtrAcct 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

data/lib/sepa_king/message.rb

@@ -0,0 +1,135 @@
+# encoding: utf-8
+
+module SEPA
+  PAIN_008_001_02 = 'pain.008.001.02'
+  PAIN_008_002_02 = 'pain.008.002.02'
+  PAIN_008_003_02 = 'pain.008.003.02'
+  PAIN_001_001_03 = 'pain.001.001.03'
+  PAIN_001_002_03 = 'pain.001.002.03'
+  PAIN_001_003_03 = 'pain.001.003.03'
+
+  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 RuntimeError.new(errors.full_messages.join("\n")) unless valid?
+      raise RuntimeError.new("Incompatible with schema #{schema_name}!") unless schema_compatible?(schema_name)
+
+      builder = Builder::XmlMarkup.new indent: 2
+      builder.instruct!
+      builder.Document(xml_schema(schema_name)) do
+        builder.__send__(xml_main_tag) do
+          build_group_header(builder)
+          build_payment_informations(builder)
+        end
+      end
+    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_002_03, PAIN_008_002_02, PAIN_001_001_03
+          account.bic.present? && transactions.all? { |t| t.schema_compatible?(schema_name) }
+        when PAIN_001_003_03, PAIN_008_003_02, PAIN_008_001_02
+          transactions.all? { |t| t.schema_compatible?(schema_name) }
+      end
+    end
+
+    # Set unique identifer for the message
+    def message_identification=(value)
+      raise ArgumentError.new('mesage_identification must be a string!') unless value.is_a?(String)
+
+      regex = /\A([A-Za-z0-9]|[\+|\?|\/|\-|\:|\(|\)|\.|\,|\'|\ ]){1,35}\z/
+      raise ArgumentError.new("mesage_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 ||= "SEPA-KING/#{SecureRandom.hex(11)}"
+    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                => "urn:iso:std:iso:20022:tech:xsd:#{schema_name}",
+        :'xmlns:xsi'          => 'http://www.w3.org/2001/XMLSchema-instance',
+        :'xsi:schemaLocation' => "urn:iso:std:iso:20022:tech:xsd:#{schema_name} #{schema_name}.xsd" }
+    end
+
+    def build_group_header(builder)
+      builder.GrpHdr do
+        builder.MsgId(message_identification)
+        builder.CreDtTm(Time.now.iso8601)
+        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
+  end
+end

data/lib/sepa_king/transaction/credit_transfer_transaction.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+module SEPA
+  class CreditTransferTransaction < Transaction
+    attr_accessor :service_level
+
+    validates_inclusion_of :service_level, :in => ['SEPA', 'URGP', '']
+
+    validate { |t| t.validate_requested_date_after(Date.today) }
+
+    def initialize(attributes = {})
+      super
+      if self.currency == 'EUR'
+        self.service_level ||= 'SEPA'
+      end
+    end
+
+    def schema_compatible?(schema_name)
+      case schema_name
+      when PAIN_001_001_03
+        if self.currency == 'EUR'
+          self.service_level == 'SEPA'
+        end
+      when PAIN_001_002_03
+        self.bic.present? && self.service_level == 'SEPA' && self.currency == 'EUR'
+      when PAIN_001_003_03
+        self.currency == 'EUR'
+      end
+    end
+  end
+end

data/lib/sepa_king/transaction/direct_debit_transaction.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+module SEPA
+  class DirectDebitTransaction < Transaction
+    SEQUENCE_TYPES = %w(FRST OOFF RCUR FNAL)
+    LOCAL_INSTRUMENTS = %w(CORE COR1 B2B)
+
+    attr_accessor :mandate_id, :mandate_date_of_signature, :local_instrument, :sequence_type, :creditor_account, :original_debtor_account, :same_mandate_new_debtor_agent
+
+    validates_with MandateIdentifierValidator, field_name: :mandate_id, message: "%{value} is invalid"
+    validates_presence_of :mandate_date_of_signature
+    validates_inclusion_of :local_instrument, in: LOCAL_INSTRUMENTS
+    validates_inclusion_of :sequence_type, in: SEQUENCE_TYPES
+
+    validate { |t| t.validate_requested_date_after(Date.today.next) }
+
+    validate do |t|
+      if creditor_account
+        errors.add(:creditor_account, 'is not correct') unless creditor_account.valid?
+      end
+
+      if t.mandate_date_of_signature.is_a?(Date)
+        errors.add(:mandate_date_of_signature, 'is in the future') if t.mandate_date_of_signature > Date.today
+      else
+        errors.add(:mandate_date_of_signature, 'is not a Date')
+      end
+    end
+
+    def initialize(attributes = {})
+      super
+      self.local_instrument ||= 'CORE'
+      self.sequence_type ||= 'OOFF'
+    end
+
+    def schema_compatible?(schema_name)
+      case schema_name
+      when PAIN_008_002_02
+        self.bic.present? && %w(CORE B2B).include?(self.local_instrument) && self.currency == 'EUR'
+      when PAIN_008_003_02
+        self.currency == 'EUR'
+      when PAIN_008_001_02
+        true
+      end
+    end
+  end
+end

data/lib/sepa_king/transaction.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+module SEPA
+  class Transaction
+    include ActiveModel::Validations
+    extend Converter
+
+    DEFAULT_REQUESTED_DATE = Date.new(1999, 1, 1).freeze
+
+    attr_accessor :name, :iban, :bic, :amount, :instruction, :reference, :remittance_information, :requested_date, :batch_booking, :currency
+    convert :name, :instruction, :reference, :remittance_information, to: :text
+    convert :amount, to: :decimal
+
+    validates_length_of :name, within: 1..70
+    validates_length_of :currency, is: 3
+    validates_length_of :instruction, within: 1..35, allow_nil: true
+    validates_length_of :reference, within: 1..35, allow_nil: true
+    validates_length_of :remittance_information, within: 1..140, allow_nil: true
+    validates_numericality_of :amount, greater_than: 0
+    validates_presence_of :requested_date
+    validates_inclusion_of :batch_booking, :in => [true, false]
+    validates_with BICValidator, IBANValidator, message: "%{value} is invalid"
+
+    def initialize(attributes = {})
+      attributes.each do |name, value|
+        send("#{name}=", value)
+      end
+
+      self.requested_date ||= DEFAULT_REQUESTED_DATE
+      self.reference ||= 'NOTPROVIDED'
+      self.batch_booking = true if self.batch_booking.nil?
+      self.currency ||= 'EUR'
+    end
+
+    protected
+
+    def validate_requested_date_after(min_requested_date)
+      return unless requested_date.is_a?(Date)
+
+      if requested_date != DEFAULT_REQUESTED_DATE && requested_date < min_requested_date
+        errors.add(:requested_date, "must be greater or equal to #{min_requested_date}, or nil")
+      end
+    end
+  end
+end

data/lib/sepa_king/validator.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+module SEPA
+  class IBANValidator < ActiveModel::Validator
+    # IBAN2007Identifier (taken from schema)
+    REGEX = /\A[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}\z/
+
+    def validate(record)
+      field_name = options[:field_name] || :iban
+      value = record.send(field_name).to_s
+
+      unless IBANTools::IBAN.valid?(value) && value.match(REGEX)
+        record.errors.add(field_name, :invalid, message: options[:message])
+      end
+    end
+  end
+
+  class BICValidator < ActiveModel::Validator
+    # AnyBICIdentifier (taken from schema)
+    REGEX = /\A[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}\z/
+
+    def validate(record)
+      field_name = options[:field_name] || :bic
+      value = record.send(field_name)
+
+      if value
+        unless value.to_s.match(REGEX)
+          record.errors.add(field_name, :invalid, message: options[:message])
+        end
+      end
+    end
+  end
+
+  class CreditorIdentifierValidator < ActiveModel::Validator
+    REGEX = /\A[a-zA-Z]{2,2}[0-9]{2,2}([A-Za-z0-9]|[\+|\?|\/|\-|\:|\(|\)|\.|,|']){3,3}([A-Za-z0-9]|[\+|\?|\/|\-|:|\(|\)|\.|,|']){1,28}\z/
+
+    def validate(record)
+      field_name = options[:field_name] || :creditor_identifier
+      value = record.send(field_name)
+
+      unless valid?(value)
+        record.errors.add(field_name, :invalid, message: options[:message])
+      end
+    end
+
+    def valid?(creditor_identifier)
+      if ok = creditor_identifier.to_s.match(REGEX)
+        # In Germany, the identifier has to be exactly 18 chars long
+        if creditor_identifier[0..1].match(/DE/i)
+          ok = creditor_identifier.length == 18
+        end
+      end
+      ok
+    end
+  end
+
+  class MandateIdentifierValidator < ActiveModel::Validator
+    REGEX = /\A([A-Za-z0-9]|[\+|\?|\/|\-|\:|\(|\)|\.|\,|\']){1,35}\z/
+
+    def validate(record)
+      field_name = options[:field_name] || :mandate_id
+      value = record.send(field_name)
+
+      unless value.to_s.match(REGEX)
+        record.errors.add(field_name, :invalid, message: options[:message])
+      end
+    end
+  end
+end

data/lib/sepa_king/version.rb

@@ -0,0 +1,3 @@
+module SEPA
+  VERSION = '0.10.1'
+end

data/lib/sepa_king.rb

@@ -0,0 +1,16 @@
+require 'active_model'
+require 'bigdecimal'
+require 'builder'
+require 'iban-tools'
+
+require 'sepa_king/converter'
+require 'sepa_king/validator'
+require 'sepa_king/account'
+require 'sepa_king/account/debtor_account'
+require 'sepa_king/account/creditor_account'
+require 'sepa_king/transaction'
+require 'sepa_king/transaction/direct_debit_transaction'
+require 'sepa_king/transaction/credit_transfer_transaction'
+require 'sepa_king/message'
+require 'sepa_king/message/direct_debit'
+require 'sepa_king/message/credit_transfer'

data/sepa_king_extended.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'sepa_king/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'sepa_king_extended'
+  s.version       = SEPA::VERSION
+  s.authors       = ['Georg Leciejewski', 'Georg Ledermann', 'Chris Okamoto']
+  s.email         = ['gl@salesking.eu', 'mail@georg-ledermann.de', 'christiane.okamoto@gmail.com']
+  s.description   = 'Accepts payment type 3 - for payments in CHF and not SEPA in pain.0001.0001.03 (ISO 20022)'
+  s.summary       = 'Ruby gem for creating SEPA XML files'
+  s.homepage      = 'https://github.com/chrisokamoto/sepa_king_extended'
+
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ['lib']
+
+  s.required_ruby_version = '>= 2.0.0'
+
+  s.add_runtime_dependency 'activemodel', '>= 3.0.0'
+  s.add_runtime_dependency 'builder'
+  s.add_runtime_dependency 'iban-tools'
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'coveralls'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'nokogiri', RUBY_VERSION < '2.1.0' ? '~> 1.6.0' : '~> 1'
+end