ebicsclient — a pure-Python EBICS 3.0 (H005) client
A Python client for the EBICS banking protocol (EBICS 3.0 / H005): download statements and initiate payments over a single, free library. Validated live against Zürcher Kantonalbank (ZKB) and the PostFinance test platform.
Free software under the Apache License 2.0, written and maintained by one person. It is a protocol library, not a financial service, and it comes without warranty: read the License section below before it touches a production account.
Website: ebicsclient.ch
Install
pip install ebicsclient # add [pdf] for PDF letters, [tls] for the certifi CA bundle
Quickstart
from ebicsclient import Bank, User, Client, generate_keyring, save_keyring, PAIN_001
bank = Bank(host_id="HOST1", url="https://ebicsweb.example.com/ebicsweb")
user = User(partner_id="PARTNER1", user_id="USER1")
# 1. Generate the three RSA key pairs (once) and store them encrypted.
keyring = generate_keyring()
save_keyring(keyring, "keyring.json", passphrase="…")
client = Client(bank, user, keyring)
# 2. Key initialisation: submit your keys, then print/sign/send the letter and wait for activation.
client.ini()
client.hia()
letter = client.make_ini_letter() # HTML, or PDF with the optional [pdf] extra
# … send letter.content to the bank; once activated:
# 3. Fetch the bank's public keys (verify their published hashes out of band).
client.hpb()
# 4. Read: download and parse the end-of-day statements.
for statement in client.download_statements():
print(statement.iban, statement.closing_balance)
# 5. Write: initiate a payment (a pain.001.001.09 document, as bytes).
transaction_id = client.upload(PAIN_001, pain001_bytes)
The certificate-based (mit Zertifikaten) profile is a constructor option — see docs/11-certificate-profiles.md.
More worked examples — a non-acking peek, a consume-safe sync, a dated backfill, a payment round-trip, certificate-profile onboarding, key rotation, incoming payments resolved to their invoices, bank discovery (HEV, HPD, HTD, HAA), the bank's log of EBICS actions (HAC) and the strict message-version policy — are in examples/.
⚠️ Loading EBICS identifiers from a config file? Quote them.
EBICS IDs can carry leading zeros (a real Partner ID may look like
00123456) and ISO versions look like"08". Unquoted in YAML/JSON/TOML these parse as numbers — the wrong type and silently stripped of their zeros. Always quote them (partner_id: "00123456"); the library rejects non-string values, but the fix is quoting, neverstr()-wrapping the parsed number (which keeps the wrong, zero-stripped identifier). The same applies to numeric-looking keyring passphrases.
What it does
Key ceremony (INI/HIA/HPB, with the bank's keys pinned to the hash values it publishes, in the
public-key or the certificate form), key rotation without a new letter (PUB/HCA/HCS) and
suspending a subscriber whose key may be compromised (SPR); statement and
report downloads (camt.053/052/054, pain.002) with optional dated ranges, each booking resolved
into its single transactions (references, payer, remittance information), and an opt-in check
that the bank delivered the requested message version (VersionPolicy.STRICT); payment uploads
(pain.001); the bank's log of every EBICS action and its result (HAC); and the bank's
registered data (HTD/HKD), parameters (HPD) and supported versions (HEV). Interrupted transfers resume within their transaction (EBICS recovery), and an upload
whose final answer stays lost is reported as unconfirmed, never as safe to retry. Read and
write are validated live against ZKB and the PostFinance test platform. Pure Python (cryptography, lxml), no PHP/Java
sidecar. In numbers: 15 of the 22 H005 order types, and 47 of the 68 capabilities tracked
in docs/13 in full plus 6 in part: reads 24 of 28, writes 9 of 13, multi-person signatures
(EDS/VEU) 0 of 7. Everything the standard requires unconditionally is implemented; what is
missing is optional in the standard, above all EDS, which waits for a test environment
with several required signatures. If you can provide access to one, please open an
issue or write to the maintainer via
ebicsclient.ch; with it, EDS gets built and validated. What is
implemented but not yet validated against a bank is kept apart in ebicsclient.experimental.
Full capability-by-capability coverage, gaps, and verification status: docs/13-standard-conformance.md.
Why this exists
It was built for WealthTracker, which needs to pull bank statements over EBICS — and no pure-Python client for EBICS 3.0 (H005) existed to build on. Rather than shell out to a PHP/Java sidecar or a proprietary dependency, ebicsclient is a clean, reusable library that any application can embed. See docs/03-library-landscape.md for the existing options and the gap.
Why only EBICS 3.0 (H005)?
By design. EBICS access now requires H005 (the pre-3.0 protocol was retired ~Nov 2025), and
the ISO 20022 "2009" message vintage retires 21 Nov 2026 — so supporting legacy versions
would be building for the past. The protocol/ layer is seamed for a future EBICS version, not
older ones. The regulatory deadlines are in docs/01; the scope
decision in docs/04.
Documentation
| Doc | Contents |
|---|---|
| docs/01-protocol-and-formats.md | EBICS/H005 background, the two regulatory deadlines, message formats |
| docs/02-licensing-strategy.md | Licence: Apache-2.0 since 2.0.0; the retired dual-licensing plan, kept as history |
| docs/03-library-landscape.md | Existing EBICS libraries and the gap this library fills |
| docs/04-implementation-plan.md | Scope, modules, the two hard parts, build order, test strategy |
| docs/05-zkb-onboarding.md | The INI/HIA + signed-letter ceremony, re-initialisation, ZKB order params |
| docs/06-engineering-conventions.md | Baseline practices: layout, logging, errors, security, typing, testing, CI |
| docs/07-handshake-testing.md | Validating INI/HIA/HPB + download/upload against the ZKB test platform |
| docs/08-parity-and-xsd-findings.md | The inclusive-vs-exclusive c14n correction and verification discipline |
| docs/09-zkb-test-platform-settings.md | What the ZKB test platform exposes, and its upload/simulation model |
| docs/10-btf-order-types.md | ZKB's EBICS order-type → H005 BTF catalogue |
| docs/11-certificate-profiles.md | "mit Schlüsseln" vs "mit Zertifikaten", and the certificate seam |
| docs/12-verification-ledger.md | Every protocol claim → spec citation → oracle → status; the 2.5→3.0 audit |
| docs/13-standard-conformance.md | Coverage & gaps: every H005 order type — supported or not, and how far verified |
| docs/14-postfinance-test-platform.md | The PostFinance test platform: BTF catalogue, behaviour, settings, and what is validated there |
Development
Contributors: see CONTRIBUTING.md. One-command setup with uv:
git clone https://github.com/schulluk/ebicsclient && cd ebicsclient && uv sync --all-groups
(or pip install -e . --group dev on pip ≥ 25.1). This is a money-moving library — the
engineering bar is docs/06-engineering-conventions.md.
License
Copyright © 2026 Lukas Schulze. Licensed under the Apache License 2.0 since version 2.0.0, for any use, commercial or not: see LICENSE and NOTICE. Versions up to 1.9.0 were published under the PolyForm Noncommercial License 1.0.0; use 2.0.0 or later for the Apache terms. The retired paid-licence plan is kept as history in docs/02-licensing-strategy.md.
What that means in practice:
- The library is written and maintained by one person. There is no company behind it, no support contract and no service level. Bug reports and questions go to the issue tracker and are answered on a best-effort basis.
- It is a protocol library, not a financial service. It transports the orders and statements you exchange with your bank under your own EBICS contract, and the bank executes what you submit.
- It comes without warranty of any kind and without liability as far as the law allows, as sections 7 and 8 of the licence state. Before it touches a production account, test it against your bank's test platform, keep your bank-side controls in place, such as payment limits and dual authorisation where your bank offers them, and check the bank's status report for every payment you submit.
- Which banks, test platforms and order types each release has been verified against is recorded in docs/12 and docs/13. Anything not listed there is untested.
Metadata
Release files for ebicsclient 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ebicsclient-2.0.0.tar.gz | 376.9 kB | With provenance | Details for ebicsclient-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ebicsclient-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for ebicsclient-2.0.0-py3-none-any.whl |
Total release size: 489.0 kB
Release files / ebicsclient-2.0.0.tar.gz
| Download URL | ebicsclient-2.0.0.tar.gz |
|---|---|
| Size | 376.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bfff3a84fd86e35a4625aacdf2a17a8756e03015456d1bf1e0d00a26a3baa5a4
|
|
BLAKE2b-256 checksum How to use checksums |
35ca5d143e634a644966d9868bf26cd0779e05e1b971049c2d6de7f9b92c3be6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / ebicsclient-2.0.0-py3-none-any.whl
| Download URL | ebicsclient-2.0.0-py3-none-any.whl |
|---|---|
| Size | 112.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
65fe7b683e32a4d124bc6d9a15439f2373e91db63efeb7100d9b84c1ff553d55
|
|
BLAKE2b-256 checksum How to use checksums |
cb78e4906b025a65e1c678128bf7c7a18c54af40dce1eb724fe4f3bb53ab9073
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for ebicsclient 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ebicsclient-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.