sepafm 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d8d907ad1e367406e6f1a98af49893e5f6211b04
-  data.tar.gz: cc91cebf5cfc771b33e98c4136f948fde2626631
+  metadata.gz: 1bcf3a08974b359e66ea01c5c484f143d7416b94
+  data.tar.gz: 452856d46a88d78db3f2187d5d7618479a92f1ad
 SHA512:
-  metadata.gz: 812949f6537bfd6e1df79f7a58b74033593e0788aa99103016eba8f9e578e2dd073337a11f58ff4fca586812d4b4842690e807f0c692c1f4bdaec9900481b02f
-  data.tar.gz: e8a469ea127b5003583a99a1c2cfc593fdb53ecfc43b95046bab97c67f1e83d1d9d3844e8442e46b0d78f376fdab2aeb4687a1c5dedb3f9ab931b5af1a2b877e
+  metadata.gz: cd9566b7a6bd7237b7620a6d1245d6e42fa55b4c962857f03f8dae76c6a8c4aecc8b0341e87cb88b06527259fcf6debd5e4ff5e82e409047526a5473569aec11
+  data.tar.gz: 89f83a46436f0e6ecae783e4c0f964a0d0ce817bc6952e81d65acc1076f84903bc31cd7b9f36c89ecfeb92d71850098a6040ee46678b59c1b43d4544efb0a46d

data/README.md

@@ -14,7 +14,7 @@ This project aims to create an open source implementation of SEPA Financial Mess
 
 Add this line to your application's Gemfile:
 
-    gem 'sepa'
+    gem 'sepafm'
 
 And then execute:
 
@@ -22,15 +22,165 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install sepa
+    $ gem install sepafm
 
 ## Usage
 
+### Building the payload
+
+* You can optionally have an invoice bundle included in a given transaction. If that is the case, you first have to define the invoices i.e. as follows:
+
+        invoice_bundle = []
+    
+        invoice_1 = {
+
+          # Has to be either CINV for normal invoice or CREN for credit note.
+          type: 'CINV',
+
+          # Positive for invoices and negative for credits.
+          amount: '700',
+
+          currency: 'EUR',
+
+          # You either have to specify an invoice number or a reference.
+          invoice_number: '123456'
+        }
+        
+        invoice_2 = {
+          type: 'CINV',
+          amount: '300',
+          currency: 'EUR',
+          reference: '123456789',
+        }
+        
+        invoice_3 = {
+          type: 'CREN',
+          amount: '-100',
+          currency: 'EUR',
+          invoice_number: '654321'
+        }
+        
+        invoice_4 = {
+          type: 'CREN',
+          amount: '-500',
+          currency: 'EUR',
+          reference: '987654321'
+        }
+        
+        # All the invoices are pushed to an array which is later included in the
+        # transaction's params.
+        invoice_bundle.push(invoice_1)
+        invoice_bundle.push(invoice_2)
+        invoice_bundle.push(invoice_3)
+        invoice_bundle.push(invoice_4)
+
+1. Define parameters for the transactions. You need at least one and one payment can have multiple. It is also worth noting that one payload can also have multiple payments. Here's how the parameters are defined:
+
+        transactions_params = {
+
+          # Optional id for the transaction. This is returned to the payer only.
+          # Max length is 35 characters.
+          instruction_id: '70CEF29BEBA8396A1F806005EDA51DEE4CE',
+
+          # Mandatory id for the transaction. This id is also passed on the the
+          # beneficiary. Max length is 35 characters.
+          end_to_end_id: '629CADFDAD5246AD915BA24A3C8E9FC3313',
+
+          # Amount to be transferred. Decimals separated by a period.
+          amount: '30.75',
+
+          # Currency. For Euros EUR etc.
+          currency: 'EUR',
+
+          # Bank's unique BIC.
+          bic: 'NDEAFIHH',
+
+          # Name of the creditor company or person
+          name: 'Testi Saaja Oy',
+
+          # Street and street number of the creditor.
+          address: 'Kokeilukatu 66',
+
+          # Creditor's county code.
+          country: 'FI',
+
+          # Creditor's postcode.
+          postcode: '00200',
+
+          # Creditor's town
+          town: 'Helsinki',
+
+          # Creditor's IBAN.
+          iban: 'FI7429501800000014',
+
+          # Reference number for the transaction. Mandatory if message not given.
+          reference: '00000000000000001245',
+
+          # Message for the transaction. Mandatory if reference not given.
+          message: 'Maksu',
+
+          # Optional set of invoices to be bundled in this transaction. If a bundle
+          # is provided amount, currency and reference will be automatically taken
+          # from that bundle.
+          invoice_bundle: invoice_bundle
+        }
+
+2. Create an array of Sepa::Transaction objects in which you put all the transactions of a given payment. You need to create an array for each payment separately.
+
+        payment_transactions = []
+
+        payment_transactions.push(Sepa::Transaction.new(transaction_params))
+
+3. Define the parameters for the payment/payments:
+
+        payment_params = {
+
+          # Unique id the payment. Max length is 35 characters.
+          payment_info_id: 'F56D46DDA136A981F58C05999479E768C92',
+
+          # Requested executin date for the payment in form YYY-MM-DD.
+          execution_date: '2013-08-10',
+
+          # The array of transactions for this payment
+          transactions: payment_transactions
+
+          # If this is a payment consisting of salary of pension transactions, you
+          # need to provide the following flag.
+          salary_or_pension: true
+        }
+
+4. Define parameters for the debtor as follows:
+
+        debtor_params = {
+          name: 'Testi Maksaja Oy',
+          address: 'Testing Street 12',
+          country: 'FI',
+          postcode: '00100',
+          town: 'Helsinki',
+          customer_id: '111111111',
+          iban: 'FI4819503000000010',
+          bic: 'NDEAFIHH'
+        }
+
+5. Create an array of Sepa::Payment objects in which you put all the payments that are going to be in the payload.
+
+        payments = []
+
+        payments.push(Sepa::Payment.new(debtor_params, payment_params))
+
+6. Create the actual payload object:
+
+        payload = Sepa::Payload.new(debtor_params, payments)
+        
+        # Will return the payload as an xml document which can be included in the
+        # construction of the SOAP message.
+        payload.to_xml
+
 ### Communicating with the bank
 
 1. Require the gem:
 
-        require 'sepa'
+        require 'sepafm'
 
 2. Define the hash that will be passed to the gem when initializing it:
 
@@ -45,7 +195,7 @@ Or install it yourself as:
           target_id: '11111111A1',
           language: 'FI',
           file_type: 'TITO',
-          content: payload,
+          content: payload, # You can use the payload you may have constructed earlier. I.e. payload.to_xml
           file_reference: "11111111A12006030329501800000014"
         }
 
@@ -112,7 +262,7 @@ Or install it yourself as:
 
 1. Require the gem:
 
-        require 'sepa'
+        require 'sepafm'
 
 2. Define the hash that will be passed to the gem when initializing it:
 
@@ -136,7 +286,7 @@ Or install it yourself as:
 
 1. Require the gem:
 
-        require 'sepa'
+        require 'sepafm'
 
 2. Define the hash that will be passed to the gem when initializing it:
 

data/lib/danske_get_bank_certificate_test.rb

@@ -1,4 +1,4 @@
-require 'sepa'
+require 'sepafm'
 
 params = {
           bank: :danske,
@@ -12,4 +12,4 @@ params = {
 
 sepa_client = Sepa::Client.new(params)
 
-sepa_client.send
+sepa_client.send

data/lib/sepa/custom_exceptions.rb

@@ -0,0 +1,2 @@
+class SchemaError < StandardError
+end

data/lib/sepa/payload.rb

@@ -0,0 +1,109 @@
+module Sepa
+  class Payload
+    def initialize(debtor, payments)
+      @debtor_name = debtor.fetch(:name)
+      @debtor_address = debtor.fetch(:address)
+      @debtor_country = debtor.fetch(:country)
+      @debtor_postcode = debtor.fetch(:postcode)
+      @debtor_town = debtor.fetch(:town)
+      @debtor_customer_id = debtor.fetch(:customer_id)
+
+      unless @payments = payments
+        fail KeyError, 'No payments provided for the payload.'
+      end
+
+      @doc = build
+    end
+
+    def to_xml
+       @doc.to_xml
+    end
+
+    # Checks whether the payload validates against the schema.
+    def valid?
+      @xsd ||= load_schema
+      @xsd.valid?(@doc)
+    end
+
+    # Errors that a schema validation of the document produces.
+    def errors
+      @xsd ||= load_schema
+      @xsd.validate(@doc).collect { |e| e.message }
+    end
+
+    private
+
+      def build
+        doc = build_root
+        doc = build_group_header(doc)
+        add_payments(doc)
+      end
+
+      # Gets the number of transactions in this payload.
+      def number_of_transactions
+        count = 0
+        @payments.each { |payment| count += payment.number_of_transactions }
+        count
+      end
+
+      # Builds the root and pain elements with namespace and schema definitions.
+      def build_root
+        builder = Nokogiri::XML::Builder.new do |xml|
+          xml.Document(
+            xmlns: 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.02',
+            'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
+            'xsi:schemaLocation' => 'urn:iso:std:iso:20022:tech:xsd:pain.001.' \
+            '001.02 pain.001.001.02.xsd'
+          ) {
+            xml.send 'pain.001.001.02'
+          }
+        end
+
+        builder.doc
+      end
+
+      # Builds the group header.
+      def build_group_header(root_e)
+        builder = Nokogiri::XML::Builder.with(root_e.at('Document > *')) do |xml|
+          xml.GrpHdr {
+            xml.MsgId SecureRandom.hex(17)
+            xml.CreDtTm Time.new.iso8601
+            xml.BtchBookg 'true'
+            xml.NbOfTxs number_of_transactions
+            xml.Grpg 'MIXD'
+            xml.InitgPty {
+              xml.Nm @debtor_name
+              xml.PstlAdr {
+                xml.AdrLine @debtor_address
+                xml.AdrLine "#{@debtor_country}-#{@debtor_postcode}"
+                xml.StrtNm @debtor_address
+                xml.PstCd "#{@debtor_country}-#{@debtor_postcode}"
+                xml.TwnNm @debtor_town
+                xml.Ctry @debtor_country
+              }
+            }
+          }
+        end
+
+        builder.doc
+      end
+
+      # Adds all the payments specified in the parameters to the payload.
+      def add_payments(root_e)
+        @payments.each do |payment|
+          root_e.at(
+            '/xmlns:Document/xmlns:pain.001.001.02',
+            'xmlns' => 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.02'
+          ).add_child(payment.to_node)
+        end
+
+        root_e
+      end
+
+      def load_schema
+        schemas_path = File.expand_path('../../../lib/sepa/xml_schemas', __FILE__)
+        xsd = Nokogiri::XML::Schema(File.read("#{schemas_path}/pain.001.001.02.xsd"))
+      end
+
+  end
+end

data/lib/sepa/payment.rb

@@ -0,0 +1,97 @@
+module Sepa
+  class Payment
+    def initialize(debtor, params)
+      @payment_info_id = params.fetch(:payment_info_id)
+      @execution_date = params.fetch(:execution_date)
+      @salary_or_pension = params[:salary_or_pension]
+
+      @debtor_name = debtor.fetch(:name)
+      @debtor_address = debtor.fetch(:address)
+      @debtor_country = debtor.fetch(:country)
+      @debtor_postcode = debtor.fetch(:postcode)
+      @debtor_town = debtor.fetch(:town)
+      @debtor_customer_id = debtor.fetch(:customer_id)
+      @debtor_iban = debtor.fetch(:iban)
+      @debtor_bic = debtor.fetch(:bic)
+
+      @transactions = params.fetch(:transactions)
+    end
+
+    # Returns a Nokogiri::XML::Node of the payment.
+    def to_node
+      node = build.doc.root
+      add_transactions(node)
+    end
+
+    # Returns the number of transactions in this payment.
+    def number_of_transactions
+      @transactions.count
+    end
+
+    private
+
+      # Builds the payment.
+      def build
+        Nokogiri::XML::Builder.new do |xml|
+          xml.PmtInf {
+            xml.PmtInfId @payment_info_id
+            xml.PmtMtd 'TRF'
+
+            xml.PmtTpInf {
+              xml.SvcLvl {
+                xml.Cd 'SEPA'
+              }
+
+              # Needs to be specified in case the payment contains salaris or
+              # pensions.
+              if @salary_or_pension
+                xml.CtgyPurp 'SALA'
+              end
+            }
+
+            xml.ReqdExctnDt @execution_date
+            xml.Dbtr {
+              xml.Nm @debtor_name
+              xml.PstlAdr {
+                xml.AdrLine @debtor_address
+                xml.AdrLine "#{@debtor_country}-#{@debtor_postcode} " \
+                "#{@debtor_town}"
+                xml.Ctry @debtor_country
+              }
+
+              xml.Id {
+                xml.OrgId {
+                  if @debtor_customer_id
+                    xml.BkPtyId @debtor_customer_id
+                  end
+                }
+              }
+            }
+
+            xml.DbtrAcct {
+              xml.Id {
+                xml.IBAN @debtor_iban
+              }
+            }
+
+            xml.DbtrAgt {
+              xml.FinInstnId {
+                xml.BIC @debtor_bic
+              }
+            }
+
+            xml.ChrgBr 'SLEV'
+          }
+        end
+      end
+
+      # Adds the transactions specified in the params hash to the payment.
+      def add_transactions(node)
+        @transactions.each do |transaction|
+          node.add_child(transaction.to_node)
+        end
+
+        node
+      end
+  end
+end

data/lib/sepa/transaction.rb

@@ -0,0 +1,178 @@
+module Sepa
+  class Transaction
+    def initialize(params)
+      @instruction_id = params[:instruction_id]
+      @end_to_end_id = params.fetch(:end_to_end_id)
+
+      # If the parameters contains an invoice bundle, the amount is taken from
+      # them.
+      if params[:invoice_bundle]
+        @amount = 0
+        params[:invoice_bundle].each do |invoice|
+          @amount += invoice.fetch(:amount).to_f
+        end
+      else
+        @amount = params.fetch(:amount)
+      end
+
+      @currency = params.fetch(:currency)
+      @bic = params.fetch(:bic)
+      @name = params.fetch(:name)
+      @address = params.fetch(:address)
+      @country = params.fetch(:country)
+      @postcode = params.fetch(:postcode)
+      @town = params.fetch(:town)
+      @iban = params.fetch(:iban)
+      @reference = params[:reference]
+      @message = params[:message]
+      @salary = params[:salary]
+      @pension = params[:pension]
+      @social_security_number = params[:social_security_number]
+      @invoice_bundle = params[:invoice_bundle]
+    end
+
+    # Returns a Nokogiri::XML::Node of the transaction.
+    def to_node
+      build.doc.root
+    end
+
+    private
+
+      # Builds the transaction
+      def build
+        Nokogiri::XML::Builder.new do |xml|
+          xml.CdtTrfTxInf {
+            xml.PmtId {
+              if @instruction_id
+                xml.InstrId @instruction_id
+              end
+
+              xml.EndToEndId @end_to_end_id
+            }
+
+            xml.Amt {
+              xml.InstdAmt(@amount, :Ccy => @currency)
+            }
+
+            xml.CdtrAgt {
+              xml.FinInstnId {
+                xml.BIC @bic
+              }
+            }
+
+            xml.Cdtr {
+              xml.Nm @name
+              xml.PstlAdr {
+                xml.AdrLine @address
+                xml.AdrLine("#{@country}-#{@postcode} " \
+                            "#{@town}")
+                xml.StrtNm @address
+                xml.PstCd "#{@country}-#{@postcode}"
+                xml.TwnNm @town
+                xml.Ctry @country
+              }
+
+              # Social security number needs to be added in case the transaction
+              # contains a salary.
+              if @salary
+                xml.Id {
+                  xml.PrvtId {
+                    xml.SclSctyNb @social_security_number
+                  }
+                }
+              end
+            }
+
+            xml.CdtrAcct {
+              xml.Id {
+                xml.IBAN @iban
+              }
+            }
+
+            # If the transaction contains a pension, this element needs to be
+            # specified.
+            if @pension
+              xml.Purp {
+                xml.Cd 'PENS'
+              }
+            end
+
+            xml.RmtInf {
+
+              # In case this transaction contains an invoice bundle, a Strd
+              # element is added for each invoice either with an invoice number
+              # or a reference.
+              if @invoice_bundle
+                message = ''
+                @invoice_bundle.each do |invoice|
+
+                  if invoice[:amount].to_f < 0
+                    amount = "#{invoice[:amount].to_f.abs}-"
+                  else
+                    amount = invoice[:amount]
+                  end
+
+                  if invoice[:reference]
+                    message += "RFS/#{invoice[:reference]}/" \
+                      "#{invoice[:currency]}#{amount}/"
+                  elsif invoice[:invoice_number]
+                    message += "#{invoice[:type]}/#{invoice[:invoice_number]}/" \
+                      "#{invoice[:currency]}#{amount}/"
+                  end
+                end
+
+                xml.Ustrd message
+
+                @invoice_bundle.each do |invoice|
+                  xml.Strd {
+                    xml.RfrdDocInf {
+                      xml.RfrdDocTp {
+                        xml.Cd invoice.fetch(:type)
+                      }
+
+                      if invoice[:invoice_number]
+                        xml.RfrdDocNb invoice[:invoice_number]
+                      end
+                    }
+                    xml.RfrdDocAmt {
+                      if invoice.fetch(:amount).to_f > 0
+                        xml.RmtdAmt(invoice[:amount],
+                                    :Ccy => invoice[:currency])
+                      else
+                        xml.CdtNoteAmt(invoice[:amount].to_f.abs,
+                                       :Ccy => invoice[:currency])
+                      end
+                    }
+
+                    if invoice[:reference]
+                      xml.CdtrRefInf {
+                        xml.CdtrRefTp {
+                          xml.Cd 'SCOR'
+                        }
+
+                        xml.CdtrRef invoice[:reference]
+                      }
+                    end
+                  }
+                end
+
+              elsif @reference
+                xml.Strd {
+                  xml.CdtrRefInf {
+                    xml.CdtrRefTp {
+                      xml.Cd 'SCOR'
+                    }
+
+                    xml.CdtrRef @reference
+                  }
+                }
+
+              else
+                xml.Ustrd @message
+              end
+            }
+          }
+        end
+      end
+  end
+end

data/lib/sepa/version.rb

@@ -1,3 +1,3 @@
 module Sepa
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end