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, source-available library. Validated live against Zürcher Kantonalbank (ZKB) and the PostFinance test platform.

Free for personal and other noncommercial use. Commercial use requires a paid license.

Website, pricing and FAQ: ebicsclient.miniapps.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, and key rotation — 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. Not yet built: multi-person signatures (EDS/VEU) and several administrative order types. 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 Dual-licensing plan, legal reasoning, reimplementation
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

Source-available under the PolyForm Noncommercial License 1.0.0 — free for noncommercial use; commercial/business use requires a paid license, see pricing. See LICENSE.md and the rationale in docs/02-licensing-strategy.md.

Metadata

Release files for ebicsclient 1.9.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 1.9.0
File Size Uploaded Provenance Actions
ebicsclient-1.9.0.tar.gz 363.7 kB With provenance Details for ebicsclient-1.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ebicsclient 1.9.0
File Interpreter ABI Platform Actions
ebicsclient-1.9.0-py3-none-any.whl Python 3 none any Details for ebicsclient-1.9.0-py3-none-any.whl

Total release size: 474.6 kB

Release files / ebicsclient-1.9.0.tar.gz

Download URL ebicsclient-1.9.0.tar.gz
Size 363.7 kB
Tags Source
SHA-256 checksum
How to use checksums
62d0c58edc2f1a4cd14b455c9113daaa18583293e14d4d267dc8eea11e84d66a
BLAKE2b-256 checksum
How to use checksums
aac8529bfb00212739782f001025c59be3f3a3fa8194645253c382a7f473aef8
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 28, 2026.

Transparency log

Release files / ebicsclient-1.9.0-py3-none-any.whl

Download URL ebicsclient-1.9.0-py3-none-any.whl
Size 110.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d475840a0e5811c86cefaa2b3d1f16efc3b3aebc393eaf9f25b8638fdeb60b5e
BLAKE2b-256 checksum
How to use checksums
8f46f896c87750e731fb0513d3a64ac0cb32e98d2320d70ff32d28a3b21b271e
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 28, 2026.

Transparency log

Security for ebicsclient 1.9.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-1.9.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 28, 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