Log in Get Started
Docs Privacy Policy Terms of Service Contact Imprint
Language: English Deutsch

Message Types

Structure of EBICS requests and responses.

EBICS defines several message types for different purposes. This document covers the structure of requests and responses.

Request Structure

Standard Request (ebicsRequest)

Used for most EBICS operations:

<?xml version="1.0" encoding="UTF-8"?>
<ebicsRequest xmlns="urn:org:ebics:H005"
              xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
              Version="H005"
              Revision="1">
    <header authenticate="true">
        <static>
            <HostID>EBIXHOST</HostID>
            <Nonce>...</Nonce>
            <Timestamp>2024-01-15T10:30:00Z</Timestamp>
            <PartnerID>PARTNER01</PartnerID>
            <UserID>USER001</UserID>
            <Product Language="en">fourbics Client</Product>
            <OrderDetails>
                <AdminOrderType>BTD</AdminOrderType>
                <BTDOrderParams>
                    <Service>
                        <ServiceName>STM</ServiceName>
                        <Scope>DE</Scope>
                        <MsgName>camt.053</MsgName>
                    </Service>
                </BTDOrderParams>
            </OrderDetails>
            <BankPubKeyDigests>
                <Authentication Version="X002" Algorithm="...">
                    <!-- SHA-256 hash of bank auth key -->
                </Authentication>
                <Encryption Version="E002" Algorithm="...">
                    <!-- SHA-256 hash of bank enc key -->
                </Encryption>
            </BankPubKeyDigests>
            <SecurityMedium>0000</SecurityMedium>
        </static>
        <mutable>
            <TransactionPhase>Initialisation</TransactionPhase>
        </mutable>
    </header>
    <AuthSignature>
        <ds:SignedInfo>...</ds:SignedInfo>
        <ds:SignatureValue>...</ds:SignatureValue>
    </AuthSignature>
    <body>
        <DataTransfer>
            <DataEncryptionInfo authenticate="true">
                <EncryptionPubKeyDigest Version="E002" Algorithm="...">
                    <!-- Digest of encryption key -->
                </EncryptionPubKeyDigest>
                <TransactionKey>
                    <!-- Encrypted AES key -->
                </TransactionKey>
            </DataEncryptionInfo>
            <SignatureData authenticate="true">
                <!-- Electronic signature (EU) -->
            </SignatureData>
            <OrderData>
                <!-- Encrypted, compressed order data -->
            </OrderData>
        </DataTransfer>
    </body>
</ebicsRequest>

Unsigned Request (ebicsUnsecuredRequest)

Used for INI and HIA (before keys are established):

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

No-Auth Request (ebicsNoPubKeyDigestsRequest)

Used for HPB (downloading bank keys):

<?xml version="1.0" encoding="UTF-8"?>
<ebicsNoPubKeyDigestsRequest xmlns="urn:org:ebics:H005"
                              Version="H005"
                              Revision="1">
    <header authenticate="true">
        <static>
            <HostID>EBIXHOST</HostID>
            <Nonce>...</Nonce>
            <Timestamp>2024-01-15T10:30:00Z</Timestamp>
            <PartnerID>PARTNER01</PartnerID>
            <UserID>USER001</UserID>
            <Product Language="en">fourbics Client</Product>
            <OrderDetails>
                <AdminOrderType>HPB</AdminOrderType>
            </OrderDetails>
            <SecurityMedium>0000</SecurityMedium>
        </static>
        <mutable>
            <TransactionPhase>Initialisation</TransactionPhase>
        </mutable>
    </header>
    <AuthSignature>
        <ds:SignedInfo>...</ds:SignedInfo>
        <ds:SignatureValue>...</ds:SignatureValue>
    </AuthSignature>
    <body />
</ebicsNoPubKeyDigestsRequest>

HEV Request (ebicsHEVRequest)

Version query (no authentication):

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

Response Structure

Standard Response (ebicsResponse)

<?xml version="1.0" encoding="UTF-8"?>
<ebicsResponse xmlns="urn:org:ebics:H005"
               Version="H005"
               Revision="1">
    <header authenticate="true">
        <static>
            <TransactionID>A1B2C3D4E5F6...</TransactionID>
            <NumSegments>1</NumSegments>
        </static>
        <mutable>
            <TransactionPhase>Initialisation</TransactionPhase>
            <SegmentNumber lastSegment="true">1</SegmentNumber>
            <ReturnCode>000000</ReturnCode>
            <ReportText>[EBICS_OK] OK</ReportText>
        </mutable>
    </header>
    <AuthSignature>
        <ds:SignedInfo>...</ds:SignedInfo>
        <ds:SignatureValue>...</ds:SignatureValue>
    </AuthSignature>
    <body>
        <DataTransfer>
            <DataEncryptionInfo authenticate="true">
                <EncryptionPubKeyDigest Version="E002" Algorithm="...">
                    <!-- Digest -->
                </EncryptionPubKeyDigest>
                <TransactionKey>
                    <!-- Encrypted AES key -->
                </TransactionKey>
            </DataEncryptionInfo>
            <OrderData>
                <!-- Encrypted, compressed response data -->
            </OrderData>
        </DataTransfer>
        <ReturnCode authenticate="true">000000</ReturnCode>
    </body>
</ebicsResponse>

HEV Response (ebicsHEVResponse)

<?xml version="1.0" encoding="UTF-8"?>
<ebicsHEVResponse xmlns="http://www.ebics.org/H000">
    <SystemReturnCode>
        <ReturnCode>000000</ReturnCode>
        <ReportText>[EBICS_OK] OK</ReportText>
    </SystemReturnCode>
    <VersionNumber>
        <ProtocolVersion>H005</ProtocolVersion>
        <AuthenticationVersion>X002</AuthenticationVersion>
        <EncryptionVersion>E002</EncryptionVersion>
        <SignatureVersion>A006</SignatureVersion>
    </VersionNumber>
    <VersionNumber>
        <ProtocolVersion>H006</ProtocolVersion>
        <AuthenticationVersion>X002</AuthenticationVersion>
        <EncryptionVersion>E002</EncryptionVersion>
        <SignatureVersion>A006</SignatureVersion>
    </VersionNumber>
</ebicsHEVResponse>

Transaction Phases

Upload Transaction

Phase 1: Initialisation
├── Client sends: Order details, encrypted data, EU signature
├── Server responds: TransactionID, acknowledgment
└── Status: Transaction created

Phase 2: Transfer (if multi-segment)
├── Client sends: Remaining data segments
├── Server responds: Segment acknowledgment
└── Status: Data received

Result: Order submitted for processing

Download Transaction

Phase 1: Initialisation
├── Client sends: Order details, date range
├── Server responds: TransactionID, first segment, total segments
└── Status: Data prepared

Phase 2: Transfer (if multi-segment)
├── Client sends: Segment requests
├── Server responds: Data segments
└── Status: Data transferred

Phase 3: Receipt
├── Client sends: Receipt acknowledgment
├── Server responds: Confirmation
└── Status: Transaction completed

Header Elements

Static Header

Element Description Required
HostID Bank's EBICS host identifier Yes
Nonce Random value for replay protection Conditional
Timestamp Request timestamp (UTC) Conditional
PartnerID Customer/partner identifier Yes
UserID Subscriber identifier Yes
SystemID Technical user identifier Optional
Product Client software name Optional
OrderDetails Order type and parameters Yes
BankPubKeyDigests Bank key fingerprints Conditional
SecurityMedium Key storage medium (usually 0000) Yes

Mutable Header

Element Description
TransactionPhase Current phase (Initialisation, Transfer, Receipt)
SegmentNumber Current segment number
OrderID Bank-assigned order identifier

Authentication Signature

The AuthSignature element contains an XML Digital Signature (XML-DSig) that authenticates the request:

<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>...</ds:DigestValue>
        </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>...</ds:SignatureValue>
</AuthSignature>

Next Steps