bankline_csv_import_file 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 66e997668b73970bc4435e68a9151d949bec1547
-  data.tar.gz: 285e3b7f92f5d1406434a8d8ce937e9862ee7920
+  metadata.gz: 54025cfff6c29e03b95f121166c159066a5c4ffb
+  data.tar.gz: bec14e977478642df29e3c967096cb69b34766ef
 SHA512:
-  metadata.gz: c4fe98dc2e53dbd8fd4932073ee28ba4e81d8fa19c66dcfd87bbc5094a6a837ac89154ddf4162d906a7abb32134e2bf4c0ed1d7ae8f2e620cfb012d41f104593
-  data.tar.gz: ab835ab9aa6e9c6fe4e2c5b3ad4d03bc178ccaf130837e6ec268bd2b70fdaf05b92e062911926b5e7f5ab0089b879a8cdbf40a90f43578cb4c3c3e45aa0fa5a3
+  metadata.gz: 8eba6219bfb10225a9d9ac28e6d1e6d75d1897781e78abc82f123ef955a5bd85e6d9bbd8c839405dbab369320631088acb63e9d17c8ee979fb66503c944aac57
+  data.tar.gz: 4b7d8620a44aceb424979484501c301898502d3aa59c494851e2090d988e283875b38eb621dca7f4ec84e3fa8b1725f406e05b3a844e6d4294bf416bfc7667b0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bankline_csv_import_file (0.1.0)
+    bankline_csv_import_file (0.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -27,8 +27,8 @@ PLATFORMS
 
 DEPENDENCIES
   bankline_csv_import_file!
-  bundler (~> 1.16)
-  rake (~> 10.0)
+  bundler
+  rake
   rspec
 
 BUNDLED WITH

data/README.md

@@ -9,28 +9,90 @@ USER BEWARE: At the time of writing, we have not yet verified that the produced
 
 ## Usage
 
-### Standard domestic payment
+Add any number of payments as described below, then generate the CSV content:
 
-All these fields are required unless stated.
+    file = BanklineCsvImportFile.new
+
+    file.add_domestic_payment(…)
+    file.add_domestic_payment(…)
+    file.add_international_payment(…)
+
+    file.generate  # => "foo,bar,…"
 
-Currency will be assumed to be GBP.
+
+### Domestic payment
+
+All these fields are required unless stated otherwise.
 
     file = BanklineCsvImportFile.new
+
     file.add_domestic_payment(
-      payer_sort_code: "151000",               # Any non-digits will be stripped automatically.
-      payer_account_number: "31806542",        # Any non-digits will be stripped automatically.
-      amount: "123.45",                        # Strings and BigDecimal are allowed. (Floats are not advisable for money.)
-      beneficiary_sort_code: "151000",         # Any non-digits will be stripped automatically.
-      beneficiary_account_number: "44298801",  # Any non-digits will be stripped automatically.
+      payer_sort_code: "151000",
+      payer_account_number: "31806542",
+      amount: "123.45",                        # Strings and BigDecimal are allowed. (Floats are not advisable for money.) Rounded to 2 decimals.
+      beneficiary_sort_code: "151000",
+      beneficiary_account_number: "44298801",
+      beneficiary_name: "John Doe",            # Truncated to a max length of 35.
+      beneficiary_reference: "Invoice 123",    # Truncated to a max length of 18.
+      payment_date: Date.new(2018, 1, 1),      # Optional. Defaults to Date.current if available, otherwise Date.today. See note below.
+    )
+
+    file.generate  # => "foo,bar,…"
+
+Currency is assumed to be GBP.
+
+Texts are converted to UPPERCASE and characters other than A-Z, 0-9, space and .-/& are automatically removed from free-text fields.
+
+Sort codes and account numbers are automatically normalised to the expected format.
+
+Bankline says this about the payment date:
+
+> Date payment to arrive (credit date)
+>
+> Identifies the date on which the funds are to be received by the beneficiary bank. Although not guaranteed this will normally be the same date on which the funds will be made available to the beneficiary.
+
+
+### International payment
+
+All these fields are required unless stated otherwise.
+
+    file = BanklineCsvImportFile.new
+    file.add_international_payment(
+      payer_sort_code: "151000",             # Any non-digits will be stripped automatically.
+      payer_account_number: "31806542",      # Any non-digits will be stripped automatically.
+      amount: "123.45",                      # Strings and BigDecimal are allowed. (Floats are not advisable for money.)
+      payment_date: Date.new(2018, 1, 1),    # Optional. Defaults to Date.current if available, otherwise Date.today. See note below.
+      beneficiary_bic: "SPKHDE2H",
+      beneficiary_iban: "DE53250501800039370089",
       beneficiary_name: "John Doe",
-      beneficiary_reference: "Invoice 123",
-      payment_date: Date.new(2018, 1, 1),      # Optional. Defaults to Date.current if available, otherwise Date.today.
+
+      # Optional but recommended, see below. Truncated to 35 chars per line and max 3 lines.
+      beneficiary_address: "10 Foo Street\nBartown, Baz County\nABC 123"
+
+      beneficiary_reference: "Invoice 123",  # Optional. Truncated to 35 chars per line and max 4 lines.
     )
     file.generate  # => "foo,bar,…"
 
-### Payment templates, CHAPS, international payments
+Currency is assumed to be GBP.
+
+Characters other than a-z, A-Z, 0-9, space and .-/?:(),+' are automatically removed from free-text fields.
+
+Sort codes, account numbers, IBAN and BIC are automatically normalised to the expected format.
 
-Not currently supported. Pull requests welcome!
+Bankline says this about the payment date:
+
+> Execution date
+>
+> Identifies the date on which the payment is to be initiated.
+
+Bankline says this about the beneficiary address:
+
+> We strongly recommend providing a beneficiary address as this is mandatory for certain destination countries and failure to populate this may cause the payment to be delayed or even rejected by the receiving bank.
+
+
+### Payment templates, CHAPS
+
+Not currently supported. Pull requests welcome! [The documentation](https://www.business.rbs.co.uk/content/dam/rbs_co_uk/Business_and_Content/PDFs/Bankline/Bankline-import-file-guide-CSV-RBS.pdf) is great and this codebase is tiny – you can do it! 💪
 
 
 ## Installation
@@ -56,6 +118,10 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Also see
+
+* [Banktools::GB](https://github.com/barsoom/banktools-gb)
+
 
 ## License
 

data/bankline_csv_import_file.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
 end

data/lib/bankline_csv_import_file.rb

@@ -26,8 +26,55 @@ class BanklineCsvImportFile
     record["T016"] = formatted_payment_date
     record["T022"] = normalize_account(beneficiary_sort_code)
     record["T028"] = normalize_account(beneficiary_account_number)
-    record["T030"] = normalize_string(beneficiary_name, max_length: 35)
-    record["T034"] = normalize_string(beneficiary_reference, max_length: 18)
+    record["T030"] = domestic_normalize_string(beneficiary_name, max_length: 35)
+    record["T034"] = domestic_normalize_string(beneficiary_reference, max_length: 18)
+
+    @records << record
+  end
+
+  def add_international_payment(payer_sort_code:, payer_account_number:, amount:, beneficiary_bic:, beneficiary_iban:, beneficiary_name:, beneficiary_address: nil, beneficiary_reference:, payment_date: nil)
+    # Use Ruby on Rails' `Date.current` when available, since it will be in the app time zone rather than the server time zone.
+    payment_date ||= Date.respond_to?(:current) ? Date.current : Date.today
+    formatted_payment_date = payment_date.strftime("%d%m%Y")
+
+    payer_account_with_sort_code = normalize_account("#{payer_sort_code}#{payer_account_number}")
+
+    normalized_iban = normalize_iban(beneficiary_iban)
+    normalized_bic = normalize_bic(beneficiary_bic)
+
+    beneficiary_country = normalized_iban[0, 2]
+
+    beneficiary_address_line_1, beneficiary_address_line_2, beneficiary_address_line_3 =
+      international_normalize_multiline_string(beneficiary_address, max_lines: 3, max_length_per_line: 35)
+
+    beneficiary_reference_line_1, beneficiary_reference_line_2, beneficiary_reference_line_3, beneficiary_reference_line_4 =
+      international_normalize_multiline_string(beneficiary_reference, max_lines: 4, max_length_per_line: 35)
+
+    record = Record.new
+
+    # https://www.business.rbs.co.uk/content/dam/rbs_co_uk/Business_and_Content/PDFs/Bankline/Bankline-import-file-guide-CSV-RBS.pdf
+    # Section 4.6, page 54.
+    record["T001"] = "04"  # 04 = International payment.
+    record["T007"] = beneficiary_country
+    record["T008"] = "N"  # Normal priority.
+    record["T010"] = payer_account_with_sort_code
+    record["T013"] = "GBP"  # Payment currency. (Presumably the target currency.)
+    record["T014"] = sprintf("%.2f", BigDecimal(amount))
+    record["T015"] = formatted_payment_date
+    record["T022"] = normalized_bic
+    record["T028"] = normalized_iban
+    record["T030"] = international_normalize_string(beneficiary_name, max_length: 35)
+
+    record["T031"] = beneficiary_address_line_1 if beneficiary_address_line_1
+    record["T032"] = beneficiary_address_line_2 if beneficiary_address_line_2
+    record["T033"] = beneficiary_address_line_3 if beneficiary_address_line_3
+
+    record["T037"] = beneficiary_reference_line_1 if beneficiary_reference_line_1
+    record["T038"] = beneficiary_reference_line_2 if beneficiary_reference_line_2
+    record["T039"] = beneficiary_reference_line_3 if beneficiary_reference_line_3
+    record["T040"] = beneficiary_reference_line_4 if beneficiary_reference_line_4
+
+    record["T042"] = "GBP"  # Credit currency. (Presumably the source currency.)
 
     @records << record
   end
@@ -42,13 +89,39 @@ class BanklineCsvImportFile
 
   private
 
+  def normalize_bic(bic)
+    normalized_bic = bic.to_s.upcase.gsub(/[^A-Z\d]/, "")
+
+    # https://www.business.rbs.co.uk/content/dam/rbs_co_uk/Business_and_Content/PDFs/Bankline/Bankline-import-file-guide-CSV-RBS.pdf section 2.5, page 6:
+    # "For any 8 character BIC, please append this with XXX i.e., for ULSBIE2D populate as ULSBIE2DXXX."
+    normalized_bic << "XXX" if normalized_bic.length == 8
+
+    normalized_bic
+  end
+
+  def normalize_iban(iban)
+    iban.to_s.upcase.gsub(/[^A-Z\d]/, "")
+  end
+
   def normalize_account(string)
-    string.gsub(/\D/, "")
+    string.upcase.gsub(/\D/, "")
   end
 
-  def normalize_string(string, max_length:)
+  def domestic_normalize_string(string, max_length:)
     output = string.to_s.upcase
     output = output.gsub(%r{[^A-Z0-9./& -]}, "")
     output[0, max_length]
   end
+
+  def international_normalize_multiline_string(string, max_lines:, max_length_per_line:)
+    string.to_s.split("\n").reject(&:empty?)[0, max_lines].map { |line|
+      international_normalize_string(line, max_length: max_length_per_line)
+    }
+  end
+
+  def international_normalize_string(string, max_length:)
+    output = string.to_s
+    output = output.gsub(%r{[^a-zA-Z0-9./?:(),+' -]}, "")
+    output[0, max_length]
+  end
 end

data/lib/bankline_csv_import_file/version.rb

@@ -1,3 +1,3 @@
 class BanklineCsvImportFile
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bankline_csv_import_file
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Henrik Nyh
@@ -14,30 +14,30 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement