H003 schematic support

EBICS_REFERENCES.md

@@ -0,0 +1,169 @@
+# EBICS Documentation — Complete Reference
+
+> Last updated: 2026-03-05
+
+---
+
+## 1. Official Specifications (ebics.org)
+
+| Document | Link | Version | Language |
+|---|---|---|---|
+| **Specification main page** | https://www.ebics.org/en/technical-information/ebics-specification | V3.0.2 (current) | EN/DE/FR |
+| **XSD Schemas** | https://www.ebics.org/en/technical-information/ebics-schema | H003/H004/H005 | — |
+| **Implementation Guide** | https://www.ebics.org/en/technical-information/implementation-guide | All | EN/DE |
+| **BTF Mapping (BTD/BTU)** | https://www.ebics.org/en/technical-information/btf-mapping | H005 | EN/DE |
+| **Examples** | https://www.ebics.org/en/technical-information/examples | All | EN |
+| **Additional Standards** | https://www.ebics.org/en/technical-information/additional-standards | All | EN/DE |
+| **Change Requests (archive)** | https://www.ebics.org/en/technical-information/archive-ebics/change-requests | Historical | EN/DE |
+| **Passed CRs** | https://www.ebics.org/en/technical-information/maintain-advance/passed-crs | Maintenance | EN/DE |
+| **Technical News** | https://www.ebics.org/en/current-topics/technical-news | — | EN/DE |
+| **Archived Specifications** | https://www.ebics.org/en/technical-information/archive-ebics/specification | V2.4/2.5 | EN/DE |
+
+---
+
+## 2. Specification PDFs — Direct Download
+
+### Main Specification
+
+| Document | Link | Version |
+|---|---|---|
+| **EBICS V3.0 Spec (SIX)** | https://www.six-group.com/dam/download/banking-services/interbank-clearing/en/standardization/ebics/ebics_3_0.pdf | H005 / V3.0 |
+| **EBICS V3.0 Spec (Gitea mirror)** | https://gitea.szsolutions.ch/Mirror/odoo_account_ebics/raw/branch/15.0/account_ebics/doc/2017-03-29-EBICS_V_3.0-FinalVersion.pdf | H005 / V3.0 |
+| **EBICS V2.5 Spec (CFONB)** | https://www.cfonb.org/fichiers/20130612170023_6_4_EBICS_Specification_2.5_final_2011_05_16_2012_07_01.pdf | H004 / V2.5 |
+| **EBICS V2.4.2 Spec (CFONB)** | https://www.cfonb.org/fichiers/20130612170103_6_7_EBICS_Specification_2.4.2_final_2010_02_16.pdf | H003 / V2.4 |
+
+### Annexes & Supplements
+
+| Document | Link | Content |
+|---|---|---|
+| **Annex 1 — Return Codes** | https://www.cfonb.org/fichiers/20130612170037_6_5_EBICS_Annex1_ReturnCodes_final_16_05_2011_2012_07_01.pdf | All EBICS return codes |
+| **Annex 2 — Order Type Identifiers** | https://www.cfonb.org/fichiers/20140423153546_Annex_2_%E2%80%93_EBICS_Specification_april_2014.pdf | Order type identifiers |
+| **EBICS SC 2021** | https://www.cfonb.org/fichiers/20210420081014_EBICS_SC_2021.pdf | EBICS SC overview |
+
+### France Implementation Guides (CFONB)
+
+| Document | Link | Content |
+|---|---|---|
+| **IG CFONB V2.1.5 (FR)** | https://www.cfonb.org/fichiers/20141029101016_6_10_EBICS_IG_CFONB_VF_2_1_5_2014_06_23.pdf | France implementation guide |
+| **IG CFONB V2.1.4 (EN)** | https://www.cfonb.org/fichiers/20130612170302_6_16_EBICS_IG_CFONB_V2_1.4_english_version_2012_02_24.pdf | France implementation guide (English) |
+| **IG Annex 2 — File names** | https://www.cfonb.org/fichiers/20130612170321_6_17_EBICS_IG_V1.2._Annexe_2_File_names_VE_final_2010_01.pdf | File naming conventions |
+| **IG Annex A3.1 — Certificate error codes** | https://www.cfonb.org/fichiers/20130612170148_6_11_EBICS_IG_V1_1_Annexe_A3_1_Certificates_error_codes_2009_04.pdf | X.509 certificate error codes |
+| **EBICS test scenarios** | https://www.cfonb.org/fichiers/20130612170423_6_21_Proposition_tests_EBICS_V1_0_2009_05_15.pdf | Test scenarios |
+
+### BTF / BTD / BTU (EBICS 3.0)
+
+| Document | Link | Content |
+|---|---|---|
+| **File Format → BTF mapping (CFONB)** | https://www.cfonb.org/sites/www.cfonb.org/files/documents/Tables%20de%20correspondance%20File%20Format%20vers%20BTF-Business%20Transaction%20Format%20(EBICS%20v3.0%20et%20suivantes)%20.pdf | Order type → BTF mapping |
+| **BTF Parameters (konfipay wiki)** | https://wiki.konfipay.de/konfipay/btf-parameters-ebics-3-0 | BTF parameter reference |
+| **CPG — EBICS BTU, BTD and BTF** | https://www.cpg.de/en/ebics-btu-btd-and-btf/ | BTD/BTU/BTF explained |
+| **CPG — EBICS 3.0 innovations** | https://www.cpg.de/en/ebics-3-0/ | EBICS 3.0 overview |
+
+---
+
+## 3. Switzerland — SIX Group
+
+| Document | Link | Content |
+|---|---|---|
+| **Swiss Market Practice Guidelines EBICS 3.0 v1.3** | https://www.six-group.com/dam/download/banking-services/standardization/ebics/market-practice-guidelines-ebics3.0-v1.3-en.pdf | Swiss guidelines H005 |
+| **Swiss Market Practice Guidelines EBICS 3.0 v1.2** | https://www.six-group.com/dam/download/banking-services/standardization/ebics/market-practice-guidelines-ebics3.0-v1.2-en.pdf | Swiss guidelines H005 (older) |
+| **EBICS in Switzerland (overview)** | https://www.six-group.com/dam/download/banking-services/interbank-clearing/en/standardization/ebics/ebics.pdf | EBICS Switzerland overview |
+| **SIX EBICS page** | https://www.six-group.com/en/products-services/banking-services/payment-standardization/standards/ebics.html | SIX EBICS portal |
+
+---
+
+## 4. Germany — Deutsche Kreditwirtschaft / Bundesbank
+
+| Document | Link | Content |
+|---|---|---|
+| **DFÜ-Abkommen — Anlage 3 Datenformate V3.8** | http://www.bayernlb.de/internet/media/de/ir/downloads_1/zahlungsverkehr/richtlinien/2024-11-17_Anlage_3_Datenformate_V3.8.pdf | Data format specification |
+| **ebics.de — Datenformate** | https://www.ebics.de/de/datenformate | Data formats portal |
+| **DFÜ-Verfahren EBICS — DK** | https://die-dk.de/zahlungsverkehr/electronic-banking/dfu-verfahren-ebics/ | DK EBICS page |
+| **Verfahrensregeln EBICS 2025 (Bundesbank)** | https://www.bundesbank.de/resource/blob/964236/6f3129a9aab710eae9b2939e0021a7bc/472B63F073F071307366337C94F8C870/verfahrensregeln-ebics-2025-data.pdf | Procedural rules 2025 |
+| **Verfahrensregeln EBICS V3.9 (Bundesbank)** | https://www.bundesbank.de/resource/blob/764544/2bfc83ca09df0c7a4a53c96caec1ac55/mL/verfahrensregeln-ebics-3-9-data.pdf | Procedural rules V3.9 |
+| **Besondere Bedingungen EBICS 2024 (Bundesbank)** | https://www.bundesbank.de/resource/blob/925930/8b5c5b9da853666a3b1638b0005aa3e4/mL/besondere-bedingungen-ebics-2024-data.pdf | Special conditions |
+| **Deutsche Bank — Order Types (EN)** | https://www.deutsche-bank.de/dam/deutschebank/de/shared/pdf/ebics-dfu-explanation-of-order-type-identifiers-e.pdf | Order type reference (EN) |
+| **Deutsche Bank — Auftragsarten (DE)** | https://www.deutsche-bank.de/dam/deutschebank/de/shared/pdf/ub/ebics-dfue-erlaeuterungen-der-auftragsarten-d.pdf | Order type reference (DE) |
+
+---
+
+## 5. DFÜ-Abkommen — English Translation
+
+| Document | Link | Content |
+|---|---|---|
+| **DFÜ Agreement Appendix 3 (EN, Isabel)** | https://www.isabel.eu/content/dam/knowledge_base_ibs6/documents/en-US/Anlage_3_Datenformate_V29_engl.pdf | Data formats (English translation) |
+
+---
+
+## 6. Reference Implementations (source code)
+
+| Project | Link | Language | Versions |
+|---|---|---|---|
+| **ebics-client-php** | https://github.com/ebics-api/ebics-client-php | PHP | H003/H004/H005 |
+| **ebics-java-client** | https://github.com/ebics-java/ebics-java-client | Java | H004 |
+| **EBICS.php (Synap)** | https://github.com/Synap/EBICS.php | PHP | H003/H004 |
+| **node-ebics-client** | https://github.com/nicemann/node-ebics-client | Node.js | H004 |
+| **epics (railslove)** | https://github.com/railslove/epics | Ruby | H004 |
+| **epics (our fork)** | https://github.com/jplot/epics | Ruby | H003/H004/H005 |
+
+---
+
+## 7. Third-party References
+
+| Resource | Link | Content |
+|---|---|---|
+| **Wikipedia — EBICS** | https://en.wikipedia.org/wiki/Electronic_Banking_Internet_Communication_Standard | Overview |
+| **Wikipedia — DFÜ-Abkommen** | https://de.wikipedia.org/wiki/Abkommen_%C3%BCber_die_Datenfern%C3%BCbertragung_zwischen_Kunden_und_Kreditinstituten | DFÜ-Abkommen (DE) |
+| **Axway — EBICS standard** | https://docs.axway.com/bundle/EBICSClient_11_allOS_en_HTML5/page/the_ebics_standard.html | Axway reference |
+| **Axway — EBICS error codes** | https://docs.axway.com/bundle/TransferCFT_332_LocalAdministrationGuide_allOS_en_HTML5/page/Content/Prots/French/EBICS/r_ebics_error_mess_codes.htm | Error codes (full list) |
+| **IBM — EBICS return codes** | https://www.ibm.com/docs/SS3JSW_5.2.0/com.ibm.help.ebics_client_user_525.doc/EBICS_Client_returncodes_events.html | IBM return codes |
+| **BL Banking — EBICS errors** | https://www.blbanking.de/webhelp/topic/de.businesslogics.banking.web/help/html/appendix/faq-ebicserrors.html | BL Banking error messages |
+| **konfipay — BTF parameters** | https://wiki.konfipay.de/konfipay/btf-parameters-ebics-3-0 | BTF parameters |
+| **Sage XRT — EBICS 3.0 Guide (FR)** | https://sxbe-onlinehelp.sage.com/PDF/SXBE/SXBE.12.1.EBICS.3.0.UserGuide_FR.pdf | Sage user guide |
+| **UBS — EBICS 3.0** | https://www.ubs.com/ch/en/corporates/payment-solutions/cash-management/connection-ubs/ebics.html | UBS EBICS 3.0 page |
+| **BCV — EBICS parameters factsheet** | https://www.bcv.ch/content/dam/bcv/brochure---flyer/44-516e_Fiche-technique-BCV-connect_web.pdf | BCV technical factsheet |
+
+---
+
+## 8. Local XSD Schemas in This Project
+
+XSD schemas are stored in `spec/xsd/`:
+
+```
+spec/xsd/
+├── H003/
+│   └── (H003 schemas)
+├── H004/
+│   ├── ebics_H004.xsd              (H004 root schema)
+│   ├── ebics_hev.xsd               (HEV protocol)
+│   ├── ebics_keymgmt_request_H004.xsd
+│   ├── ebics_keymgmt_response_H004.xsd
+│   ├── ebics_orders_H004.xsd       (89K — order types)
+│   ├── ebics_request_H004.xsd
+│   ├── ebics_response_H004.xsd
+│   ├── ebics_signature.xsd         (S001)
+│   ├── ebics_types_H004.xsd        (86K — types)
+│   └── xmldsig-core-schema.xsd
+└── H005/
+    ├── ebics_H005.xsd              (H005 root schema)
+    ├── ebics_hev.xsd
+    ├── ebics_keymgmt_request_H005.xsd
+    ├── ebics_keymgmt_response_H005.xsd
+    ├── ebics_orders_H005.xsd
+    ├── ebics_request_H005.xsd
+    ├── ebics_response_H005.xsd
+    ├── ebics_signature_S002.xsd    (S002 — A005)
+    ├── ebics_types_H005.xsd
+    └── xmldsig-core-schema.xsd
+```
+
+---
+
+## Notes
+
+- Specifications on **ebics.org** require accepting terms of use before downloading
+- Current version: **V3.0.2** (valid since December 30, 2022)
+- Last BTF list update: **October 23, 2024**
+- **DFÜ-Abkommen Anlage 3** is the reference document for data formats in Germany
+- X/Y/Z prefixed order types = bank-individual (not core EBICS)
+- FUL/FDL = core EBICS H003/H004, removed in H005 (replaced by BTU/BTD)

README.md

@@ -6,7 +6,8 @@
 EPICS is a ruby implementation of the [EBICS](https://www.ebics.org/) (Electronic Banking Internet
 Communication Standard).
 
-It supports EBICS 2.5.
+It supports EBICS 2.4, 2.5 and 3.0.
+The default setting is 2.5.
 
 The client supports the complete initialization process comprising INI, HIA and HPB including the
 INI letter generation. It offers support for the most common download and upload order types

lib/epics.rb

@@ -10,15 +10,19 @@
 require 'securerandom'
 require 'time'
 require "epics/version"
-require "epics/key"
+require "epics/keyring"
+require "epics/signature"
+require "epics/signature_algorithm"
+require "epics/signature_algorithm/base"
+require "epics/signature_algorithm/rsa"
+require "epics/signature_algorithm/rsapss"
+require "epics/signature_algorithm/rsapkcs1"
 require "epics/response"
 require "epics/error"
 require 'epics/letter_renderer'
-require "epics/middleware/xmlsig"
 require "epics/middleware/parse_ebics"
 require "epics/generic_request"
 require "epics/generic_upload_request"
-require "epics/header_request"
 require "epics/azv"
 require "epics/hpb"
 require "epics/hkd"
@@ -59,15 +63,36 @@
 require "epics/hia"
 require "epics/ini"
 require "epics/hev"
-require "epics/signer"
-require "epics/x_509_certificate"
 require "epics/client"
 
+require 'epics/builders'
+require 'epics/crypt'
+require 'epics/factories'
+require 'epics/handlers'
+require 'epics/services'
+
 I18n.load_path += Dir[File.join(File.dirname(__FILE__), 'letter/locales', '*.yml')]
 
 module Epics
   DEFAULT_PRODUCT_NAME = 'EPICS - a ruby ebics kernel'
   DEFAULT_LOCALE = :de
+
+  class VersionSupportError < StandardError
+    attr_reader :version
+
+    def initialize(version, direction = 'above')
+      @version = version
+      message = case direction
+      when 'above'
+        "Supported from version #{version}"
+      when 'below'
+        "Support for versions below #{version}"
+      else
+        raise ArgumentError, "Invalid direction: #{direction}. Use 'above' or 'below'."
+      end
+      super(message)
+    end
+  end
 end
 
 Ebics = Epics

lib/epics/azv.rb

@@ -1,13 +1,6 @@
 class Epics::AZV < Epics::GenericUploadRequest
-  def header
-    client.header_request.build(
-      nonce: nonce,
-      timestamp: timestamp,
-      order_type: 'CD1',
-      order_attribute: 'OZHNN',
-      order_params: {},
-      num_segments: 1,
-      mutable: { TransactionPhase: 'Initialisation' }
-    )
+  def to_xml
+    builder = request_factory.create_azv(document_digest, transaction_key)
+    builder.to_xml
   end
 end

lib/epics/b2b.rb

@@ -1,13 +1,6 @@
 class Epics::B2B < Epics::GenericUploadRequest
-  def header
-    client.header_request.build(
-      nonce: nonce,
-      timestamp: timestamp,
-      order_type: 'B2B',
-      order_attribute: 'OZHNN',
-      order_params: {},
-      num_segments: 1,
-      mutable: { TransactionPhase: 'Initialisation' }
-    )
+  def to_xml
+    builder = request_factory.create_b2b(document_digest, transaction_key)
+    builder.to_xml
   end
 end

lib/epics/bka.rb

@@ -1,17 +1,6 @@
 class Epics::BKA < Epics::GenericRequest
-  def header
-    client.header_request.build(
-      nonce: nonce,
-      timestamp: timestamp,
-      order_type: 'BKA',
-      order_attribute: 'DZHNN',
-      order_params: {
-        DateRange: {
-          Start: options[:from],
-          End: options[:to]
-        }
-      },
-      mutable: { TransactionPhase: 'Initialisation' }
-    )
+  def to_xml
+    builder = request_factory.create_bka(options[:from], options[:to])
+    builder.to_xml
   end
 end

lib/epics/builders.rb

@@ -0,0 +1,13 @@
+module Epics::Builders
+end
+
+require 'epics/builders/body_builder'
+require 'epics/builders/data_encryption_info_builder'
+require 'epics/builders/data_transfer_builder'
+require 'epics/builders/header_builder'
+require 'epics/builders/mutable_builder'
+require 'epics/builders/order_details_builder'
+require 'epics/builders/request_builder'
+require 'epics/builders/static_builder'
+require 'epics/builders/transfer_receipt_builder'
+require 'epics/builders/xml_builder'

lib/epics/builders/body_builder.rb

@@ -0,0 +1,6 @@
+module Epics::Builders::BodyBuilder
+end
+
+require 'epics/builders/body_builder/base'
+require 'epics/builders/body_builder/v2'
+require 'epics/builders/body_builder/v3'

lib/epics/builders/body_builder/base.rb

@@ -0,0 +1,26 @@
+class Epics::Builders::BodyBuilder::Base
+  def initialize
+    Nokogiri::XML::Builder.new do |xml|
+      @xml = xml
+      xml.body do
+        yield self
+      end
+    end
+  end
+
+  def add_data_transfer
+    raise NotImplementedError
+  end
+
+  def add_transfer_receipt
+    instance = Epics::Builders::TransferReceiptBuilder.new do |instance|
+      yield instance
+    end
+    @xml.parent.add_child(instance.doc)
+    self
+  end
+
+  def doc
+    @xml.doc.root
+  end
+end

lib/epics/builders/body_builder/v2.rb

@@ -0,0 +1,9 @@
+class Epics::Builders::BodyBuilder::V2 < Epics::Builders::BodyBuilder::Base
+  def add_data_transfer
+    instance = Epics::Builders::DataTransferBuilder::V2.new do |instance|
+      yield instance
+    end
+    @xml.parent.add_child(instance.doc)
+    self
+  end
+end

lib/epics/builders/body_builder/v3.rb

@@ -0,0 +1,9 @@
+class Epics::Builders::BodyBuilder::V3 < Epics::Builders::BodyBuilder::Base
+  def add_data_transfer
+    instance = Epics::Builders::DataTransferBuilder::V3.new do |instance|
+      yield instance
+    end
+    @xml.parent.add_child(instance.doc)
+    self
+  end
+end

lib/epics/builders/data_encryption_info_builder.rb

@@ -0,0 +1,28 @@
+class Epics::Builders::DataEncryptionInfoBuilder
+  def initialize
+    @crypt_service = Epics::Services::CryptService.new
+    Nokogiri::XML::Builder.new do |xml|
+      @xml = xml
+      xml.DataEncryptionInfo(authenticate: true) do
+        yield self
+      end
+    end
+  end
+
+  def add_encryption_pubkey_digest(keyring, algorithm = 'sha256')
+    certificate_digest = @crypt_service.calculate_digest(keyring.bank_encryption.key, algorithm)
+    attribues = { Version: keyring.bank_encryption.version, Algorithm: "http://www.w3.org/2001/04/xmlenc##{algorithm}" }
+    @xml.EncryptionPubKeyDigest Base64.strict_encode64(certificate_digest), **attribues
+    self
+  end
+
+  def add_transaction_key(transaction_key, keyring)
+    transaction_key_encrypted = @crypt_service.encrypt_transaction_key(keyring.bank_encryption.key, transaction_key)
+    @xml.TransactionKey Base64.strict_encode64(transaction_key_encrypted)
+    self
+  end
+
+  def doc
+    @xml.doc.root
+  end
+end