Skip to main content

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, never str()-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)

Source distribution for ebicsclient 2.0.0
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)

Table of built distributions (wheels) for ebicsclient 2.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page