enable-banking-api

name	enable-banking-api
description	Domain knowledge about the Enable Banking Open Banking API. Reference this when working with API-based bank sync.

Enable Banking API

Purpose

Provides domain knowledge about the Enable Banking Open Banking API — endpoints, authentication, session lifecycle, transaction structure, rate limits, and supported Danish banks. Reference this when orchestrating tools/eb-api.py for API-based transaction sync.

API Overview

Enable Banking provides PSD2-compliant access to bank account data across 2,500+ European banks. SmartSpender uses it as an alternative to browser automation for faster, more reliable transaction sync.

• API Base URL: https://api.enablebanking.com
• Authentication: JWT signed with RSA private key (PS256 algorithm)
• Data Format: JSON, ISO 20022 inspired field names
• Rate Limit: Max 4 account information requests per day per account (PSD2 regulation)

Authentication

JWT Structure

The eb-api.py helper handles JWT generation. Conceptually:

• Issuer: enablebanking.com
• Audience: api.enablebanking.com
• Algorithm: PS256 (RSA-PSS with SHA-256)
• Expiry: 1 hour from creation
• Payload: includes app_id from config

Config File

Stored at ~/.config/smartspender/eb-config.json:

{
  "app_id": "your-application-id",
  "key_path": "~/.config/smartspender/private.pem"
}

Session Lifecycle

Consent Flow

1. Initiate: eb-api.py auth --bank <name> sends POST to /auth with ASPSP details and redirect URL (https://smartspender.mentilead.com/callback.html)
2. MitID: User authenticates in browser (auto-opened)
3. HTTPS Relay: Bank redirects to callback.html which forwards code to http://localhost:19876/callback
4. Capture: Localhost listener on port 19876 catches the authorization code
5. Session: Code exchanged for session_id via POST to /sessions
6. Active: Session provides access to account data for 90-180 days

Session States

State	Meaning	Action
active	Consent valid, API accessible	Proceed with sync
expired	Consent period ended	Re-run auth for new consent
revoked	Bank-side revocation	Re-run auth
no_session	No session file exists	Run setup + auth

Session File

Stored at ~/.config/smartspender/eb-session.json:

{
  "session_id": "uuid-string",
  "accounts": [
    {
      "uid": "account-uid-string",
      "account_id": {"iban": "DK1234567890123456"},
      "name": "Lønkonto",
      "currency": "DKK",
      "product": "Checking Account"
    }
  ],
  "consent_expires": "2026-05-02T12:00:00.000Z",
  "created_at": "2026-02-02T12:00:00+00:00",
  "fetch_log": {}
}

API Endpoints

POST /auth

Initiate consent. Returns url for user to visit.

POST /sessions

Exchange authorization code for session. Returns session_id and accounts.

GET /sessions/{session_id}/accounts

List accounts linked to the session. Returns account UIDs, IBANs, names, currencies.

GET /accounts/{uid}/transactions

Fetch transactions. Parameters:

• date_from (required): YYYY-MM-DD
• date_to (optional): YYYY-MM-DD (defaults to today)
• continuation_key (optional): for pagination

GET /accounts/{uid}/balances

Fetch current balances. Returns balance type, amount, currency, and date.

Response structure:

{
  "balances": [
    {
      "balance_amount": {"amount": "12543.25", "currency": "DKK"},
      "balance_type": "CLBD",
      "reference_date": "2026-02-03"
    },
    {
      "balance_amount": {"amount": "12100.00", "currency": "DKK"},
      "balance_type": "ITAV",
      "reference_date": "2026-02-03"
    }
  ]
}

Balance type codes:

Type	Description	Use Case
CLBD	Closing booked balance	End of day settled — most accurate, prefer this
ITAV	Intraday available	Current available funds — fallback if CLBD missing
XPCD	Expected balance	Projected balance including pending

Parsing priority: Prefer CLBD over ITAV over XPCD. Extract balance_amount.amount as the balance value.

Transaction Structure

Enable Banking returns transactions in this JSON format:

{
  "bank_transaction_code": {"code": "12", "description": "Kortbetaling"},
  "booking_date": "2026-01-15",
  "booking_date_time": "2026-01-15T14:30:00Z",
  "credit_debit_indicator": "DBIT",
  "creditor": {"name": "FØTEX"},
  "debtor": {"name": "Peer Jakobsen"},
  "entry_reference": "5561990681",
  "remittance_information": ["Dankort-køb", "FØTEX 4123"],
  "status": "BOOK",
  "transaction_amount"    
        
   

Key Fields

Field	Description
booking_date	Transaction date (already YYYY-MM-DD)
credit_debit_indicator	DBIT = debit (expense), CRDT = credit (income)
transaction_amount.amount	Positive number as string
transaction_amount.currency	ISO currency code
creditor.name	Recipient (present on debits)
debtor.name	Sender (present on credits)
remittance_information	Array of description strings
balance_after_transaction	Running balance (for tx_hash)
status	BOOK (booked), PDNG (pending), INFO (informational)
entry_reference	Bank's reference number
bank_transaction_code	Transaction type code and description

Transaction Status Values

• BOOK: Booked, final — include in sync
• PDNG: Pending, not yet final — skip (may change or disappear)
• INFO: Informational, not a real transaction — skip

Only sync transactions with status: BOOK.

PSD2 Rate Limits

Regulation

PSD2 (Payment Services Directive 2) limits account information requests to 4 per day per account. This is a European banking regulation, not an Enable Banking or SmartSpender limitation.

Rate Limit Strategy

• eb-api.py tracks fetches per account per day in the session file
• Before each fetch, check the count. Warn at 3/4, block at 4/4
• A single eb-api.py transactions call counts as 1 fetch regardless of pagination
• Balances and account list queries are also rate-limited

Practical Impact

• Sync once per day during normal use
• If testing, be mindful of the 4/day limit
• Rate resets at midnight UTC
• Error when exceeded: rate_limit with message explaining the constraint

Supported Danish Banks

Enable Banking supports these Danish banks (non-exhaustive):

Major Banks

• Nykredit
• Danske Bank
• Nordea
• Jyske Bank
• Sydbank
• Spar Nord

Digital Banks

• Lunar
• Bank Norwegian

Cooperative Banks (via BEC/Bankdata)

• Arbejdernes Landsbank
• Vestjysk Bank
• Ringkjøbing Landbobank
• Sparekassen Danmark
• Plus 50+ smaller banks

ASPSP Names

When running eb-api.py auth --bank <name>, use the bank's name as registered with Enable Banking. Common Danish bank names:

• Nykredit (not "nykredit" — use proper case)
• Danske Bank
• Nordea
• Jyske Bank
• Sydbank
• Lunar

Error Codes

Error	Meaning	Resolution
401 Unauthorized	JWT invalid or expired	Check RSA key and app_id
403 Forbidden	Consent missing or expired	Re-run auth for new consent
404 Not Found	Invalid session or account UID	Verify session is active
429 Too Many Requests	PSD2 rate limit exceeded	Wait until tomorrow
503 Service Unavailable	Bank API temporarily down	Retry later

Related Skills

• skills/data-schemas/SKILL.md — Common transaction schema and CSV file structures including accounts.csv with EB fields

Known Limitations

• PSD2 rate limit (4/day/account) means no real-time balance checking
• Transaction descriptions from API may differ from browser export CSV (banks format them differently)
• balance_after_transaction is optional — some banks don't provide it for all transaction types
• Session can be revoked bank-side without notice (user changed consent settings)
• ASPSP names must match Enable Banking's registry (case-sensitive)