EBICS Protocol

Comprehensive guide to EBICS protocol versions, message structures, and communication patterns.

This document covers the EBICS protocol versions, message structures, and communication patterns supported by the fourbics Client.

Supported Protocol Versions

The client supports all four EBICS protocol versions with full backwards compatibility:

Version	EBICS Spec	XML Namespace	Key Features
H006	V3.0.2	`urn:org:ebics:H006`	BTF, A006 signatures, latest security
H005	V3.0	`urn:org:ebics:H005`	BTF, A006 signatures, ISO 20022
H004	V2.5	`urn:org:ebics:H004`	Legacy FUL/FDL, A005 signatures
H003	V2.4	`http://www.ebics.org/H003`	Legacy, different namespace format

Version Differences

┌──────────────────────────────────────────────────────────────────────────────┐
│                        PROTOCOL VERSION COMPARISON                           │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Feature                │ H003/H004          │ H005/H006                     │
│  ───────────────────────┼────────────────────┼───────────────────────────────│
│  Business Orders        │ FUL/FDL            │ BTU/BTD with BTF parameters   │
│  Signature Algorithm    │ A005 (PKCS#1)      │ A006 (RSASSA-PSS)             │
│  Order Identification   │ 3-letter codes     │ BTF service + scope + option  │
│  Namespace Format       │ http:// (H003)     │ urn:org:ebics:Hxxx            │
│  ISO 20022 Support      │ Limited            │ Full support                  │
│  Certificate Init       │ Not supported      │ H3K supported                 │
│  Complementary Sigs     │ Not supported      │ H006 only (CR-EB-22-05)       │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

H006 Specific Features

Complementary Signatures (CR-EB-22-05)

H006 introduces Complementary Signatures, a feature originally developed for Austrian banks but available internationally. This extends the traditional signature class model with additional authorization combinations.

┌──────────────────────────────────────────────────────────────────────────────┐
│                      COMPLEMENTARY SIGNATURES (H006)                         │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Traditional Model (H003-H005):                                              │
│  ─────────────────────────────                                               │
│  • E = Single signature (executes alone)                                     │
│  • A = First signature (needs A or B)                                        │
│  • B = Second signature (needs A)                                            │
│  • T = Transport only (cannot authorize)                                     │
│                                                                              │
│  Extended Model (H006 with Complementary Signatures):                        │
│  ────────────────────────────────────────────────────                        │
│  • Allows bank-defined signature class combinations                          │
│  • Supports complex multi-level authorization schemes                        │
│  • Enables role-based signing hierarchies                                    │
│  • Configurable per order type and amount threshold                          │
│                                                                              │
│  Example: Austrian Banking Requirements                                      │
│  ───────────────────────────────────────                                     │
│  • Orders up to €10,000: Single authorized signer                            │
│  • Orders €10,000-€50,000: Two signers from Group A                          │
│  • Orders over €50,000: One Group A + one Group B signer                     │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

H005 vs H006 Comparison

Feature	H005	H006
EBICS Specification	V3.0	V3.0.2
BTF Support	Yes	Yes
A006 Signatures	Yes	Yes
Complementary Signatures	No	Yes
XML Namespace	`urn:org:ebics:H005`	`urn:org:ebics:H006`

Banks may support H006 while not enabling Complementary Signatures. Check the HPD response for feature availability.

Order Types

Administrative Orders (24 types)

Key Management

Order	Name	Purpose	Requires Auth
HEV	Host EBICS Version	Query supported protocol versions	No
INI	Initialize	Submit signature public key	No (unsecured)
HIA	Host Init Agreement	Submit auth + encryption keys	No (unsecured)
H3K	3-Key Init	Certificate-based initialization (H005/H006)	No
HPB	Host Public Keys	Download bank's public keys	Yes
SPR	Suspend	Suspend subscriber	Yes
PUB	Public Key Update	Update signature key	Yes
HCA	Host Certificate Auth	Update auth + encryption keys	Yes
HCS	Host Certificate Sign	Update all three keys	Yes

Information Retrieval

Order	Name	Purpose
HAA	Available Order Types	List supported order types
HPD	Host Parameters	Bank parameters (recovery support, etc.)
HKD	Customer Data	Partner info, accounts, users
HTD	Subscriber Data	User permissions, signature classes
HAC	Customer Acknowledgement	Acknowledgement data

VEU (Distributed Electronic Signature)

Order	Name	Purpose
HVU	VEU Overview	List pending signatures (unsigned)
HVZ	VEU Overview Signed	List pending signatures (signed)
HVD	VEU Detail	Get specific order details
HVT	VEU Transaction	Get transaction for signing
HVE	VEU Signature	Submit signature
HVS	VEU Cancel	Cancel signature request

Business Transactions

Order	Version	Purpose
BTU	H005/H006	Business Transaction Upload (with BTF)
BTD	H005/H006	Business Transaction Download (with BTF)
FUL	H003/H004	File Upload (legacy)
FDL	H003/H004	File Download (legacy)

XML Message Structure

Request Types

EBICS uses four different request envelope types:

1. ebicsUnsecuredRequest (INI, HIA)

Used for initial key submission before authentication is established:

<?xml version="1.0" encoding="UTF-8"?>
<ebicsUnsecuredRequest xmlns="urn:org:ebics:H006"
                       Version="H006"
                       Revision="1">
    <header authenticate="true">
        <static>
            <HostID>BANKHOST</HostID>
            <PartnerID>PARTNER01</PartnerID>
            <UserID>USER001</UserID>
            <Product Language="en">fourbics Client 1.0</Product>
            <OrderDetails>
                <AdminOrderType>INI</AdminOrderType>
            </OrderDetails>
            <SecurityMedium>0000</SecurityMedium>
        </static>
        <mutable />
    </header>
    <body>
        <DataTransfer>
            <OrderData>
                <!-- Base64-encoded, compressed key data -->
            </OrderData>
        </DataTransfer>
    </body>
</ebicsUnsecuredRequest>

2. ebicsNoPubKeyDigestsRequest (HPB)

Used when bank key digests are not yet available:

<?xml version="1.0" encoding="UTF-8"?>
<ebicsNoPubKeyDigestsRequest xmlns="urn:org:ebics:H006"
                              Version="H006"
                              Revision="1">
    <header authenticate="true">
        <static>
            <HostID>BANKHOST</HostID>
            <Nonce><!-- 16-byte random hex --></Nonce>
            <Timestamp>2026-01-08T10:30:00Z</Timestamp>
            <PartnerID>PARTNER01</PartnerID>
            <UserID>USER001</UserID>
            <Product Language="en">fourbics Client 1.0</Product>
            <OrderDetails>
                <AdminOrderType>HPB</AdminOrderType>
            </OrderDetails>
            <SecurityMedium>0000</SecurityMedium>
        </static>
        <mutable>
            <TransactionPhase>Initialisation</TransactionPhase>
        </mutable>
    </header>
    <AuthSignature>
        <!-- XML-DSig signature (X002) -->
    </AuthSignature>
    <body />
</ebicsNoPubKeyDigestsRequest>

3. ebicsRequest (Standard Operations)

Used for all authenticated operations:

<?xml version="1.0" encoding="UTF-8"?>
<ebicsRequest xmlns="urn:org:ebics:H006"
              xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
              Version="H006"
              Revision="1">
    <header authenticate="true">
        <static>
            <HostID>BANKHOST</HostID>
            <Nonce><!-- 16-byte random hex --></Nonce>
            <Timestamp>2026-01-08T10:30:00Z</Timestamp>
            <PartnerID>PARTNER01</PartnerID>
            <UserID>USER001</UserID>
            <Product Language="en">fourbics Client 1.0</Product>
            <OrderDetails>
                <AdminOrderType>BTU</AdminOrderType>
                <BTUOrderParams>
                    <Service>
                        <ServiceName>SCT</ServiceName>
                        <Scope>DE</Scope>
                        <MsgName>pain.001</MsgName>
                    </Service>
                </BTUOrderParams>
            </OrderDetails>
            <BankPubKeyDigests>
                <Authentication Version="X002" 
                    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">
                    <!-- SHA-256 of bank auth key -->
                </Authentication>
                <Encryption Version="E002" 
                    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">
                    <!-- SHA-256 of bank encryption key -->
                </Encryption>
            </BankPubKeyDigests>
            <SecurityMedium>0000</SecurityMedium>
        </static>
        <mutable>
            <TransactionPhase>Initialisation</TransactionPhase>
        </mutable>
    </header>
    <AuthSignature>
        <ds:SignedInfo>
            <ds:CanonicalizationMethod 
                Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <ds:SignatureMethod 
                Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#xpointer(//*[@authenticate='true'])">
                <ds:Transforms>
                    <ds:Transform 
                        Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
                </ds:Transforms>
                <ds:DigestMethod 
                    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue><!-- SHA-256 digest --></ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue><!-- RSA signature --></ds:SignatureValue>
    </AuthSignature>
    <body>
        <DataTransfer>
            <DataEncryptionInfo authenticate="true">
                <EncryptionPubKeyDigest Version="E002" 
                    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">
                    <!-- Digest of encryption key used -->
                </EncryptionPubKeyDigest>
                <TransactionKey>
                    <!-- RSA-encrypted AES key -->
                </TransactionKey>
            </DataEncryptionInfo>
            <SignatureData authenticate="true">
                <!-- Encrypted electronic signature (EU) -->
            </SignatureData>
            <OrderData>
                <!-- AES-encrypted, compressed order data -->
            </OrderData>
        </DataTransfer>
    </body>
</ebicsRequest>

4. ebicsHEVRequest (Version Query)

Minimal request for version discovery:

<?xml version="1.0" encoding="UTF-8"?>
<ebicsHEVRequest xmlns="http://www.ebics.org/H000">
    <HostID>BANKHOST</HostID>
</ebicsHEVRequest>

Response Structure

<?xml version="1.0" encoding="UTF-8"?>
<ebicsResponse xmlns="urn:org:ebics:H006"
               Version="H006"
               Revision="1">
    <header authenticate="true">
        <static>
            <TransactionID>A1B2C3D4E5F6...</TransactionID>
            <NumSegments>3</NumSegments>
        </static>
        <mutable>
            <TransactionPhase>Initialisation</TransactionPhase>
            <SegmentNumber lastSegment="false">1</SegmentNumber>
            <ReturnCode>000000</ReturnCode>
            <ReportText>[EBICS_OK] OK</ReportText>
        </mutable>
    </header>
    <AuthSignature>
        <!-- Bank's XML-DSig signature -->
    </AuthSignature>
    <body>
        <DataTransfer>
            <DataEncryptionInfo authenticate="true">
                <EncryptionPubKeyDigest Version="E002" 
                    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">
                    <!-- Digest -->
                </EncryptionPubKeyDigest>
                <TransactionKey>
                    <!-- Encrypted AES key -->
                </TransactionKey>
            </DataEncryptionInfo>
            <OrderData>
                <!-- Encrypted response data -->
            </OrderData>
        </DataTransfer>
        <ReturnCode authenticate="true">000000</ReturnCode>
    </body>
</ebicsResponse>

Transaction Phases

EBICS uses a three-phase transaction model:

┌──────────────────────────────────────────────────────────────────────────────┐
│                         TRANSACTION PHASES                                   │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  PHASE 1: INITIALISATION                                                     │
│  ────────────────────────                                                    │
│  • Client sends order parameters and first data segment                      │
│  • Bank validates request and creates transaction                            │
│  • Bank returns TransactionID and NumSegments                                │
│  • For downloads: Bank returns first data segment                            │
│                                                                              │
│  PHASE 2: TRANSFER                                                           │
│  ─────────────────                                                           │
│  • Only for multi-segment transactions (data > 1 MB)                         │
│  • Upload: Client sends remaining segments                                   │
│  • Download: Client requests remaining segments                              │
│  • Each segment acknowledged by bank                                         │
│                                                                              │
│  PHASE 3: RECEIPT                                                            │
│  ───────────────                                                             │
│  • Client sends receipt acknowledgment                                       │
│  • ReceiptCode: 0 = positive (data accepted)                                 │
│  • ReceiptCode: 1 = negative (data rejected)                                 │
│  • Bank finalizes transaction                                                │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

BTF (Business Transaction Format)

H005/H006 use BTF parameters to identify business transactions, replacing the legacy 3-letter order type codes with a flexible service-based approach.

BTF Structure

<BTUOrderParams>
    <Service>
        <ServiceName>SCT</ServiceName>           <!-- Service type -->
        <Scope>DE</Scope>                        <!-- Geographic scope -->
        <ServiceOption>URG</ServiceOption>       <!-- Optional modifier -->
        <Container>ZIP</Container>               <!-- Container format -->
        <MsgName>pain.001</MsgName>              <!-- Message type -->
        <MsgName version="09"/>                  <!-- Message version -->
    </Service>
</BTUOrderParams>

BTF Components

Component	Description	Examples
ServiceName	Business service type (33 services)	SCT, SDD, SCI, XCT, STM, EOP, REP
Scope	Geographic/regulatory scope (17 scopes)	DE, AT, CH, FR, BGR, BBK, BIL
ServiceOption	Optional modifier (25 options)	VOO, VOI, B2B, COR, URG, CFD, THM
Container	Container format (4 types)	XML, ZIP, SVC, None
MsgName	ISO 20022 message type	pain.001, pain.008, camt.053

For complete BTF documentation including all services, scopes, options, and legacy mappings, see BTF Reference.

Legacy Order Types (H003/H004)

For backwards compatibility, legacy 3-letter codes map to BTF:

Legacy	BTF Equivalent
CCT	BTU + SCT
CDD	BTU + SDD (CORE)
C53	BTD + EOP (camt.053)
STA	BTD + STM (MT940)

See BTF Reference for complete mapping table.

Authentication Signature (X002)

All authenticated requests include an XML-DSig signature:

┌──────────────────────────────────────────────────────────────────────────────┐
│                      AUTHENTICATION SIGNATURE (X002)                         │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  1. SELECT AUTHENTICATED ELEMENTS                                            │
│     XPath: //*[@authenticate='true']                                         │
│     Includes: header, DataEncryptionInfo, SignatureData, ReturnCode          │
│                                                                              │
│  2. CANONICALIZE (C14N)                                                      │
│     Algorithm: http://www.w3.org/TR/2001/REC-xml-c14n-20010315               │
│     Removes whitespace, normalizes attributes                                │
│                                                                              │
│  3. HASH (SHA-256)                                                           │
│     Algorithm: http://www.w3.org/2001/04/xmlenc#sha256                       │
│     Result: DigestValue in SignedInfo                                        │
│                                                                              │
│  4. SIGN (RSA-SHA256)                                                        │
│     Algorithm: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256             │
│     Key: Authentication private key (X002)                                   │
│     Result: SignatureValue                                                   │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Electronic Signature (EU)

Order data is signed with the Electronic Signature (Elektronische Unterschrift):

<?xml version="1.0" encoding="UTF-8"?>
<UserSignatureData xmlns="http://www.ebics.org/S002">
    <OrderSignatureData>
        <SignatureVersion>A006</SignatureVersion>
        <SignatureValue>
            <!-- RSA signature of order data hash -->
        </SignatureValue>
        <PartnerID>PARTNER01</PartnerID>
        <UserID>USER001</UserID>
    </OrderSignatureData>
</UserSignatureData>

Signature Versions

Version	Algorithm	Padding	Hash
A005	RSA	PKCS#1 v1.5	SHA-256
A006	RSA	RSASSA-PSS	SHA-256

A006 (RSASSA-PSS) is recommended for H005/H006 as it provides stronger security guarantees.

Nonce and Timestamp

Replay protection uses:

Nonce: 16-byte random value (hex-encoded, 32 characters)
Timestamp: UTC timestamp in ISO 8601 format

Banks track nonce/timestamp pairs to prevent replay attacks. The EbicsNonceTimestamp model stores used values.

Recovery Support

EBICS supports transaction recovery for failed transfers:

Check HPD for RecoverySupported flag
Resume from last segment using stored TransactionID
Track recovery attempts (configurable max)

<!-- HPD Response indicates recovery support -->
<HPDResponseOrderData>
    <RecoverySupported>true</RecoverySupported>
    <PrevalidationSupported>true</PrevalidationSupported>
</HPDResponseOrderData>

Next Steps

Cryptography - Detailed cryptographic operations
Data Model - Entity relationships
Return Codes - Error handling