camt 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8bfc23e67cc63e70b660a029d859f138f397427a
+  data.tar.gz: 3f1a661d0c80e14264b48198b3cb17bd953ec7ba
+SHA512:
+  metadata.gz: e6208aa0f98688518eb4f6b5b80192088eebbe2129204f5cc834d6017f2814b296356092f94492c50682a8d6b822712974f9f1ef16c1b9f72214b2683445ed88
+  data.tar.gz: 59d5e30cfbf93252e6f0b6996a0d0ffa429d6f068c776cd1334801f36a838f31b2125c997d85f8a0751c084afa143ce7014f89c39c6ddba7cec5ed3af2703e45

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in camt.gemspec
+gemspec
+
+# gem 'debugger'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Reinier de Lange
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,31 @@
+# camt: A ruby gem for parsing CAMT.053 files
+
+This gem is based on the Python implementation by Therp (https://code.launchpad.net/~therp-nl/banking-addons) (camt.py). It is still far from supporting the full CAMT.053 specification, but it does provide the most important transaction information.
+
+## Installation
+
+Add to your Gemfile: gem 'camt', github: 'moiristo/camt'
+
+## Usage
+
+* Parse a CAMT file:
+  * camt = Camt::File.parse 'camt.xml'
+* Get information:
+  * puts camt.messages.inspect
+  * puts camt.statements.inspect
+  * puts camt.transactions.inspect
+
+## TODO
+
+* More testing
+* Extend Camt::Parser to support the full CAMT.053 specification
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Send me a pull request
+
+## Copyright
+
+Copyright (c) 2014 Reinier de Lange. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test

data/camt.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'camt/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "camt"
+  spec.version       = Camt::VERSION
+  spec.authors       = ["Reinier de Lange"]
+  spec.email         = ["r.j.delange@nedforce.nl"]
+  spec.description   = %q{A gem for parsing CAMT.053 files}
+  spec.summary       = %q{A gem for parsing CAMT.053 file}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "nokogiri"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/camt.rb

@@ -0,0 +1,100 @@
+require 'nokogiri'
+require 'time'
+
+require 'camt/version'
+require 'camt/object_extension'
+require 'camt/file'
+require 'camt/parser'
+
+module Camt
+
+  # Define structs
+
+  Message = Struct.new(:group_header, :statements)
+  GroupHeader = Struct.new(:message_id, :created_at, :recipient, :pagination, :additional_info)
+
+  Statement = Struct.new(
+    :id,
+    :date,
+    :created_at,
+    :local_account,
+    :local_currency,
+    :start_balance,
+    :end_balance,
+    :electronic_sequence_number,
+    :transactions
+  )
+
+  Transaction = Struct.new(
+    :execution_date,
+    :effective_date,
+    :transfer_type,
+    :transferred_amount,
+    :transaction_details
+  )
+
+  Reasons = {
+    'EN' => {
+      'AC01' => "Account identifier incorrect (i.e. invalid IBAN)",
+      'AC04' => "Account closed",
+      'AC06' => "Account blocked",
+      'AG01' => "Direct debit forbidden on this account for regulatory reasons",
+      'AG02' => "Operation/transaction code incorrect, invalid file format",
+      'AM04' => "Insufficient funds",
+      'AM05' => "Duplicate collection",
+      'BE01' => "Debtor's name does not match with the account holder's name",
+      'BE04' => "Creditor adress  missing or incorrect",
+      'BE05' => "Creditor identifier incorrect",
+      'FF01' => "Operation/transaction code incorrect, invalid file format",
+      'FF05' => "Operation/transaction type incorrect",
+      'FOCR' => "Returned after cancellation request of account holder",
+      'MD01' => "No Mandate",
+      'MD02' => "Mandate data missing or incorrect",
+      'MD06' => "Returned after request of account holder",
+      'MD07' => "Debtor deceased",
+      'MS02' => "Refusal by the Debtor",
+      'MS03' => "Reason not specified",
+      'RC01' => "Bank identifier incorrect (i.e. invalid BIC)",
+      'RR01' => "Regulatory Reason",
+      'RR02' => "Regulatory Reason",
+      'RR03' => "Regulatory Reason",
+      'RR04' => "Regulatory Reason",
+      'SL01' => "Specific Service offered by the Debtor Bank",
+      'CNOR' => "Creditor bank is not registered under this BIC in the CSM",
+      'DNOR' => "Debtor bank is not registered under this BIC in the CSM",
+      'TM01' => "File received after Cut-off Time",
+    },
+    'NL' => {
+      'AC01' => "Rekeningnummer incorrect",
+      'AC04' => "Rekeningnummer gesloten",
+      'AC06' => "Rekeningnummer geblokkeerd",
+      'AC13' => "Debiteur rekening is klant rekening",
+      'AG01' => "Transactie niet toegestaan",
+      'AG02' => "Transactiecode incorrect, ongeldig bestandsformaat",
+      'AM04' => "Onvoldoende saldo",
+      'AM05' => "Dubbel betaald",
+      'BE01' => "Debiteur naam en rekeningnummer komen niet overeen",
+      'BE04' => "Adres crediteur ontbreekt of incorrect",
+      'BE05' => "Identificatie van de crediteur is incorrect",
+      'FF01' => "Transactie code incorrect",
+      'FF05' => "Incasso type incorrect",
+      'FOCR' => "Terugboeking na annuleringsverzoek",
+      'MD01' => "Geen machtiging verstrekt",
+      'MD02' => "Verplichte informatie over machtiging ontbreekt of incorrect",
+      'MD06' => "Terugboeking op verzoek van klant",
+      'MD07' => "Klant overleden",
+      'MS02' => "Onbekende reden klant",
+      'MS03' => "Onbekende reden bank",
+      'RC01' => "BIC incorrect",
+      'RR01' => "Wet of regelgeving",
+      'RR02' => "Voor wet of regelgeving benodigde naam en/of adres van de debiteur is onvolledig of ontbreekt",
+      'RR03' => "Voor wet of regelgeving benodigde naam en/of adres van de crediteur ontbreekt",
+      'RR04' => "Wet of regelgeving",
+      'SL01' => "Specifieke dienstverlening bank (bv selectieve incassoblokkade)",
+      'CNOR' => "Bank van de crediteur is niet bekend onder deze BIC",
+      'DNOR' => "Bank van de debiteur is niet bekend onder deze BIC",
+      'TM01' => "Bestand aangeleverd na cut-off tijd (uiterste aanlevertijdstip)"
+    }
+  }
+
+end

data/lib/camt/file.rb

@@ -0,0 +1,47 @@
+module Camt
+  class File
+    attr_accessor :code, :country_code, :name
+    attr_accessor :doc, :ns
+
+    def self.parse file
+      Camt::File.new Nokogiri::XML ::File.read(file)
+    end
+
+    def initialize doc, options = { code: 'CAMT', country_code: 'NL', name: 'Generic CAMT Format' }
+      self.code = options[:code] || 'CAMT'
+      self.country_code = options[:country_code] || 'NL'
+      self.name = options[:name] || 'Generic CAMT Format'
+
+      self.doc = doc
+      self.ns = doc.namespaces['xmlns']
+
+      check_version
+    end
+
+
+    def check_version
+      # Sanity check the document's namespace
+      raise 'This does not seem to be a CAMT format bank statement' unless ns.start_with?('urn:iso:std:iso:20022:tech:xsd:camt.')
+      raise 'Only CAMT.053 is supported at the moment.' unless ns.start_with?('urn:iso:std:iso:20022:tech:xsd:camt.053.')
+      return true
+    end
+
+    def messages
+      @messages ||= Parser.new.parse self
+    end
+
+    def statements
+      @statements ||= messages.map(&:statements).flatten
+    end
+
+    def transactions
+      @transactions ||= statements.map(&:transactions).flatten
+    end
+
+
+    def to_s
+      "#{name}: #{messages.map{|message| message.group_header.message_id }.join(', ')}"
+    end
+
+  end
+end

data/lib/camt/object_extension.rb

@@ -0,0 +1,11 @@
+unless Object.respond_to?(:try)
+  class Object
+    def try(*a, &b)
+      if a.empty? && block_given?
+        yield self
+      else
+        public_send(*a, &b) if respond_to?(a.first)
+      end
+    end
+  end
+end

data/lib/camt/parser.rb

@@ -0,0 +1,174 @@
+module Camt
+  class Parser
+
+    attr_accessor :file
+
+    def get_balance_type_node node, balance_type
+      # :param node: BkToCstmrStmt/Stmt/Bal node
+      # :param balance type: one of 'OPBD', 'PRCD', 'ITBD', 'CLBD'
+      return node.at("./Bal/Tp/CdOrPrtry/Cd[text()='#{balance_type}']/../../..")
+    end
+
+    def parse_amount(node)
+      # Parse an element that contains both Amount and CreditDebitIndicator
+      #
+      # :return: signed amount
+      # :returntype: float
+
+      sign = node.at('./CdtDbtInd').text == 'DBIT' ? -1 : 1
+      return sign * node.at('./Amt').text.to_f
+    end
+
+    def get_start_balance(node)
+      # Find the (only) balance node with code OpeningBalance, or
+      # the only one with code 'PreviousClosingBalance'
+      # or the first balance node with code InterimBalance in
+      # the case of preceeding pagination.
+      #
+      # :param node: BkToCstmrStmt/Stmt/Bal node
+      balance_type_node = nil
+      ['OPBD', 'PRCD', 'ITBD'].detect{|code| balance_type_node = get_balance_type_node(node, code) }
+      parse_amount balance_type_node
+    end
+
+    def get_end_balance(node)
+      # Find the (only) balance node with code ClosingBalance, or
+      # the second (and last) balance node with code InterimBalance in
+      # the case of continued pagination.
+      #
+      # :param node: BkToCstmrStmt/Stmt/Bal node
+      balance_type_node = nil
+      ['CLBD', 'ITBD'].detect{|code| balance_type_node = get_balance_type_node(node, code) }
+      parse_amount balance_type_node
+    end
+
+    def parse_Stmt node
+      # Parse a single Stmt node.
+      #
+      # Be sure to craft a unique, but short enough statement identifier,
+      # as it is used as the basis of the generated move lines' names
+      # which overflow when using the full IBAN and CAMT statement id.
+
+      statement = Statement.new
+
+      statement.id = node.at('./Id').text
+      statement.electronic_sequence_number = node.at('./ElctrncSeqNb').text
+      statement.created_at = Time.parse(node.at('./CreDtTm').text)
+      statement.local_account = node.at('./Acct/Id').text.strip
+      statement.local_currency = node.at('./Acct/Ccy').text
+      statement.date = Time.parse(node.at('./Ntry[1]/ValDt/Dt | ./Ntry[1]/ValDt/DtTm').text)
+      statement.start_balance = get_start_balance(node)
+      statement.end_balance = get_end_balance(node)
+      statement.transactions = node.xpath('./Ntry').map{ |node| parse_Ntry(node) }
+
+      statement
+    end
+
+    def get_transfer_type node
+      # Map properietary codes from BkTxCd/Prtry/Cd.
+      # :param node: BkTxCd/Prtry node
+      { proprietary_code: node.at('./Cd').text, proprietary_issuer: node.at('./Issr').text } if node
+    end
+
+    def parse_Ntry node
+      # :param node: Ntry node
+
+      transaction = Transaction.new
+      transaction.execution_date      = node.at('./BookgDt/Dt | ./BookgDt/DtTm').text
+      transaction.effective_date      = node.at('./ValDt/Dt | ./ValDt/DtTm').text
+      transaction.transfer_type       = get_transfer_type(node.at('./BkTxCd/Prtry'))
+      transaction.transferred_amount  = parse_amount(node)
+      transaction.transaction_details = node.xpath('.//NtryDtls//TxDtls').map{ |node| parse_TxDtls(node) }
+
+      transaction
+    end
+
+    def get_party_values node
+      # Determine to get either the debtor or creditor party node
+      # and extract the available data from it
+      values = {}
+
+      party_type = node.at('../../CdtDbtInd').text == 'CRDT' ? 'Dbtr' : 'Cdtr'
+
+      party_node = node.at("./RltdPties/#{party_type}")
+      account_node = node.at("./RltdPties/#{party_type}Acct/Id")
+      bic_node = node.at("./RltdAgts/#{party_type}Agt/FinInstnId/BIC")
+
+      if party_node
+        values[:remote_owner] = party_node.at('./Nm').try(:text)
+        values[:remote_owner_country] = party_node.at('./PstlAdr/Ctry').try(:text)
+        values[:remote_owner_address] = party_node.at('./PstlAdr/AdrLine').try(:text)
+      end
+
+      if account_node
+        values[:remote_account] = account_node.at('./IBAN').try(:text)
+        values[:remote_account] ||= account_node.at('./Othr/Id').try(:text)
+        values[:remote_bank_bic] = bic_node.text if bic_node
+      end
+
+      return values
+    end
+
+    def parse_TxDtls node
+      # Parse a single TxDtls node
+      transaction_details = {}
+
+      if (unstructured = node.xpath('./RmtInf/Ustrd')).any?
+        transaction_details[:messages] = unstructured.map(&:text)
+      end
+
+      if (structured = node.xpath('./RmtInf/Strd/CdtrRefInf/Ref | ./Refs/EndToEndId')).any?
+        transaction_details[:references] = structured.map(&:text)
+      end
+
+      if mandate_identifier = node.at('./Refs/MndtId').try(:text)
+        transaction_details[:mandate_identifier] = mandate_identifier
+      end
+
+      if reason = node.at('./RtrInf/Rsn/Cd').try(:text)
+        reason_language = Camt::Reasons.keys.include?(file.country_code) ? file.country_code : 'EN'
+        transaction_details[:reason] = { code: reason, description: Camt::Reasons[reason_language][reason] }
+      end
+
+      transaction_details[:party] = get_party_values node
+
+      transaction_details
+    end
+
+    def parse_message node
+      group_header_node = node.at('./GrpHdr')
+
+      group_header = GroupHeader.new
+      group_header.message_id       = group_header_node.at('./MsgId').text
+      group_header.created_at       = Time.parse(group_header_node.at('./CreDtTm').text)
+      group_header.additional_info  = group_header_node.at('./AddtlInf').try(:text)
+
+      if recipient_node = group_header_node.at('./MsgRcpt')
+        group_header.recipient = {
+          name: recipient_node.at('./Nm').try(:text),
+          postal_address: recipient_node.at('./PstlAdr').try(:text),
+          identification: recipient_node.at('./Id').try(:text),
+          country_of_residence: recipient_node.at('./CtryOfRes').try(:text),
+          contact_details: recipient_node.at('./CtctDtls').try(:text)
+        }
+      end
+
+      if pagination_node = group_header_node.at('./MsgPgntn')
+        group_header.pagination = { page: pagination_node.at('./PgNb').text, last_page: (pagination_node.at('./LastPgInd').text == 'true') }
+      end
+
+      message = Message.new
+      message.group_header = group_header
+      message.statements = node.xpath('./Stmt').map{|node| parse_Stmt node }
+
+      message
+    end
+
+    def parse file
+      self.file = file
+      file.doc.remove_namespaces!
+      file.doc.xpath('//BkToCstmrStmt').map{|node| parse_message node }
+    end
+
+  end
+end