sepafm 0.0.2 → 0.1.0

data/README.md

@@ -1,385 +1,246 @@
 # Devlab / SEPA
 
-This project aims to create an open source implementation of SEPA Financial Messages using Web Services. Project implementation will be done in Ruby. We will also create a REST API for this module.
+[![Code Climate](https://codeclimate.com/github/devlab-oy/sepa.png)](https://codeclimate.com/github/devlab-oy/sepa)
+[![Code Climate](https://codeclimate.com/github/devlab-oy/sepa/coverage.png)](https://codeclimate.com/github/devlab-oy/sepa)
+[![Build Status](https://travis-ci.org/devlab-oy/sepa.svg?branch=master)](https://travis-ci.org/devlab-oy/sepa)
 
-## First milestone
+This project aims to create an open source implementation of SEPA Financial Messages using Web Services. Project implementation is done in Ruby.
 
-* Support for SEPA Web Services
-* Customer-to-Bank Statement. ISO standard "CustomerCreditTransferInitiationV03", XML schema "pain.001.001.03"
-* Bank-to-Customer Statement. ISO standard "BankToCustomerStatementV02", XML schema "camt.053.001.02"
-* Bank-to-Customer Debit/Credit Notification. ISO standard "BankToCustomerDebitCreditNotificationV02", XML schma "camt.054.001.02"
-* Update README
+Currently we have support for SEPA Web Services for:
+
+* Nordea
+* Danske Bank
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'sepafm'
+```ruby
+gem 'sepafm'
+```
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
-Or install it yourself as:
+Or install it with:
 
-    $ gem install sepafm
+```bash
+$ 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 'sepafm'
-
-2. Define the hash that will be passed to the gem when initializing it:
-
-        params = {
-          bank: :nordea,
-          private_key_path: "path/to/key", (OR private_key_plain : "Your private key in plain text form ")
-          cert_path: "path/to/key", (OR cert_plain : "Your certificate in plain text form ")
-          command: :command_as_symbol,
-          customer_id: '11111111',
-          environment: 'PRODUCTION',
-          status: 'NEW',
-          target_id: '11111111A1',
-          language: 'FI',
-          file_type: 'TITO',
-          content: payload, # You can use the payload you may have constructed earlier. I.e. payload.to_xml
-          file_reference: "11111111A12006030329501800000014"
-        }
-
-3. Initialize a new instance of the client and pass the params hash
-
-        sepa_client = Sepa::Client.new(params)
-
-4. There is only one method that can be called after initializing the client:
-
-  * Returns the whole soap response as a savon response object:
-
-            response = client.send
-
-### Verifying the response
+Define parameters hash for client, ie. get bank statement;
 
-* Check that the hashes match in the response
+```ruby
+params = {
+  bank: :nordea,
+  command: :download_file,
+  private_key: "...your private key...",
+  cert: "...your certificate...",
+  customer_id: '11111111',
+  file_type: 'NDCAMT53L',
+  file_reference: "11111111A12006030329501800000014",
+  target_id: '11111111A1',
+  status: 'NEW'
+}
+```
 
-        response.hashes_match?
+Initialize a new instance of the client and pass the params hash
 
-        # You can also provide an optional parameter verbose:true
-        # if you want to see which hashes failed to verify.
+```ruby
+client = Sepa::Client.new params
+```
 
-        response.hashes_match?(verbose: true)
+Send request to bank
 
-* Check that the signature of the response is valid
+```ruby
+response = client.send_request
+```
 
-        response.signature_is_valid?
+### Interacting with the response
 
-* Extract the certificate from the response
+Make sure response is valid
 
-        # Will return an OpenSSL::X509::Certificate object
-        response.certificate
+```ruby
+response.valid?
+```
 
-* Check that the certificate is trusted against a root cert
+Get reponse content
 
-        # The root cert has to be of type OpenSSL::X509::Certificate
-        response.cert_is_trusted?(root_cert)
+```ruby
+response.content
+```
 
-### Verifying the application response
+### Downloading Nordea certificate
 
-1. Extract the application request from the request
+Define parameters hash for client
 
-        ar = response.application_request
+```ruby
+params = {
+  pin: '1234567890',
+  bank: :nordea,
+  command: :get_certificate,
+  customer_id: '11111111',
+  environment: 'TEST',
+  csr: "...your csr...",
+  service: 'service'
+}
+```
 
-* Check that the hashes match in the application response
+Initialize a new instance of the client and pass the params hash
 
-        ar.hashes_match?
+```ruby
+client = Sepa::Client.new params
+response = client.send_request
+```
 
-* Check that the signature of the application response is valid
+Get the certificates from the response
 
-        ar.signature_is_valid?
+```ruby
+response.content
+```
 
-* Extract the certificate from the application response
+### Downloading Danske bank certificates
 
-        # Will return an OpenSSL::X509::Certificate object
-        ar.certificate
+#### Bank's certificates
 
-* Check that the certificate is trusted against a root cert
+Define parameters hash for client
 
-        # The root cert has to be of type OpenSSL::X509::Certificate
-        ar.cert_is_trusted?(root_cert)
+```ruby
+params = {
+  bank: :danske,
+  target_id: 'Danske FI',
+  language: 'EN',
+  command: :get_bank_certificate,
+  bank_root_cert_serial: '1111110002',
+  customer_id: '360817',
+  environment: 'TEST'
+}
+```
 
-### For downloading Nordea certificate
+Initialize a new instance of the client and pass the params hash
 
-1. Require the gem:
+```ruby
+client = Sepa::Client.new params
+response = client.send_request
+```
 
-        require 'sepafm'
+Get the certificates from the response
 
-2. Define the hash that will be passed to the gem when initializing it:
+```ruby
+# Bank's encryption certificate
+response.bank_encryption_cert
 
-        params = {
-          bank: :nordea,
-          command: :get_certificate,
-          customer_id: '11111111',
-          environment: 'TEST',
-          csr_path: "path_to_your_local_csr_file", (OR csr_plain: "your csr in plain text format")
-          service: 'service'
-        }
+# Bank's signing certificate
+response.bank_signing_cert
 
-3. Initialize a new instance of the client and pass the params hash
+# Bank's root certificate
+response.bank_root_cert
+```
 
-        sepa_client = Sepa::Client.new(params)
-        sepa_client.call
+#### Own certificates
 
-4. Save the certificate from the response into a local file
+Define parameters hash
 
-### For downloading Danske bank certificates
+``` ruby
+params = {
+  bank: :danske,
+  enc_cert: danske_bank_enc_cert,
+  command: :create_certificate,
+  customer_id: '360817',
+  environment: 'customertest',
+  key_generator_type: 'software',
+  encryption_cert_pkcs10: danske_enc_cert_request,
+  signing_cert_pkcs10: danske_signing_cert_request,
+  pin: '1234'
+}
+```
 
-1. Require the gem:
+Initialize a new instance of the client and pass the params hash
 
-        require 'sepafm'
+```ruby
+client = Sepa::Client.new params
+response = client.send_request
+```
 
-2. Define the hash that will be passed to the gem when initializing it:
+Get the certificates from the response
 
-        params = {
-          bank: :danske,
-          target_id: 'Danske FI',
-          language: 'EN',
-          command: :get_bank_certificate,
-          bank_root_cert_serial: '1111110002',
-          customer_id: '360817',
-          environment: 'TEST',
-        }
+```ruby
+# Own encryption certificate
+response.own_encryption_cert
 
-3. Initialize a new instance of the client and pass the params hash
+# Own signing certificate
+response.own_signing_cert
 
-        sepa_client = Sepa::Client.new(params)
-        sepa_client.call
+# CA Certificate used for signing own certificates
+response.ca_certificate
+```
 
-4. Save the certificates from the response into a local file
-
-***
+---
 
 ### Parameter breakdown
 
-* bank : The bank you want to send the request to as a symbol. Either :nordea or :danske
-
-* private_key_plain: Your private key in plain text format
-
-* private_key_path: Path to your local private key file
-
-* cert_plain: Your certificate in plain text format.
-
-* cert_path: Path to your local certificate file
-
-* csr_plain: Your certificate signing request in plain text format
-
-* csr_path: Path to your local certificate signing request file
-
-* command: Either :download_file_list, :upload_file, :download_file, :get_user_info, :get_certificate or :get_bank_certificate, depending on what you want to do.
-
-* customer_id: Your personal id with the bank.
-
-* environment: Must be either PRODUCTION or TEST
-
-* status: For filtering stuff. Must be either NEW, DOWNLOADED or ALL
-
-* target_id: Some specification of the folder which to access in the bank.
-
-* language: Language must be either FI, EN or SV
-
-* file_type: File types to upload or download:
-
-  * LMP300 = Laskujen maksupalvelu (lähtevä)
-
-  * LUM2 = Valuuttamaksut (lähtevä)
-
-  * KTL = Saapuvat viitemaksut (saapuva)
-
-  * TITO = Konekielinen tiliote (saapuva)
-
-  * NDCORPAYS = Yrityksen maksut XML (lähtevä)
-
-  * NDCAMT53L = Konekielinen XML-tiliote (saapuva)
-
-  * NDCAMT54L = Saapuvat XML viitemaksu (saapuva)
-
-* content: The actual payload to send. The creation of this file may be supported by the client at some point.
-
-* file_reference: File reference for :download_file command
-
-* pin: Your personal pin-code provided by the bank
-
-* service: For testing value is service, otherwise ISSUER
-
-* bank_root_cert_serial: Serial number for Danske bank certificate download (1111110002)
-
-***
-
-### Parsing data from bank response xml
-Parsing based on specifications by Federation of Finnish Financial Services provided xml examples account statement [XML account statement](http://www.fkl.fi/teemasivut/sepa/tekninen_dokumentaatio/Dokumentit/FI_camt_053_sample.xml.xml) and debit credit notification [XML debit credit notification](http://www.fkl.fi/teemasivut/sepa/tekninen_dokumentaatio/Dokumentit/FI_camt_054_sample.xml.xml) and ISO20022 transaction reporting guide [ISO20022 Transaction reporting guide](http://www.fkl.fi/en/themes/sepa/sepa_documents/Dokumentit/ISO20022_Payment_Guide.pdf)
-* Hardcode wanted specs into app_response.rb methods get_account_statement_content/get_debit_credit_notification_content
-* Create new instance of ApplicationResponse
-* method get_account_statement_content takes a bank statement file (xml) as a parameter and returns selected info in a hash
-* method get_debit_credit_notification_content takes a debit credit notification file (xml) as a parameter and returns selected info in a hash
-* method animate_response takes a full application response xml as a parameter and parses data into objects, can be used to take out different formats of Content-field, without predefined parameter specs
+* **bank** - The bank you want to send the request to as a symbol. Either :nordea or :danske
+* **private_key** - Your private key in plain text format
+* **cert** - Your certificate in plain text format
+* **csr** - Your certificate signing request in plain text format
+* **command** - Must be one of:
+    * download_file_list
+    * upload_file
+    * download_file
+    * get_user_info
+    * get_certificate
+    * get_bank_certificate
+* **customer_id** - Your personal id with the bank.
+* **environment** - Must be either PRODUCTION or TEST
+* **status** - For filtering stuff. Must be either NEW, DOWNLOADED or ALL
+* **target_id** - Some specification of the folder which to access in the bank.
+* **language** - Language must be either FI, EN or SV
+* **file_type** - File types to upload or download:
+    * LMP300 = Laskujen maksupalvelu (lähtevä)
+    * LUM2 = Valuuttamaksut (lähtevä)
+    * KTL = Saapuvat viitemaksut (saapuva)
+    * TITO = Konekielinen tiliote (saapuva)
+    * NDCORPAYS = Yrityksen maksut XML (lähtevä)
+    * NDCAMT53L = Konekielinen XML-tiliote (saapuva)
+    * NDCAMT54L = Saapuvat XML viitemaksu (saapuva)
+* **content** - The payload to send.
+* **file_reference** - File reference for :download_file command
+* **pin** - Your personal pin-code provided by the bank
+* **service** - For testing value is service, otherwise ISSUER
+* **bank_root_cert_serial** - Serial number for Danske bank certificate download (1111110002)
+
+---
+
+## Upcoming features
+
+* Parse responses
+    * Bank-to-Customer Statement
+        * ISO standard "BankToCustomerStatementV02"
+        * XML schema "camt.053.001.02"
+    * Bank-to-Customer Debit/Credit Notification
+        * ISO standard "BankToCustomerDebitCreditNotificationV02"
+        * XML schma "camt.054.001.02"
+* Create payloads
+    * Customer-to-Bank Statement
+        * ISO standard "CustomerCreditTransferInitiationV03"
+        * XML schema "pain.001.001.03"
+
+---
 
 ## Contributing
 
 1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+1. Create your feature branch (`git checkout -b my-new-feature`)
+1. Commit your changes (`git commit -am 'Add some feature'`)
+1. Push to the branch (`git push origin my-new-feature`)
+1. Create new Pull Request
 
 ## License
 

data/Rakefile

@@ -2,9 +2,14 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.libs << 'lib/sepa'
-  t.test_files = FileList['test/sepa/*_test.rb']
+  t.libs << 'test'
+  t.test_files = FileList['test/sepa/**/*_test.rb']
   t.verbose = true
 end
 
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "bundle exec irb -I lib -r sepafm.rb"
+end
+
 task :default => :test