Benutzerhandbuch – EBICS 3.0 Testapp

Version vom 14.10.2026 · Zielgruppe: Bank- und IT-Tester

1. Zweck und Umfang

Die EBICS 3.0 (H005) Testapp – Buchhaltungs-Simulator ist ein Test-Client, der gegenüber dem EBICS-Testserver einer Bank wie eine Buchhaltungssoftware auftritt. Unterstützt werden:

Erzeugung der Teilnehmerschlüssel A006 (Unterschrift), X002 (Authentifikation), E002 (Verschlüsselung) mit selbstsignierten X.509-Zertifikaten
Initialisierung: INI, HIA, INI-/HIA-Brief (HTML/PDF), HPB (Bankschlüssel abholen)
Abfrage der freigeschalteten Auftragsarten: HTD, HKD, HAA
Download per BTD (z. B. camt.053, camt.054, pain.002) inkl. Transaktionsphasen und Quittung
Upload per BTU (z. B. pain.001) mit elektronischer Unterschrift (A006) und SignatureFlag
Protokoll aller Roh-XML-Requests und -Responses

Die App ist ein Testwerkzeug für EBICS-Testzugänge – nicht für produktive Zahlungen.

2. Zugang

Gehostete Instanz (AWS Lightsail): https://3.64.204.78.sslip.io/
Dieses Handbuch: /handbuch (HTML) und /handbuch.pdf – auch ohne Anmeldung erreichbar
Eigenen Server betreiben: siehe SELFHOST.md im Paket (Docker + Caddy oder systemd)

3. Anmeldung: Arbeitsbereich und Passphrase

Anmeldeseite

Arbeitsbereich (Name): 3–64 Zeichen (Buchstaben, Ziffern, ., -, _, @). Ein neuer Name legt automatisch einen neuen, isolierten Arbeitsbereich an.
Passphrase: mindestens 12 Zeichen. Sie verschlüsselt die privaten Schlüssel (PKCS#8).
Button Öffnen / anlegen.

Wichtig:

Keine Wiederherstellung: Passphrase vergessen = Schlüssel verloren. Dann sind neue Schlüssel und eine neue Initialisierung bei der Bank nötig.
Sitzungs-Timeout nach 30 Minuten Inaktivität.
Bei jedem Update/Neustart der App werden alle Sitzungen beendet – einfach neu anmelden (gleicher Name, gleiche Passphrase). Daten und Schlüssel bleiben erhalten.
Jeder Arbeitsbereich hat eigene Einstellungen, Schlüssel, Protokolle und Downloads. Arbeitsbereiche sehen einander nicht.
Anmeldeversuche sind begrenzt (10 pro 5 Minuten und IP).

4. Überblick der Hauptseite

Hauptseite

Oben: aktueller Arbeitsbereich, Abmelden, Link zum Handbuch. Meldungen (Erfolg/Fehler) erscheinen als blau hinterlegte Hinweise. Die Abschnitte sind in Arbeitsreihenfolge nummeriert.

5. Bankverbindung (Abschnitt „1. Bankverbindung“)

Feld	Bedeutung
Bank-URL	EBICS-Endpunkt des Testservers (https://…)
Host-ID	EBICS-Host-ID der Bank
Kunden-ID (Partner)	Partner-ID aus den Zugangsdaten
Teilnehmer-ID (User)	User-ID aus den Zugangsdaten
System-ID (optional)	nur wenn von der Bank vorgegeben (technischer Teilnehmer)
Bankname, Name Teilnehmer	erscheinen auf dem INI-Brief bzw. im Zertifikat
Schlüssellänge	2048, 3072 oder 4096 Bit
TLS prüfen	Serverzertifikat prüfen (nur für Testserver mit eigenem Zertifikat abschalten)

Mit Speichern übernehmen. Die Werte werden im Arbeitsbereich gespeichert.

6. Schlüssel und Initialisierung (Abschnitt „2. Initialisierung“)

Die Statuszeile zeigt „Teilnehmerschlüssel: vorhanden/fehlen | Bankschlüssel: vorhanden/fehlen“.

6.1 Schlüssel erzeugen

Schlüssel erzeugen (A006/X002/E002) erzeugt drei RSA-Schlüssel mit Zertifikaten und passender Schlüsselverwendung (A006 = nonRepudiation, X002 = digitalSignature, E002 = keyEncipherment). Vorher Partner-ID und User-ID speichern.

Achtung: Nach erfolgreichem INI/HIA bzw. nach der Freischaltung durch die Bank keine neuen Schlüssel erzeugen. Neue Schlüssel machen die bei der Bank hinterlegten ungültig – dann ist eine komplette Neuinitialisierung nötig.

6.2 INI und HIA senden

INI senden – übermittelt das Unterschriftszertifikat (A006).
HIA senden – übermittelt Authentifikations- (X002) und Verschlüsselungszertifikat (E002).

Erfolg: Header- und Body-ReturnCode 000000. Die Bank vergibt eine Auftragsnummer (z. B. N003/N004).

6.3 INI-Brief

INI-Brief (HTML) öffnet die druckbare Fassung, INI-Brief (PDF) lädt das PDF. Pro Schlüssel eine Seite mit Datum, Bank/Host-ID, Teilnehmer, Version, Schlüssellänge, Hashwert Zertifikat (SHA-256, EBICS 3.0), Hashwert öffentlicher Schlüssel, Exponent/Modulus sowie Unterschriftsfeld.

INI-Brief (Ausschnitt)

6.4 Freischaltung in der Bank (z. B. TRAVIC)

Die Bank vergleicht die Hashwerte des Briefs mit den empfangenen INI/HIA-Aufträgen und schaltet den Teilnehmer frei (Status „bereit“/aktiv). In TRAVIC (Corporate/Port-Administration) erscheint dazu ein Freischaltauftrag zum Teilnehmer. Erst danach funktionieren HPB und alle weiteren Aufträge.

6.5 HPB – Bankschlüssel abholen

HPB abholen lädt die Bankzertifikate (X002, E002) und speichert sie. Anschließend zeigt der Abschnitt „Bank X002/E002“ Zertifikats- und Schlüssel-Hash. Diese Hashwerte mit den von der Bank veröffentlichten Werten vergleichen, bevor Daten ausgetauscht werden.

7. Zugelassene Auftragsarten (BTF)

Abschnitt „Zugelassene Auftragsarten (BTF) der Bank“ mit den Buttons HTD abfragen, HKD abfragen, HAA abfragen. Die Antwort wird entschlüsselt, im Protokoll abgelegt und als Tabelle angezeigt:

Spalte	Inhalt
Quelle	HTD, HKD oder HAA
Art	BTD (Download) oder BTU (Upload)
ServiceName / Scope / Option / Container / MsgName / Version	BTF-Parameter der Bank
Berecht.	Unterschriftsklasse (z. B. E) und Anzahl benötigter Unterschriften
Beschreibung	Text der Bank

Pro Zeile gibt es Download bzw. Upload (mit Auswahl einer Beispieldatei). Diese Buttons verwenden genau die Parameter der Bank – das ist der zuverlässigste Weg, 091005 zu vermeiden.

7.1 Unterschied zwischen HTD, HKD und HAA

HAA liefert nur die Auftragsarten, die aktuell zum Abholen bereitstehen (Downloads mit vorhandenen Daten). Keine Uploads, keine Berechtigungen.
HTD liefert die Kunden- und Teilnehmerdaten des eigenen Teilnehmers: Konten, freigeschaltete Auftragsarten für Upload und Download inkl. BTF-Parametern sowie die Unterschriftsklasse je Auftragsart.
HKD liefert dieselben Informationen wie HTD, aber für alle Teilnehmer des Kunden (der Partner-ID). Manche Banken schränken HKD ein oder geben es nur bestimmten Teilnehmern frei.

	HAA	HTD	HKD
Inhalt	Downloads mit verfügbaren Daten	Kunden- und eigene Teilnehmerdaten	Kunden- und Daten aller Teilnehmer
Upload-Auftragsarten (BTU)	nein	ja	ja
Download-Auftragsarten (BTD)	nur aktuell verfügbare	alle freigeschalteten	alle freigeschalteten
Unterschriftsklasse	nein	ja (eigener Teilnehmer)	ja (je Teilnehmer)
Verfügbarkeit	meist frei	meist frei	teils eingeschränkt

Empfehlung: HTD für normale Tests, HKD zum Vergleich mehrerer Teilnehmer, HAA als schneller Check, ob Downloads bereitliegen.

8. Download (Abschnitt „3. Download (BTD)“)

Vorlage: vordefinierte Kombinationen, u. a. camt.053 (Tagesauszug), camt.053 CH/LI (SPS, Scope CH, v08 bzw. v04), camt.052, camt.054, pain.002, HAC. Mit Eigene Parameter … gelten die Felder ServiceName/Scope/Option und MsgName/Version/Container.
Zeitraum (optional): Start- und Enddatum; leer = neue, noch nicht abgeholte Daten.
Abholen führt Initialisierung, ggf. weitere Segmente und die Quittung (Receipt) aus.

Ergebnis: Datei unter „Downloads & Protokoll → Empfangene Dateien“ (.zip bei Container ZIP, sonst .xml). Meldung 090005 – keine Daten verfügbar ist kein Fehler: Für den Zeitraum liegen keine Daten vor.

9. Upload (Abschnitt „4. Upload (BTU)“)

Vorlage oder Eigene Parameter … (ServiceName/Scope/Option, MsgName/Version). Für Schweizer/Liechtensteiner Banken typischerweise MCT / CH / pain.001 – maßgeblich ist die HTD-Tabelle.
Beispieldatei:
pain.001.001.03.ch.02_CH.xml (Swiss Payment Standards, Version 03)
pain.001.001.09.ch.03_CH.xml (SPS, Version 09)
pain.001.001.09_SCT.xml (SEPA-Überweisung)
Eigene Datei hat Vorrang vor der Beispieldatei.
VEU (requestEDS): anhaken, wenn mehr Unterschriften nötig sind als vorhanden – der Auftrag geht dann in die Verteilte Elektronische Unterschrift statt abgelehnt zu werden.
Signieren (A006) und senden.

Jeder Upload enthält die Unterschrift (A006) und das SignatureFlag. Ohne dieses behandelt die Bank den Auftrag als reinen Transport (Attribut „D“) und lehnt ihn bei Unterschriftspflicht ab.

Die Beispieldateien enthalten eine Platzhalter-IBAN (LI21088100002324013AA) und fiktive Empfänger. Die EBICS-Übertragung sollte gelingen; die fachliche Prüfung der Bank (pain.002) kann die Zahlung trotzdem ablehnen. Für echte Tests ein Testkonto der Bank eintragen bzw. eigene Datei hochladen.

Nach dem Upload den Statusbericht per Download pain.002 (PSR) abholen.

10. Protokoll („Downloads & Protokoll“)

Empfangene Dateien: heruntergeladene Daten.
XML-Log (neueste zuerst): jeder Request und jede Response als Datei, z. B. …_HPB_request.xml, …_BTD_init_response_http200.xml, sowie entschlüsselte Antworten (…_HTD_orderdata_decrypted.xml).
Die Logs enthalten keine privaten Schlüssel und keine Passphrasen. Bei Fehlern ReturnCode im Header (technisch) und im Body (fachlich) beachten – die App zeigt beide an.

11. Fehlerbehebung

Code	Name	Typische Ursache	Lösung
091210	EBICS_X509_WRONG_KEY_USAGE	Zertifikat ohne passende Schlüsselverwendung (bei INI/HIA)	Behoben in der App; Schlüssel einmalig neu erzeugen, INI/HIA erneut senden
061001	EBICS_AUTHENTICATION_FAILED	Teilnehmer noch nicht freigeschaltet oder Authentifikationssignatur ungültig	Freischaltung in der Bank prüfen; App ist aktuell (Signatur-Fehler behoben); keine neuen Schlüssel erzeugen
091002 / 091003	INVALID_USER_OR_USER_STATE / USER_UNKNOWN	Teilnehmer nicht aktiv bzw. IDs falsch	Host-/Partner-/User-ID prüfen, Status in der Bank prüfen
091005	EBICS_INVALID_ORDER_IDENTIFIER	BTF-Kombination (ServiceName/Scope/Version/Container) nicht freigeschaltet; bei Upload fehlende Unterschriftsberechtigung	HTD abfragen und Zeile aus der Tabelle verwenden
090005	EBICS_NO_DOWNLOAD_DATA_AVAILABLE	Keine Daten im Zeitraum	Kein Fehler; anderen Zeitraum wählen
091214	EBICS_X509_UNKNOWN_CERTIFICATE_AUTHORITY	Bank akzeptiert keine selbstsignierten Zertifikate	Mit der Bank klären (CA-Zertifikate werden von der App nicht unterstützt)
011000	DOWNLOAD_POSTPROCESS_DONE	Quittung bestätigt	Kein Fehler

Weitere Hinweise:

„Verbindungsfehler“: Bank-URL, Firewall der Bank (IP-Freigabe) und TLS-Einstellung prüfen.
Grundregel aus der Praxis: Nach der Freischaltung Schlüssel nie neu erzeugen. Bei Problemen zuerst das XML-Log ansehen.

12. Sicherheit

Nur EBICS-Testzugänge verwenden.
Private Schlüssel sind mit der Passphrase verschlüsselt; die Passphrase liegt nur während der Sitzung im Arbeitsspeicher.
Zugriff nur per HTTPS; Cookies sind Secure/HttpOnly/SameSite=Strict.
Ratenbegrenzung: 120 Anfragen/Minute/IP, 20 EBICS-Aufträge/Minute/Arbeitsbereich.
Die gehostete Instanz ist öffentlich: Jeder kann Arbeitsbereiche anlegen. Wer Name und Passphrase kennt, hat Zugriff – daher eine starke, eindeutige Passphrase wählen.

13. Bekannte Einschränkungen

Getestet gegen einen TRAVIC-Testserver (INI, HIA, HPB, HTD, BTD) und einen Offline-Simulator; andere Bankserver ungetestet.
Nur selbstsignierte Zertifikate, keine CA-Zertifikate, keine Chipkarten/Sicherheitsmedien.
Keine VEU-Bearbeitung (HVE/HVU/HVD …) in der Oberfläche; Upload kann nur per requestEDS in die VEU gestellt werden.
Keine Schlüsseländerung (PUB/HCA/HCS) und keine Sperre (SPR).
Sitzungen liegen im Arbeitsspeicher (nur ein Server-Prozess); Neustart = neue Anmeldung.
Nur EBICS 3.0 (H005), keine Versionen 2.x.