# FinTS Connector

The FinTS connector can run embedded in the main API or in the separate local
agent. Embedded mode is the default for local/self-hosted installs, so users do
not need to start a second process.

The privacy tradeoff is explicit:

- Embedded mode: the API process receives PIN/TAN inputs while a FinTS job runs.
- Separate local-agent mode: PIN/TAN inputs stay in the separate local process.

In both modes, PINs are not stored in the database. Normalized observations are
stored only when you import them.

## Required Inputs

- `--blz` or `MOUSEHOLD_FINTS_BLZ`: bank identifier/BLZ.
- `--server` or `MOUSEHOLD_FINTS_SERVER`: FinTS endpoint URL.
- `--bank-user-id` or `MOUSEHOLD_FINTS_USER_ID`: your bank login ID.
- PIN: prompted interactively by default, or provided through `MOUSEHOLD_FINTS_PIN`.
- `--product-id` or `MOUSEHOLD_FINTS_PRODUCT_ID`: required by python-fints 4+.
  Register a product ID with Deutsche Kreditwirtschaft/ZKA before connecting.
- Optional `--customer-id`, `--tan-medium`, and `--product-version`.

## comdirect

The web UI has a `comdirect` preset.

Current values:

```text
BLZ: 20041111
FinTS endpoint: https://fints.comdirect.de/fints
Bank user ID: your comdirect Zugangsnummer
Customer ID: leave empty
```

If your account uses a different comdirect/Commerzbank GF comdirect BLZ, replace
the preset BLZ before fetching accounts.

## Local State

The connector stores non-PIN client state in:

```text
~/.config/mousehold/fints/<profile>.json
```

This caches bank parameter data, selected TAN mechanism, and selected TAN
medium so repeated syncs do not ask the same setup questions. The file is
written with mode `0600`.

Use `--no-state` for a one-off session without reading or writing that cache.

## Commands

The browser UI uses the embedded API route by default:

```text
http://127.0.0.1:8001/agent/fints/...
```

To use a separate local-agent HTTP bridge instead:

```sh
mousehold-agent serve --host 127.0.0.1 --port 8765
```

Then set `VITE_LOCAL_AGENT_URL=http://127.0.0.1:8765` in
`apps/web/.env.development`.

List accounts:

```sh
mousehold-agent fints-accounts \
  --profile my-bank \
  --blz <bank-blz> \
  --server <fints-endpoint-url> \
  --bank-user-id <bank-login-id> \
  --with-balances
```

Display transactions:

```sh
mousehold-agent fints-transactions \
  --profile my-bank \
  --blz <bank-blz> \
  --server <fints-endpoint-url> \
  --bank-user-id <bank-login-id> \
  --iban <iban> \
  --start-date 2026-06-01 \
  --end-date 2026-06-27
```

Sync transactions into Mousehold:

```sh
mousehold-agent sync-fints \
  --api-url http://127.0.0.1:8001 \
  --connection-id <connection-id> \
  --household-id <household-id> \
  --owner-user-id <user-id> \
  --source-account-id <account-id> \
  --profile my-bank \
  --blz <bank-blz> \
  --server <fints-endpoint-url> \
  --bank-user-id <bank-login-id> \
  --iban <iban> \
  --days 30 \
  --display
```

## TAN Handling

If the bank returns a TAN challenge, the CLI prints the challenge text and asks
for the TAN. Decoupled app confirmation flows prompt you to confirm in the
banking app and press Enter. Binary challenge images are written under:

```text
~/.config/mousehold/fints/challenges/
```

## Ledger Mapping

FinTS transactions are imported as `source_type = "fints"` and
`status = "confirmed"`.

- Positive bank movements become `income`.
- Ordinary negative bank movements become `expense`.
- Negative movements mentioning PayPal, Klarna, or credit-card providers become
  `liability_payment`, so they can later be linked to prior obligations instead
  of becoming duplicate household expenses.