sps_king 0.1.0

data/lib/sps_king/message/direct_debit.rb

@@ -0,0 +1,177 @@
+# encoding: utf-8
+
+module SPS
+  class DirectDebit < Message
+    self.account_class = CreditorAccount
+    self.transaction_class = DirectDebitTransaction
+    self.xml_main_tag = 'CstmrDrctDbtInitn'
+    self.known_schemas = [
+      PAIN_008_001_02_CH_03
+    ]
+
+    validate do |record|
+      if record.transactions.map(&:local_instrument).uniq.size > 1
+        errors.add(
+          :base,
+          'different local_instruments (e.g. LSV+, BDD) 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,
+        service_level:    transaction.service_level,
+        local_instrument: transaction.local_instrument,
+        account:          transaction.creditor_account || account
+      }
+    end
+
+    def creditor_scheme_name(service_level)
+      case service_level
+      when 'CHDD' # PAIN_008_001_02_CH_03 only
+        return 'CHDD'
+      when 'CHTA' # PAIN_008_001_02_CH_03 only
+        return 'CHLS'
+      end
+    end
+
+    # For IBANs from Switzerland or Liechtenstein the clearing system member id can be retrieved
+    # as the 5th to 9th digit of the IBAN, which is the local bank code.
+    def clearing_system_member_id_from_iban(iban)
+      return iban.to_s[4..8].sub(/^0*/, '')
+    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.PmtTpInf do
+            builder.SvcLvl do
+              builder.Prtry(group[:service_level])
+            end
+            builder.LclInstrm do
+              builder.Prtry(group[:local_instrument])
+            end
+          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
+              builder.ClrSysMmbId do
+                builder.MmbId(clearing_system_member_id_from_iban(group[:account].iban))
+              end
+              if group[:account].isr_participant_number
+                builder.Othr do
+                  builder.Id(group[:account].isr_participant_number)
+                end
+              end
+            end
+          end
+          builder.CdtrSchmeId do
+            builder.Id do
+              builder.PrvtId do
+                builder.Othr do
+                  builder.Id(group[:account].creditor_identifier)
+                  builder.SchmeNm do
+                    builder.Prtry(creditor_scheme_name(group[:service_level]))
+                  end
+                end
+              end
+            end
+          end
+
+          transactions.each do |transaction|
+            build_transaction(builder, transaction)
+          end
+        end
+      end
+    end
+
+    def build_transaction(builder, transaction)
+      builder.DrctDbtTxInf do
+        builder.PmtId do
+          builder.InstrId(transaction.instruction)
+          builder.EndToEndId(transaction.reference)
+        end
+        builder.InstdAmt('%.2f' % transaction.amount, Ccy: transaction.currency)
+        builder.DbtrAgt do
+          builder.FinInstnId do
+            builder.ClrSysMmbId do
+              builder.MmbId(clearing_system_member_id_from_iban(transaction.iban))
+            end
+          end
+        end
+        builder.Dbtr do
+          builder.Nm(transaction.name)
+          if transaction.debtor_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.debtor_address.street_name
+                builder.StrtNm transaction.debtor_address.street_name
+              end
+
+              if transaction.debtor_address.post_code
+                builder.PstCd transaction.debtor_address.post_code
+              end
+
+              if transaction.debtor_address.town_name
+                builder.TwnNm transaction.debtor_address.town_name
+              end
+
+              if transaction.debtor_address.country_code
+                builder.Ctry transaction.debtor_address.country_code
+              end
+
+              if transaction.debtor_address.address_line1
+                builder.AdrLine transaction.debtor_address.address_line1
+              end
+
+              if transaction.debtor_address.address_line2
+                builder.AdrLine transaction.debtor_address.address_line2
+              end
+            end
+          end
+        end
+        builder.DbtrAcct do
+          builder.Id do
+            builder.IBAN(transaction.iban)
+          end
+        end
+        builder.RmtInf do
+          if transaction.remittance_information
+            builder.Ustrd(transaction.remittance_information)
+          end
+
+          builder.Strd do
+            builder.CdtrRefInf do
+              builder.Tp do
+                builder.CdOrPrtry do
+                  builder.Prtry(transaction.structured_remittance_information.proprietary)
+                end
+              end
+              builder.Ref(transaction.structured_remittance_information.reference)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sps_king/structured_remittance_information.rb

@@ -0,0 +1,20 @@
+module SPS
+  class StructuredRemittanceInformation
+    include ActiveModel::Validations
+    extend Converter
+
+    attr_accessor :proprietary,
+                  :reference
+
+    validates_inclusion_of :proprietary, in: %w(ESR IPI)
+    validates_length_of :reference, within: 1..35
+
+    convert :proprietary, :reference, to: :text
+
+    def initialize(attributes = {})
+      attributes.each do |name, value|
+        public_send("#{name}=", value)
+      end
+    end
+  end
+end

data/lib/sps_king/transaction.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+module SPS
+  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,
+                  :structured_remittance_information,
+                  :requested_date,
+                  :batch_booking,
+                  :currency,
+                  :debtor_address,
+                  :creditor_address
+
+    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/sps_king/transaction/credit_transfer_transaction.rb

@@ -0,0 +1,19 @@
+# encoding: utf-8
+module SPS
+  class CreditTransferTransaction < Transaction
+    attr_accessor :service_level,
+                  :creditor_address,
+                  :category_purpose
+
+    validates_length_of :category_purpose, within: 1..4, allow_nil: true
+
+    validate { |t| t.validate_requested_date_after(Date.today) }
+
+    def schema_compatible?(schema_name)
+      case schema_name
+      when PAIN_001_001_03_CH_02
+        !self.bic.nil?
+      end
+    end
+  end
+end

data/lib/sps_king/transaction/direct_debit_transaction.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+module SPS
+  class DirectDebitTransaction < Transaction
+    SERVICE_LEVELS = %w(CHDD CHTA)
+
+    LOCAL_INSTRUMENTS_FOR_SERVICE_LEVELS = {
+      'CHDD' => %w(DDCOR1 DDB2B),
+      'CHTA' => %w(LSV+ BDD)
+    }
+
+    attr_accessor :service_level,
+                  :local_instrument,
+                  :creditor_account,
+                  :debtor_address
+
+    validates_format_of :iban, with: /\A(CH|LI)/
+
+    validates_presence_of :instruction,
+                          :structured_remittance_information
+
+    validates_inclusion_of :service_level, in: SERVICE_LEVELS, allow_nil: true
+    validate { |t| t.validate_local_instrument }
+    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
+    end
+
+    def initialize(attributes = {})
+      super
+      self.service_level    ||= 'CHTA'
+      self.local_instrument ||= 'LSV+'
+    end
+
+    def schema_compatible?(schema_name)
+      case schema_name
+      when PAIN_008_001_02_CH_03
+        self.structured_remittance_information.present? &&
+        self.structured_remittance_information.valid?
+      end
+    end
+
+    def validate_local_instrument
+      if SERVICE_LEVELS.include?(self.service_level)
+        allowed_local_instruments = LOCAL_INSTRUMENTS_FOR_SERVICE_LEVELS[self.service_level]
+
+        if !allowed_local_instruments.include?(self.local_instrument)
+          errors.add(
+            :local_instrument,
+            "is not correct. Must be one of #{allowed_local_instruments.join(', ')}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/sps_king/validator.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+module SPS
+  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|\A[A-Z0-9]{5,5}\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
+end

data/lib/sps_king/version.rb

@@ -0,0 +1,3 @@
+module SPS
+  VERSION = '0.1.0'
+end

data/spec/examples/pain.001.001.03.ch.02.xml

@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- 
+(C) Copyright 2010, SKSF, www.sksf.ch
+
+Anregungen und Fragen zu diesem Dokument können an das jeweilige Finanzinstitut gerichtet werden. 
+Allgemeine Anregungen können auch bei der SIX Interbank Clearing AG unter folgender Adresse angebracht werden: 
+pm@six-group.com
+-->
+<Document xmlns="http://www.six-interbank-clearing.com/de/pain.001.001.03.ch.02.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.six-interbank-clearing.com/de/pain.001.001.03.ch.02.xsd  pain.001.001.03.ch.02.xsd">
+	<CstmrCdtTrfInitn>
+		<GrpHdr>
+			<MsgId>MSG-01</MsgId>
+			<CreDtTm>2010-02-15T07:30:00</CreDtTm>
+			<NbOfTxs>3</NbOfTxs>
+			<CtrlSum>15850.00</CtrlSum>
+			<InitgPty>
+				<Nm>MUSTER AG</Nm>
+			</InitgPty>
+		</GrpHdr>
+		<PmtInf>
+			<PmtInfId>PMTINF-01</PmtInfId>
+			<PmtMtd>TRF</PmtMtd>
+			<BtchBookg>true</BtchBookg>
+			<ReqdExctnDt>2010-02-22</ReqdExctnDt>
+			<Dbtr>
+				<Nm>MUSTER AG</Nm>
+				<PstlAdr>
+					<Ctry>CH</Ctry>
+					<AdrLine>SELDWYLA</AdrLine>
+				</PstlAdr>
+			</Dbtr>
+			<DbtrAcct>
+				<Id>
+					<IBAN>CH5481230000001998736</IBAN>
+				</Id>
+			</DbtrAcct>
+			<DbtrAgt>
+				<FinInstnId>
+					<BIC>RAIFCH22</BIC>
+				</FinInstnId>
+			</DbtrAgt>
+			<CdtTrfTxInf>
+				<PmtId>
+					<InstrId>INSTRID-01-01</InstrId>
+					<EndToEndId>ENDTOENDID-001</EndToEndId>
+				</PmtId>
+				<PmtTpInf>
+					<LclInstrm>
+						<Prtry>CH01</Prtry>
+					</LclInstrm>
+				</PmtTpInf>
+				<Amt>
+					<InstdAmt Ccy="CHF">3949.75</InstdAmt>
+				</Amt>
+				<CdtrAcct>
+					<Id>
+						<Othr>
+							<Id>01-39139-1</Id>
+						</Othr>
+					</Id>
+				</CdtrAcct>
+				<RmtInf>
+					<Strd>
+						<CdtrRefInf>
+							<Ref>210000000003139471430009017</Ref>
+						</CdtrRefInf>
+					</Strd>
+				</RmtInf>
+			</CdtTrfTxInf>
+		</PmtInf>
+		<PmtInf>
+			<PmtInfId>PMTINF-02</PmtInfId>
+			<PmtMtd>TRF</PmtMtd>
+			<BtchBookg>true</BtchBookg>
+			<ReqdExctnDt>2010-02-18</ReqdExctnDt>
+			<Dbtr>
+				<Nm>MUSTER AG</Nm>
+				<PstlAdr>
+					<Ctry>CH</Ctry>
+					<AdrLine>SELDWYLA</AdrLine>
+				</PstlAdr>
+			</Dbtr>
+			<DbtrAcct>
+				<Id>
+					<IBAN>CH5481230000001998736</IBAN>
+				</Id>
+			</DbtrAcct>
+			<DbtrAgt>
+				<FinInstnId>
+					<BIC>RAIFCH22</BIC>
+				</FinInstnId>
+			</DbtrAgt>
+			<CdtTrfTxInf>
+				<PmtId>
+					<InstrId>INSTRID-02-01</InstrId>
+					<EndToEndId>ENDTOENDID-002</EndToEndId>
+				</PmtId>
+				<PmtTpInf>
+					<LclInstrm>
+						<Prtry>CH02</Prtry>
+					</LclInstrm>
+				</PmtTpInf>
+				<Amt>
+					<InstdAmt Ccy="CHF">8479.25</InstdAmt>
+				</Amt>
+				<Cdtr>
+					<Nm>Robert Scheider SA</Nm>
+					<PstlAdr>
+						<StrtNm>Rue de la gare</StrtNm>
+						<BldgNb>24</BldgNb>
+						<PstCd>2501</PstCd>
+						<TwnNm>Biel</TwnNm>
+						<Ctry>CH</Ctry>
+					</PstlAdr>
+				</Cdtr>
+				<CdtrAcct>
+					<Id>
+						<Othr>
+							<Id>25-9034-2</Id>
+						</Othr>
+					</Id>
+				</CdtrAcct>
+				<RmtInf>
+					<Ustrd>Rechnung Nr. 408</Ustrd>
+				</RmtInf>
+			</CdtTrfTxInf>
+			<CdtTrfTxInf>
+				<PmtId>
+					<InstrId>INSTRID-02-02</InstrId>
+					<EndToEndId>ENDTOENDID-003</EndToEndId>
+				</PmtId>
+				<PmtTpInf>
+					<SvcLvl>
+						<Cd>SEPA</Cd>
+					</SvcLvl>
+				</PmtTpInf>
+				<Amt>
+					<InstdAmt Ccy="EUR">3421.00</InstdAmt>
+				</Amt>
+				<CdtrAgt>
+					<FinInstnId>
+						<BIC>DEUTDEFF</BIC>
+					</FinInstnId>
+				</CdtrAgt>
+				<Cdtr>
+					<Nm>Peter Haller</Nm>
+					<PstlAdr>
+						<AdrLine>Rosenauweg 4</AdrLine>
+						<AdrLine>DE-80036 München</AdrLine>
+					</PstlAdr>
+				</Cdtr>
+				<CdtrAcct>
+					<Id>
+						<IBAN>DE62007620110623852957</IBAN>
+					</Id>
+				</CdtrAcct>
+				<RmtInf>
+					<Strd>
+						<CdtrRefInf>
+							<Tp>
+								<CdOrPrtry>
+									<Cd>SCOR</Cd>
+								</CdOrPrtry>
+							</Tp>
+							<Ref>RF712348231</Ref>
+						</CdtrRefInf>
+					</Strd>
+				</RmtInf>
+			</CdtTrfTxInf>
+		</PmtInf>
+	</CstmrCdtTrfInitn>
+</Document>