EBICS — Bank Integration

Overview

The EBICS service enables automatic integration with any German bank via the EBICS standard (Electronic Banking Internet Communication Standard). Account statements are fetched automatically and incoming payments are matched to open invoices in the CRM.

Features

• Automatic statement retrieval — Daily (MT940/camt.053) and hourly (MT942/camt.052)
• Auto-reconciliation — Bank transactions are automatically matched to open invoices
• Dunning integration — Payment receipts stop dunning workflows immediately
• Real-time cash flow — Hourly transaction data in the CRM dashboard
• Multi-bank accounts — Unlimited accounts at different banks per tenant
• GoBD archiving — Raw bank statements stored for 10 years

Prerequisites

What the bank provides

After requesting EBICS access, the bank provides the following data:

Information	Description
Host ID	Technical identifier of the bank server
Partner ID	Customer number in the EBICS system
User ID	User identifier for access
Server URL	URL of the bank's EBICS server

Additionally, the desired order types (STA, VMK, C53, C52) must be enabled by the bank.

What the customer provides

Information	Description
IBAN	Bank account number
BIC	Bank identifier code (SWIFT code)
EBICS credentials	Host ID, Partner ID, User ID (received from bank)
Signature	Physical signature on the INI letter

No technical setup required

The customer does not need any software installation or certificate management. Everything runs through the xynap setup wizard.

Setup (Wizard)

Step 1: Enter bank details

In the CRM under Finance → EBICS Bank Accounts → New Account, enter the bank details and EBICS credentials.

Step 2: Generate keys

RSA keys are generated automatically. Click "Generate Keys" to start the process.

Step 3: Send INI + HIA

The initialization letters are sent to the bank. Then the INI letter must be printed, signed, and mailed to the bank.

Step 4: Activation

After receiving the INI letter, the bank activates the access (1-3 business days). Click "Check Activation" in the wizard — on success, automatic retrieval starts.

Supported Formats

Format	Order Type	Description	Frequency
camt.053	C53	Account statement (ISO 20022)	Daily
camt.052	C52	Intraday transactions (ISO 20022)	Hourly
MT940	STA	Account statement (SWIFT, being phased out)	Daily
MT942	VMK	Intraday transactions (SWIFT, being phased out)	Hourly

Format transition

Starting November 2026, many banks will discontinue MT940/MT942. camt.053/052 is automatically preferred.

Auto-Reconciliation

Incoming payments are automatically matched to open invoices:

Strategy	Confidence	Description
Exact reference	100%	Invoice number in payment reference or SEPA End-to-End ID
Amount + date	70%	Open amount matches exactly, date within due window
Counter IBAN	60%	Customer IBAN known, amount matches
Fuzzy matching	40%	Pattern search in payment reference

• At 85% confidence or higher: Automatic match (CRM payment is created)
• Below 85%: Suggestion for manual confirmation in the reconciliation view

API Endpoints

All endpoints under /api/v1/crm/ebics/. Authentication via JWT, tenant scoping automatic.

Account Management

GET    /crm/ebics/accounts              → List bank accounts
POST   /crm/ebics/accounts              → Create bank account
GET    /crm/ebics/accounts/{uuid}       → Account detail
PUT    /crm/ebics/accounts/{uuid}       → Update account
DELETE /crm/ebics/accounts/{uuid}       → Deactivate account

Key Management

POST   /crm/ebics/accounts/{uuid}/keys/init      → Generate keys
POST   /crm/ebics/accounts/{uuid}/keys/ini       → Send INI to bank
POST   /crm/ebics/accounts/{uuid}/keys/hia       → Send HIA to bank
POST   /crm/ebics/accounts/{uuid}/keys/activate  → Check activation
GET    /crm/ebics/accounts/{uuid}/keys/ini-letter → INI letter PDF
GET    /crm/ebics/accounts/{uuid}/keys/status     → Key status

Statements

POST   /crm/ebics/accounts/{uuid}/fetch    → Manual fetch
GET    /crm/ebics/statements               → Filter statements
GET    /crm/ebics/statements/{uuid}        → Statement detail
GET    /crm/ebics/statements/{uuid}/raw    → Original file (GoBD)

Transactions + Reconciliation

GET    /crm/ebics/transactions                      → Filter transactions
GET    /crm/ebics/transactions/{uuid}               → Detail
GET    /crm/ebics/transactions/{uuid}/suggestions   → Match suggestions
POST   /crm/ebics/transactions/{uuid}/reconcile     → Manual match
POST   /crm/ebics/transactions/{uuid}/ignore        → Ignore
POST   /crm/ebics/transactions/{uuid}/undo          → Undo match
POST   /crm/ebics/reconcile/batch                   → Auto-reconciliation

Dashboard

GET    /crm/ebics/dashboard    → Balances, unmatched count, daily stats

Permissions

Permission	Description
ebics.view	View bank accounts, statements and transactions
ebics.manage	Create/edit bank accounts, manage keys
ebics.fetch	Manually fetch account statements
ebics.reconcile	Match, ignore or undo payment assignments

Technical Details

Architecture

┌─────────────────┐     REST      ┌──────────────┐     EBICS      ┌──────────┐
│  Platform API   │ ──────────── │  ebics-api   │ ────────────── │   Bank   │
│  (FastAPI)      │              │  (Container) │               │  Server  │
│                 │              │              │               │          │
│  Parser         │              │  Keys        │               │  MT940   │
│  Reconciliation │              │  Connections │               │  camt053 │
│  Scheduler      │              │  Protocol    │               │  MT942   │
└─────────────────┘              └──────────────┘               │  camt052 │
                                                                └──────────┘

Scheduler

• Daily fetch (~08:00 UTC, via CRM Daily Scheduler): Account statements (camt.053/MT940) + auto-reconciliation
• Hourly intraday (dedicated background task, 07:00-20:00 UTC): Intraday transactions (camt.052/MT942)
• Time window configurable via EBICS_INTRADAY_START_HOUR / EBICS_INTRADAY_END_HOUR
• Duplicate detection via SHA-256 hash of raw data
• Intraday statements are cumulatively replaced (bank delivers daily cumulative)

Key Status Lifecycle

pending → keys_generated → ini_sent → hia_sent → active
                                                → suspended

After HIA is sent, the INI letter must be printed, signed, and mailed to the bank. Activation by the bank typically takes 1-3 business days. Afterwards, the HPB download can be performed (button "Check Activation").

Reconciliation Status

Status	Description
unmatched	No match found
suggested	Suggestion available, manual confirmation required
auto_matched	Automatically matched (confidence ≥ 85%)
manual_matched	Manually matched by user
ignored	Marked as irrelevant
partial	Partial payment — invoice only partially settled

Database Tables

• ebics_bank_accounts — Bank accounts with EBICS credentials and key status
• ebics_bank_statements — Account statements incl. raw_data + raw_hash (GoBD archiving, 10 years)
• ebics_bank_transactions — Individual transactions with reconciliation status and SEPA references

Parser Details

MT940 Parser (ebics_parsers.py):

• Library: mt940 (WoLpH/mt940) — API: mt940.MT940(io.StringIO(raw)).statements
• Supports standard SEPA tags (SVWZ+, EREF+, MREF+, ...) and DK-format sub-fields (?30=BIC, ?31=IBAN, ?32=Name)
• Returns Statement namedtuples with start_balance, end_balance, transactions

camt.053/052 Parser (ebics_parsers.py):

• Direct XML parsing via Python ElementTree (no external framework)
• Namespace-aware (urn:iso:std:iso:20022:tech:xsd:camt.053.001.02)
• Extracts NtryRef, EndToEndId, RmtInf/Ustrd, IBAN from RltdPties, BIC from RltdAgts

Test Status

103 backend tests passing (as of 2026-03-17):

Test file	Tests	Coverage
test_ebics_parsers.py	60	MT940 (Standard + ABN AMRO + SEPA), camt.053 (Minimal + Real files)
test_ebics_key_manager.py	20	Key lifecycle, status transitions, error handling
test_ebics_reconciliation.py	23	All matching strategies, apply/undo, batch
ebics-demobank/test_api.py	67	Demobank API end-to-end