Metadata-Version: 2.5
Name: ebicsclient
Version: 2.0.0
Summary: Pure-Python client for the EBICS 3.0 (H005) banking protocol
Project-URL: Homepage, https://ebicsclient.ch
Project-URL: Repository, https://github.com/schulluk/ebicsclient
Project-URL: Issues, https://github.com/schulluk/ebicsclient/issues
Project-URL: Changelog, https://github.com/schulluk/ebicsclient/blob/main/CHANGELOG.md
Author: Lukas Schulze
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: banking,camt,ebics,fintech,h005,iso20022
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cryptography
Requires-Dist: lxml
Provides-Extra: pdf
Requires-Dist: reportlab; extra == 'pdf'
Provides-Extra: tls
Requires-Dist: certifi; extra == 'tls'
Description-Content-Type: text/markdown

# 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](https://ebicsclient.ch)**

## Install

```console
pip install ebicsclient          # add [pdf] for PDF letters, [tls] for the certifi CA bundle
```

## Quickstart

```python
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](https://github.com/schulluk/ebicsclient/blob/main/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/](https://github.com/schulluk/ebicsclient/blob/main/examples/README.md).

> ### ⚠️ 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](https://github.com/schulluk/ebicsclient/issues) or write to the maintainer via
[ebicsclient.ch](https://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](https://github.com/schulluk/ebicsclient/blob/main/docs/13-standard-conformance.md)**.

## Why this exists

It was built for [WealthTracker](https://github.com/schulluk/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](https://github.com/schulluk/ebicsclient/blob/main/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](https://github.com/schulluk/ebicsclient/blob/main/docs/01-protocol-and-formats.md); the scope
decision in [docs/04](https://github.com/schulluk/ebicsclient/blob/main/docs/04-implementation-plan.md).

## Documentation

| Doc | Contents |
|---|---|
| [docs/01-protocol-and-formats.md](https://github.com/schulluk/ebicsclient/blob/main/docs/01-protocol-and-formats.md) | EBICS/H005 background, the two regulatory deadlines, message formats |
| [docs/02-licensing-strategy.md](https://github.com/schulluk/ebicsclient/blob/main/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](https://github.com/schulluk/ebicsclient/blob/main/docs/03-library-landscape.md) | Existing EBICS libraries and the gap this library fills |
| [docs/04-implementation-plan.md](https://github.com/schulluk/ebicsclient/blob/main/docs/04-implementation-plan.md) | Scope, modules, the two hard parts, build order, test strategy |
| [docs/05-zkb-onboarding.md](https://github.com/schulluk/ebicsclient/blob/main/docs/05-zkb-onboarding.md) | The INI/HIA + signed-letter ceremony, re-initialisation, ZKB order params |
| [docs/06-engineering-conventions.md](https://github.com/schulluk/ebicsclient/blob/main/docs/06-engineering-conventions.md) | Baseline practices: layout, logging, errors, security, typing, testing, CI |
| [docs/07-handshake-testing.md](https://github.com/schulluk/ebicsclient/blob/main/docs/07-handshake-testing.md) | Validating INI/HIA/HPB + download/upload against the ZKB test platform |
| [docs/08-parity-and-xsd-findings.md](https://github.com/schulluk/ebicsclient/blob/main/docs/08-parity-and-xsd-findings.md) | The inclusive-vs-exclusive c14n correction and verification discipline |
| [docs/09-zkb-test-platform-settings.md](https://github.com/schulluk/ebicsclient/blob/main/docs/09-zkb-test-platform-settings.md) | What the ZKB test platform exposes, and its upload/simulation model |
| [docs/10-btf-order-types.md](https://github.com/schulluk/ebicsclient/blob/main/docs/10-btf-order-types.md) | ZKB's EBICS order-type → H005 BTF catalogue |
| [docs/11-certificate-profiles.md](https://github.com/schulluk/ebicsclient/blob/main/docs/11-certificate-profiles.md) | "mit Schlüsseln" vs "mit Zertifikaten", and the certificate seam |
| [docs/12-verification-ledger.md](https://github.com/schulluk/ebicsclient/blob/main/docs/12-verification-ledger.md) | Every protocol claim → spec citation → oracle → status; the 2.5→3.0 audit |
| [docs/13-standard-conformance.md](https://github.com/schulluk/ebicsclient/blob/main/docs/13-standard-conformance.md) | Coverage & gaps: every H005 order type — supported or not, and how far verified |
| [docs/14-postfinance-test-platform.md](https://github.com/schulluk/ebicsclient/blob/main/docs/14-postfinance-test-platform.md) | The PostFinance test platform: BTF catalogue, behaviour, settings, and what is validated there |

## Development

Contributors: see [CONTRIBUTING.md](https://github.com/schulluk/ebicsclient/blob/main/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](https://github.com/schulluk/ebicsclient/blob/main/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](https://github.com/schulluk/ebicsclient/blob/main/LICENSE) and
[NOTICE](https://github.com/schulluk/ebicsclient/blob/main/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](https://github.com/schulluk/ebicsclient/blob/main/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](https://github.com/schulluk/ebicsclient/issues) 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](https://github.com/schulluk/ebicsclient/blob/main/docs/12-verification-ledger.md)
  and [docs/13](https://github.com/schulluk/ebicsclient/blob/main/docs/13-standard-conformance.md).
  Anything not listed there is untested.
