kvitt/docs/spikes/K0-enable-banking.md

# K0: Enable Banking and the SJ Prio Mastercard

Date: 2026-10-24. Plan `PLAN-K0.md` (D-176). Tool: the local test app `docs/spikes/k0/app.py` as committed in `2ce317f`, run on the owner's MacBook against Enable Banking's production API in restricted mode, with the owner's own SJ Prio Mastercard and his BankID. The application's key, the session and every fetched transaction stayed in the git-ignored `docs/spikes/k0/.local/`. This report holds aggregates only: no names, merchant texts, amounts, purchase dates, identifiers, the application id or the card number. Recorded in SPEC v0.36 (D-177 to D-180).

## 1. What was tested

| Step | What | Result |
|---|---|---|
| Account and licence | Enable Banking sign-up, Terms of Service accepted by the owner (the "Licences first" step) | done |
| Application | Restricted production application, redirect URL `https://kvitt.suorra.duckdns.org/cards/callback` | registered; the key file downloaded and moved to `.local/` |
| Redirect URL | `http://localhost:8765/callback` in the production control panel | refused: "uses unsupported scheme" |
| Activation | Control panel › "Activate by linking accounts", the owner's card, BankID | worked; the application runs in restricted mode |
| Bank list | `GET /aspsps?country=SE` | 126 Swedish ASPSPs, SJ Prio among them (§2) |
| Connect | `POST /auth`, BankID by QR, the redirect address pasted back into the app, `POST /sessions` | worked (the callback page does not load yet, as expected; the address bar kept `code` and `state`) |
| Session | `GET /sessions/{id}` | 1 account (§3) |
| User-present fetch | transactions with `Psu-Ip-Address` and `Psu-User-Agent` | HTTP 200 |
| Background fetch | transactions without any PSU header | HTTP 200 |
| History depth | 7, 30, 90 and 180 days back; five consecutive 30-day windows | §4 |
| Fields | presence and shape over a 100-row fetch | §5 |

Not run (owner's decision, 2026-10-24: "let's just assume it all works now given your test"): linking the partner's card and fetching it (PLAN-K0 §8 steps 6 and 10), and the next-day repeat (step 9). §7 lists what is assumed instead and where it is verified.

## 2. The ASPSP

| Field | Value |
|---|---|
| `name` | `SJ Prio Mastercard` (exactly) |
| `country` | `SE` |
| `beta` | false |
| `maximum_consent_validity` | 15552000 s (180 days) |
| `psu_types` | [`personal`] |
| auth method | `REDIRECT` |
| `required_psu_headers` | [`psu-ip-address`] (lower case as listed) |

## 3. Session and consent

* One account in the session, currency SEK, `cash_account_type` `CARD`.
* `access.valid_until` asked for now + 180 days − 5 minutes (the ASPSP's maximum is 180 days, equal to the cap); the session returned `valid_until` 2027-04-22.
* User-present fetch (`Psu-Ip-Address`, `Psu-User-Agent`) and background fetch (no PSU header): both HTTP 200. Only one background fetch was made, so the number accepted per 24 hours is not measured.

## 4. History and the 100-row cap

Every transactions response held at most 100 rows and never a `continuation_key`.

| Request | Rows | Note |
|---|---|---|
| 7 days, default strategy | 12 | |
| 30 days, default strategy | 52 | |
| 90 days, default strategy | 100 | covers only the newest 60 days: older rows are cut |
| 180 days, `strategy=longest` | 100 | neither the newest 100 nor a contiguous range: a mixed selection |
| five consecutive 30-day windows, `date_from` and `date_to`, 150 days back | 67, 85, 55, 49, 52 | all HTTP 200, no continuation key, 308 distinct rows in total |

The five-window series asked with both `date_from` and `date_to`; the committed app's form sends only `date_from`.

Findings:

* A range longer than the card's 100-row cap loses rows silently: no error, no continuation key. The fix is fetching in windows (D-178): at most 30 days each, and a window that returns 100 rows is split in half and fetched again.
* At least 150 days of history were reachable right after BankID (the oldest window answered HTTP 200 with rows). The 180-day choice stays.
* No `WRONG_TRANSACTIONS_PERIOD` was seen.
* Rows returned for a window can have booking dates one or two days outside the requested window (the bank seems to filter on another date), so windows overlap in what they return. De-duplication across windows by `entry_reference` gave the 308 distinct rows.

## 5. Transaction fields (100-row sample)

| Field | Presence | Notes |
|---|---|---|
| `entry_reference` | 100 % | also on both pending rows; all unique; unchanged between two fetches |
| `transaction_id` | 100 % | not used (Enable Banking: "may change") |
| `booking_date` | 98 % | missing exactly on the pending rows |
| `value_date` | 100 % | |
| `transaction_date` | 0 % | |
| `remittance_information` | 100 % | exactly one line on every row; it is the merchant text |
| `creditor.name` | 0 % | |
| `creditor.postal_address.country` | 100 % | SE 79, DE 14, IE 5, EE 2 |
| `creditor.postal_address.town_name` | 97 % | |
| `debtor.name` | 96 % | one distinct value: the card holder |
| `debtor_account.other.identification` | 97 % | `scheme_name` `CPAN`; one distinct value, a masked card number |
| `bank_transaction_code.code` | 100 % | `PURCHASE` 92, `PAYMENT` 5, `UNKNOWN` 2, `FEE` 1 |
| `merchant_category_code`, `exchange_rate`, `balance_after_transaction`, `note`, `reference_number` | 0 % | |

* Amounts: positive decimal strings with a point; the sign comes from `credit_debit_indicator`.
* Currency: every row `SEK`, purchases at German, Irish and Estonian merchants included (`exchange_rate` empty). The card account reports foreign purchases already converted to SEK.
* Status: `BOOK` 98, `PDNG` 2. Direction: `DBIT` 98, `CRDT` 2.
* Credits: both `CRDT` rows were `PAYMENT` rows, payments of the card bill. No refund in the sample.

## 6. Answers to the K0 `TODO(spec)` items (SPEC v0.35 §9.12)

| Item | Answer | SPEC v0.36 |
|---|---|---|
| CP-1 ASPSP name and country | `SJ Prio Mastercard`, `SE` (measured) | the registry entry uses them |
| CP-2 account pick with several accounts | the session has 1 account (`CARD`), so the rule is untested | the default rule stays: the first `CARD` account, else the first |
| CP-3 history depth right after BankID | at least 150 days (measured with windows) | 7, 30, 90, 180 stay; default 30 |
| CP-4 background fetch without PSU headers | accepted, HTTP 200 (one fetch) | the 4-per-24-hours rule stays as written |
| CP-5 `required_psu_headers` and acceptance | [`psu-ip-address`]; a fetch with `Psu-Ip-Address` and `Psu-User-Agent` was accepted (from the MacBook) | send those two, compare names case-insensitively; from the Pi it is checked by K1's owner steps |
| CP-6 `maximum_consent_validity` | 15552000 s = 180 days; the session ran to 2027-04-22 | `valid_until` = now + 180 days − 5 min |
| CP-7 `strategy=longest` | 100 rows, a mixed selection; the cap is 100 rows per response with no continuation key | windowed fetch (D-178); `strategy` is never sent |
| CP-7 dates | `booking_date` on booked rows, `value_date` on all, `transaction_date` never | `purchase_date` = `booking_date`, else `value_date` |
| CP-7 foreign purchases in SEK | yes | the non-SEK path stays as a safeguard |
| CP-7 merchant field | `remittance_information` (one line); `creditor.name` never present | merchant = `remittance_information`, else `creditor.name`, else "Kortköp" |
| CP-8 pending → booked | `entry_reference` is present on pending rows; the change to booked was not observed | owner's assumption: the reference is kept; the amount-and-date rule stays as the secondary rule |
| CP-8 credits | 2 of 100, both card-bill payments | stored, shown only under "Alla", no action (unchanged) |
| CP-13 partner's card on the owner's application | not tried | owner's assumption: yes; the per-user application (D-175) stays as the fallback |

Further rules from the field survey (D-179): `bank_transaction_code` is not used and the direction alone decides, so a debit `FEE` row is a purchase to handle (the holder turns it into an expense or ignores it). The holder's name, the masked card number (`CPAN`) and the merchant's address are never stored, logged or shown.

## 7. Assumed, not measured (owner's decision, 2026-10-24)

| Assumption | Why it is reasonable | Verified by |
|---|---|---|
| The partner's card can be linked to the owner's application and fetched | restricted mode serves the accounts linked in the application's control panel; linking is per account with the account holder's BankID | PLAN-K1 §8 step 5 (with the fallback of D-175 if refused) |
| A pending row keeps its `entry_reference` when it is booked | the reference is present on pending rows and stable between fetches | PLAN-K1 §8 step 7 (the `card_fetch` counters and the owner's yes/no) |
| The session is reused the next day without BankID | the consent runs to 2027-04-22 | PLAN-K1 §8 step 6 |

## 8. Results (owner's run)

| Owner step (PLAN-K0 §8) | Result |
|---|---|
| 1 Sign up, accept the Terms of Service | yes |
| 2 Production application with the callback URL; the key downloaded | yes |
| 3 Key moved into `docs/spikes/k0/.local/` | yes |
| 4 NPM `/cards/callback` block (optional) | not recorded; it is part of K1's NPM step |
| 5 "Activate by linking accounts" with the owner's card | yes |
| 6 The partner's card | not run (assumed, §7) |
| 7 Connect with BankID, paste the address, the card account shown | yes, 1 account |
| 8 "Uppdatera" and "Bakgrundshämtning" | both fetched (HTTP 200) |
| 9 The next day without BankID | not run (assumed, §7) |
| 10 The partner's run | not run (assumed, §7) |

The key file stays only in the main checkout's git-ignored `docs/spikes/k0/.local/`; K1's owner steps copy it to the Pi (`~/kvitt/secrets/cards/`, D-175).