H003 schematic support by jplot · Pull Request #154 · railslove/epics

jplot · 2024-08-27T08:21:51Z

Testing overview:

Order Type	H003	H004	H005	Description
AZV	❌	✅	❌
B2B	❌	✅	❌
BTD	❌	❌	✅
BTU	❌	❌	✅
BKA	❌	✅	❌
C2S	❌	✅	❌
C5N	❌	✅	❌
C52	❌	✅	✅
C53	❌	✅	✅
C54	❌	✅	✅
CCS	❌	✅	❌
CCT	❌	✅	✅	Used to initiate the credit transfer per Single Euro Payments Area (SEPA) specification set by the European Payment Council or Die Deutsche Kreditwirtschaft (DK).
CD1	❌	✅	❌	Uploads a SEPA Direct Debit document of type COR1
CDB	❌	✅	✅	Uploads a SEPA Direct Debit document of type B2B
CDD	❌	✅	✅	Uploads a SEPA Direct Debit document of type CORE
CDS	❌	✅	❌
CDZ	❌	✅	❌
CIP	❌	✅	✅
CRZ	❌	✅	❌
FDL	✅	✅	✅
FUL	❌	❌	❌
H3K	❌	❌	❌
HAA	✅	✅	✅	Download retrievable order types
HAC	✅	✅	✅	Used to download customer acknowledgment (XML format)
HEV	✅	✅	✅	Download of supported EBICS versions
HIA	✅	✅	✅	Used to transmit user public certificates for identification, authentication and encryption within the framework of subscriber initialization
HKD	✅	✅	✅	Retrieve customer's customer and subscriber information
HPB	✅	✅	✅	Fetch your bank’s public keys
HPD	✅	✅	✅	Download bank parameters
HTD	✅	✅	✅	Retrieve subscriber’s customer and subscriber information
INI	✅	✅	✅	Used in subscriber initialization. Sends the bank-technical public certificate of the user to the EBICS Banking Server
PTK	✅	✅	✅	Customer usage report in text format
SPR	❌	❌	❌
STA	❌	✅	✅	Statements in MT940 format
VMK	❌	✅	✅	Customer usage report in XML format
WSS	❌	✅	❌
XCT	❌	✅	❌
XDS	❌	✅	❌
XE2	❌	✅	✅
XE3	❌	✅	✅
XEK	❌	❌	✅
Z52	❌	✅	✅
Z53	❌	✅	✅
Z54	❌	✅	✅
ZSR	❌	❌	✅
YCT	❌	❌	✅

jplot · 2024-09-26T12:32:58Z

Hi @tobischo,
You can start reviewing the code.
I'm waiting to finalize tests with our financial partner before putting the PR on ready.

tobischo · 2024-09-28T06:17:31Z

I am really excited to see that you also added EBICS 3 🤩

I had that on my list as a potential followup after your changes.
Will review as soon as I have time and also start testing whether the 2.5 cases still work that I am responsible
I might have access on a test API to 3.0 as well 🤔

tobischo

Overall this looks great.

I haven't tested it yet against an EBICS API, so I cannot speak to whether it is still working (yet).

I think it is missing some test cases, e.g. around the signature algorithm handling and using a different EBICS version

tobischo · 2024-09-28T06:28:16Z

README.md

 Communication Standard).

-It supports EBICS 2.5.
+It supports EBICS 2.4, 2.5 and 3.0.


I think the readme could reflect which one is the default when initializing a new or existing client and how to work with another version

lib/epics/header_request.rb

spec/signature_algorithm/rsa_pss_spec.rb

frantisekrokusek · 2024-12-31T13:59:50Z

@jplot do you need help finalizing this ?

jplot · 2025-01-02T11:02:59Z

@jplot do you need help finalizing this ?

I don't have a sandbox environment to test end-to-end operation.

tobischo · 2025-01-10T10:44:32Z

I haven't checked if it supports EBICS 2.4, but https://iso20022test.credit-suisse.com/login provides a testing environment for communication through EBICS

janz93 · 2025-03-11T10:26:16Z

Sadly the credit-suisse test ox does not work for ebics 3.0

Es gibt keine Testumgebung; insbesondere eignet sich der
EBICS-3.0-Zugang der Credit Suisse ISO 20022 Test
Platform nicht zum Testen von Direct Link

https://www.credit-suisse.com/media/assets/private-banking/docs/ch/unternehmen/unternehmen-unternehmer/umstellung-von-ebics-25-auf-30-de.pdf

jplot · 2025-03-27T10:51:51Z

@tobischo I have reallocated my work time to this project full-time, with the aim of integrating the features related to versions 'H003' and 'H005'.
To ensure compatibility with version 'H005', it was imperative to refactor the way we generate XML.

tobischo · 2025-03-27T18:38:45Z

Amazing 😃
Let me know when you think it is testable and I will try to at least test the data retrieval cases.
I am not sure I can promise testing the upload part 😅

frantisekrokusek · 2025-04-09T15:03:09Z

@jplot We have some mandates with H003 servers so we can also do the testing part for you 😉

jplot · 2025-04-18T09:03:34Z

@frantisekrokusek If you have the possibility of writing more complete tests on the main branch, this would allow me to guarantee the integrity of the new system.

jplot · 2025-04-28T16:38:29Z

For version H003, I can only confirm that FDL, HAA, HAC, HEV, HIA, HKD, HPB, HPD, HTD, INI, PTK are supported.

frantisekrokusek · 2025-05-13T09:43:57Z

@jplot we just finished our testing phase on our fork
master...pennylane-hq:epics:master

We have successfully initialized those French banks but only tested INI/HIA/HPB/FDL commands because our mandates do not have access to other commands.

jplot · 2025-06-18T14:05:57Z

jplot · 2025-06-18T14:21:06Z

Key Technical Points for H003 and H005 Versions

AuthSignature: We've observed that the AuthSignature function isn't working correctly on version H003. An investigation is needed to resolve this issue.
X.509 Certificate Generation: The implementation of X.509 certificate generation will become mandatory for version H005. Therefore, we must ensure this functionality is properly integrated.
Signature Functions (EMSAs): For version H005, the emsaPssEncode (reference A006) and emsaPkcs1V15Encode (reference A005) signature functions are missing. Their development is crucial for compliance and security.

jplot · 2026-03-03T18:49:50Z

I'll take some time this week to update the branch, look into leveraging the X509 Certificate support, and wrap up the remaining items.

Replaces the legacy header_request.build approach with the versioned factory pattern (V25: build_download_request, V3: BTD with PSR/pain.002). Adds z01 to ORDER_TYPES registry and updates spec with shared examples.

Replaces the legacy header_request.build approach with the versioned factory pattern. Adds add_ful_order_params to OrderDetailsBuilder for FileFormat support, and makes build_upload_request accept a block for custom order params. Updates spec with shared examples.

- Fix V2 factory: %w[btd btu] instead of ['btd btu'] so create_btd and create_btu properly raise VersionSupportError - V3 Z01: add service_option CH003GEN per SIX Group spec - V3 FUL: raise VersionSupportError since FUL doesn't exist in H005

Add shared examples for receipt, transfer, FDLOrderParams, and FULOrderParams phases. Apply H004 structural validation to all 30 order types covering init, transfer, and receipt phases as applicable.

Rename 'a valid H004 ...' shared examples to 'a valid ebicsRequest ...' with an ebics_version parameter (default 'H004') to support both H003 and H004 structural validation from the same test definitions. Add H003 structural tests for the 8 order types that already support it: HKD, HPD, HTD, PTK (init), HAA, HAC (init + receipt), STA, FDL (receipt).

Add pending H003 init blocks for downloads (BKA, C52-C54, C5N, VMK, WSS, Z01, Z52-Z54, CDZ, CRZ, STA) and uploads (CCT, B2B, CD1, CDB, CDD, CIP, XE2, XE3, AZV, C2S, CCS, FUL). Add active H003 transfer blocks for all uploads since transfer XML is version-agnostic. Fix FDL: remove incorrect H003 pending markers since FDL already supports H003 through the factories/builders architecture.

Move build_download_request, build_upload_request, and all 27 create_xxx methods from V25 up to V2, making them available to both V24 (H003) and V25 (H004). Fix V24 add_order_type to support OZHNN for uploads with electronic signature. Remove duplicate V24 initialize. V24 and V25 now differ only by namespace (H003/H004) and OrderID (mandatory in H003, absent in H004).

Remove Epics::X509Certificate in favor of Epics::Crypt::X509 which now provides data, fingerprint and to_pem. Certificates are assigned directly on Signature objects via the keyring instead of being stored separately on the client. Remove x_509_certificates_content, x_509_certificate(type) and x_509_certificate_hash(type) from Client. Remove dead x509_data_xml from GenericRequest. Update OrderDataHandler, LetterRenderer and ini_with_certs template to use certificates from signatures.

jplot · 2026-03-04T18:10:02Z

Would appreciate if folks could test this branch against their EBICS connections to confirm H003 and H004 both work as expected. Any feedback welcome!

- Add auto-generated X.509 certificates for H005 test clients - Implement CryptService.sign() with RSA-PSS (A006) and PKCS1v15 (A005) - Add BTD mappings for BKA, C5N, CDZ, CRZ downloads in V3 factory - Add BTU mappings for AZV, B2B, CCS, CDS, C2S uploads in V3 factory - Add VersionSupportError for FDL, CD1, WSS, XDS in H005 - Fix missing AuthSignature in V3 create_btd - Add H005 structural shared examples (header, download, upload, receipt, transfer) - Remove all H005 pending tests and replace with active structural tests - Override AZV#to_xml to use create_azv (separate from CD1 in H005)

Cover all CryptService public methods (sign A005/A006, encrypt, AES round-trip, transaction key encryption, hash, digest calculation, certificate fingerprint) and DigestResolver behavior differences between V2 (key-based) and V3 (certificate-based).

Test XmlBuilder (V24/V25/V3 namespaces and container types), OrderDetailsBuilder (V2 OrderType/OrderAttribute vs V3 AdminOrderType/ BTDOrderParams/BTUOrderParams), StaticBuilder, MutableBuilder, DataTransferBuilder (V2 no-op vs V3 DataDigest/AdditionalOrderInfo), DataEncryptionInfoBuilder, HeaderBuilder, BodyBuilder, and TransferReceiptBuilder.

Test UserSignatureHandler V2 (S001) vs V3 (S002), OrderDataHandler V24/V25 (PubKeyValue with RSA material) vs V3 (X509Data, no PubKeyValue), and AuthSignatureHandler (digest, signature verification, C14N) across all three EBICS versions.

Test base factory methods (HEV, INI, HIA, HPB, transfers, admin orders), V2 download/upload patterns with OrderType/OrderAttribute/OrderID, V3 BTD/BTU patterns with AdminOrderType and service descriptors, and VersionSupportError boundaries between protocol versions.

Test version validation, key slot accessors, key serialization round-trip (dump/reload with AES-256-CBC encryption), Client.setup key generation (A005/A006, X002, E002), next_order_id overflow, and urn_schema per protocol version.

Signer was only used by the XMLSIG Faraday middleware which has been replaced by AuthSignatureHandler signing directly during request construction in the factories.

XCT now delegates to request_factory.create_azv like all other order types instead of using the legacy HeaderRequest monolithic builder. HeaderRequest has no remaining consumers and is removed along with its require and Client#header_request accessor.

AZV overrides to_xml completely and uses create_azv (not create_cd1), so inheriting from CD1 was misleading. AZV and CD1 are unrelated order types (international payment vs SEPA COR1 direct debit).

janz93 · 2026-03-04T20:33:01Z

@jplot nice work!
I'll test it within the next two days and provide you some feedback :)

CDS: SEPA Direct Debit without ES (DZHNN), BTU with SDD/BIL/pain.008 XCT: International payment alias for AZV (CD1 in V2, XCT/dtazv in V3)

XCT: add scope 'DE' assertion (matching AZV which already had it) CDD: add scope 'GLB' assertion for SEPA Direct Debit Core

The passphrase for key encryption/decryption is stored on Client, not on Keyring. This attribute was never used anywhere in production.

Include xmlns:xsi namespace declaration and xsi:schemaLocation attribute on all H003/H004/H005 request root elements (ebicsRequest, ebicsUnsecuredRequest, ebicsNoPubKeyDigestsRequest, ebicsUnsignedRequest). Each version points to its official XSD: - H003: http://www.ebics.org/H003/ebics_H003.xsd - H004: http://www.ebics.org/H004/ebics_H004.xsd - H005: http://www.ebics.org/H005/ebics_H005.xsd Update fixtures and auth signature test values to reflect the new canonical XML content (C14N inclusive includes ancestor namespaces).

Comprehensive reference file with links to official EBICS specifications, XSD schemas, implementation guides, BTF/BTD/BTU documentation, and country-specific resources (France, Switzerland, Germany).

The ini.erb template now handles both certificate and RSA key display using conditionals, eliminating the need for a separate ini_with_certs.erb.

lib/epics/letter_renderer.rb

CLAassistant · 2026-03-06T09:06:39Z

All committers have signed the CLA.

jplot force-pushed the h003-a005 branch from cffec95 to 1fcb434 Compare August 28, 2024 13:10

jplot force-pushed the h003-a005 branch from 1fcb434 to 39bb1db Compare September 4, 2024 13:54

jplot force-pushed the h003-a005 branch from 3355f09 to 0d4cb6b Compare September 25, 2024 13:54

jplot force-pushed the h003-a005 branch from cbb2490 to d8e35b4 Compare September 26, 2024 15:10

tobischo requested changes Sep 28, 2024

View reviewed changes

jplot force-pushed the h003-a005 branch from 6ea5cbc to 8dc00a5 Compare January 2, 2025 11:21

tobischo mentioned this pull request Feb 26, 2025

Support EPICS 3.0 #164

Open

jplot force-pushed the h003-a005 branch 2 times, most recently from f688bfb to db2cd7d Compare March 24, 2025 16:09

bonflintstone mentioned this pull request May 19, 2025

Add support for Real-time notifications railslove/ebicsbox#322

Open

tobischo mentioned this pull request Jun 27, 2025

Support X509Certificate in INI and HIA request #168

Merged

jplot added 4 commits March 4, 2026 18:34

Adds h003 schematic support

7643a26

Adds a005 signature support

c32fdf8

Adds h005 schematic support

3a5eb7f

Fixes after code review

0737966

jplot added 9 commits March 4, 2026 18:38

Adds early support for version H005

cf9b42f

Migrate Z01 order type to factories/builders architecture

544acde

Replaces the legacy header_request.build approach with the versioned factory pattern (V25: build_download_request, V3: BTD with PSR/pain.002). Adds z01 to ORDER_TYPES registry and updates spec with shared examples.

Add comprehensive H004 structural tests for all order types and phases

e3ae911

Add shared examples for receipt, transfer, FDLOrderParams, and FULOrderParams phases. Apply H004 structural validation to all 30 order types covering init, transfer, and receipt phases as applicable.

jplot force-pushed the h003-a005 branch from 9daf41d to 9ca9e40 Compare March 4, 2026 17:42

jplot added 9 commits March 4, 2026 20:16

Add unit tests for all handler classes

00e39ac

Test UserSignatureHandler V2 (S001) vs V3 (S002), OrderDataHandler V24/V25 (PubKeyValue with RSA material) vs V3 (X509Data, no PubKeyValue), and AuthSignatureHandler (digest, signature verification, C14N) across all three EBICS versions.

Remove dead Signer class

6dc0516

Signer was only used by the XMLSIG Faraday middleware which has been replaced by AuthSignatureHandler signing directly during request construction in the factories.

Fix AZV to inherit from GenericUploadRequest instead of CD1

9066751

AZV overrides to_xml completely and uses create_azv (not create_cd1), so inheriting from CD1 was misleading. AZV and CD1 are unrelated order types (international payment vs SEPA COR1 direct debit).

jplot added 6 commits March 4, 2026 22:00

Add specs for CDS and XCT order types

c157731

CDS: SEPA Direct Debit without ES (DZHNN), BTU with SDD/BIL/pain.008 XCT: International payment alias for AZV (CD1 in V2, XCT/dtazv in V3)

Add missing scope assertions in H005 specs for XCT and CDD

ad8b5d9

XCT: add scope 'DE' assertion (matching AZV which already had it) CDD: add scope 'GLB' assertion for SEPA Direct Debit Core

Remove unused password attribute from Keyring

4e41179

The passphrase for key encryption/decryption is stored on Client, not on Keyring. This attribute was never used anywhere in production.

Add EBICS documentation references

54f4638

Comprehensive reference file with links to official EBICS specifications, XSD schemas, implementation guides, BTF/BTD/BTU documentation, and country-specific resources (France, Switzerland, Germany).

Merge INI letter templates into a single conditional template

1059607

The ini.erb template now handles both certificate and RSA key display using conditionals, eliminating the need for a separate ini_with_certs.erb.

janz93 reviewed Mar 6, 2026

View reviewed changes

lib/epics/letter_renderer.rb Outdated Show resolved Hide resolved

Update lib/epics/letter_renderer.rb

19c3589

Conversation

jplot commented Aug 27, 2024 • edited by janz93 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jplot commented Sep 26, 2024

Uh oh!

tobischo commented Sep 28, 2024

Uh oh!

tobischo left a comment

Choose a reason for hiding this comment

Uh oh!

tobischo Sep 28, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

frantisekrokusek commented Dec 31, 2024

Uh oh!

jplot commented Jan 2, 2025

Uh oh!

tobischo commented Jan 10, 2025

Uh oh!

janz93 commented Mar 11, 2025

Uh oh!

jplot commented Mar 27, 2025

Uh oh!

tobischo commented Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

frantisekrokusek commented Apr 9, 2025

Uh oh!

jplot commented Apr 18, 2025

Uh oh!

jplot commented Apr 28, 2025

Uh oh!

frantisekrokusek commented May 13, 2025

Uh oh!

jplot commented Jun 18, 2025

Uh oh!

jplot commented Jun 18, 2025

Uh oh!

jplot commented Mar 3, 2026

Uh oh!

jplot commented Mar 4, 2026

Uh oh!

janz93 commented Mar 4, 2026

Uh oh!

Uh oh!

CLAassistant commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jplot commented Aug 27, 2024 •

edited by janz93

Loading

tobischo commented Mar 27, 2025 •

edited

Loading

CLAassistant commented Mar 6, 2026 •

edited

Loading