Banking and Financial Data Domain

Overview

This part of the backend turns provider-specific banking payloads into a consent-driven, provider-agnostic flow for the housing application domain. It covers Plaid consent exchange, Plaid token attachment to housing applications, balance and transaction refreshes, Salt Edge onboarding and connection lookups, and the canonical data adapter used by downstream scoring and analytics code.

The main business value is consistency: Plaid and Salt Edge inputs arrive in different shapes, but the backend stores them and consumes them through a shared consent and canonical-data layer. That lets later use cases operate on normalized bank data instead of provider-specific envelopes.

Architecture Overview

flowchart LR
    subgraph InterfaceLayer[Interface Layer]
        OBEP[open_banking_endpoints]
        SEP[saltedge_endpoints]
        HTTP[http_endpoints]
    end

    subgraph UseCaseLayer[Use Case Layer]
        OBUC[open_banking]
        AD[account_detection]
        ADAPT[credit_adapters]
    end

    subgraph PersistenceLayer[Persistence Layer]
        OBR[SQLOpenBankingConsentRepository]
        HAR[SQLAlchemyHousingApplicationRepository]
        DB[get_db]
    end

    subgraph ProviderLayer[Provider Layer]
        PBG[PlaidBankGateway]
        PKG[PlaidKycGateway]
        SC[SaltEdgeClient]
        SPC[SaltEdgePartnersClient]
    end

    subgraph CanonicalLayer[Canonical Data Layer]
        COBS[CanonicalOpenBankingData]
    end

    OBEP -->|consent sync and refresh| OBUC
    OBEP -->|operator checks| OBR
    OBEP -->|application lookup| HAR
    OBEP -->|Plaid exchange and retrieval| PBG
    OBEP -->|transaction retrieval| PKG

    SEP -->|Salt Edge connect URL| SC
    HTTP -->|lead session and connection lookup| SPC

    OBUC -->|consent persistence| OBR
    OBUC -->|application account scan| AD
    ADAPT -->|normalise Plaid payloads| COBS
    ADAPT -->|normalise Salt Edge payloads| COBS
    ADAPT -->|normalise connected accounts| COBS

Canonical Open Banking Data and Provider Abstraction

The provider abstraction is implemented in OpenBankingAdapter, which normalizes Plaid, Salt Edge, and generic connected-account payloads into CanonicalOpenBankingData. That canonical model is what downstream scoring code expects.

CanonicalOpenBankingData

backend/src/ml/credit_canonical_schema.py

Properties

Property Type Description
provider str Provider label for the canonical record: plaid, saltedge, finverse, manual, mixed, or a preserved single provider name
institutions list[str] Provider or institution labels collected from the source payload
accounts_count int Number of account records found after normalization
days_covered int Calendar span covered by transaction history
transactions_90d list[CanonicalTransaction] Normalized transactions inside the 90-day window
balance_snapshots_usd list[float] USD-normalized balance readings
raw dict[str, Any] Original source payload when the source is a dict

OpenBankingAdapter

backend/src/ml/credit_adapters.py

Public Methods

Method Description
from_connected_accounts Normalizes generic connected-account payloads into CanonicalOpenBankingData
from_plaid Merges Plaid accounts and transactions by account_id, then normalizes the result
from_saltedge Normalizes Salt Edge data envelopes into canonical open banking data

Normalization Rules

  • from_connected_accounts accepts:
    • a dict of provider names to payloads
    • a bare list, which is wrapped under "default"
    • non-dict input, which becomes CanonicalOpenBankingData(provider="unknown")
  • Provider names are tracked in providers_seen and collapsed into:
    • plaid
    • saltedge
    • finverse
    • a single preserved provider name
    • mixed
  • Bureau-only keys are skipped during ingestion.
  • Balance snapshots are converted to USD from:
    • balances[*].balance
    • balances.current
    • balance
  • Transaction values are normalized to:
    • 90-day window only
    • absolute USD amounts
    • lowercased categories
    • inferred directions when missing
    • counterparty_hash or counterparty

Normalization Flow

sequenceDiagram
    participant Source as Provider Payload
    participant Adapter as OpenBankingAdapter
    participant Canonical as CanonicalOpenBankingData
    participant Downstream as Scoring and Analytics

    Source->>Adapter: from_plaid or from_saltedge or from_connected_accounts
    Adapter->>Adapter: merge accounts and filter 90 day transactions
    Adapter->>Adapter: convert balances and transaction amounts to USD
    Adapter->>Adapter: infer provider and clean categories
    Adapter->>Canonical: return normalized record
    Canonical->>Downstream: consumed by scoring and analytics

Provider-Specific Entry Points

  • from_plaid:
    • reads top-level accounts
    • reads top-level transactions
    • merges transactions by account_id
    • uses institution.name, institution.institution_id, or "plaid" for the grouping key
    • sets final provider to "plaid"
  • from_saltedge:
    • reads payload["data"] or the payload itself
    • reads connection.provider_name or connection.country_code
    • groups accounts under that key
    • sets final provider to "saltedge"

Open Banking Use Cases

[!NOTE] from_plaid and from_saltedge both delegate to from_connected_accounts, then overwrite the canonical provider field to the provider-specific label.

backend/src/usecase/open_banking.py

backend/src/usecase/account_detection.py

These use cases bridge housing applications, consent storage, and Plaid retrieval flows. They are the business layer behind the open banking endpoints.

Public Functions

Function Description
_normalise_string Trims string values and returns None for blank input
_extract_plaid_connections Scans connected_accounts and groups Plaid records by access token
_ensure_active_consent Validates consent existence, active status, operator access, and token presence
attach_plaid_tokens Stores Plaid access tokens and item IDs on an existing consent
sync_application_plaid_consents Creates or updates consent records from a housing application’s Plaid-linked accounts
trigger_refresh Fetches balances and transactions for a consent and records a refresh event
auto_refresh_due_consents Refreshes due consents that have auto-refresh enabled
_collect_plaid_entries Extracts Plaid access-token keyed entries from connected-account records

sync_application_plaid_consents consumes application.connected_accounts and extracts Plaid records via _extract_plaid_connections. Each access token is hashed with SHA-256 to derive a stable consent reference suffix, then the repository is checked for an existing consent.

If the consent already exists, the use case updates:

  • customer_reference
  • customer_name
  • expires_at
  • metadata
  • auto_refresh_enabled
  • application_id

If it does not exist, it creates a new consent through register_consent with:

  • scopes=("balances:read", "transactions:read")
  • auto_refresh_enabled=True
  • auto_refresh_interval_minutes=720

Finally, attach_plaid_tokens persists the Plaid access token and item_id.

Refresh Flow

trigger_refresh validates the consent through _ensure_active_consent, then:

  • gets balances through bank_gateway.get_balances(consent.plaid_access_token or "")
  • gets transactions through transactions_gateway.fetch_transactions(...)
  • updates consent.last_refreshed_at only when refresh succeeds
  • records an OpenBankingRefreshEvent
  • raises OpenBankingRefreshFailed when retrieval fails

auto_refresh_due_consents applies the same retrieval path to all active consents that are due for refresh and have auto_refresh_enabled=True. It records success and failure events per consent.

Plaid Entry Extraction Helper

_collect_plaid_entries is the lower-level Plaid account detection helper. It iterates connected account records, keeps only Plaid entries, groups them by access token, and captures:

  • account_ids
  • connection_name
  • institution_name

This makes Plaid-linked records searchable by token and preserves the connection metadata needed by consent-sync and risk flows.

  • sync_application_plaid_consents sets the consent up for auto-refresh immediately.
  • _ensure_active_consent requires the consent to be active, authorized, and token-backed before refresh.
  • trigger_refresh stores last_refreshed_at only on success.
  • auto_refresh_due_consents silently skips missing-token and ineligible consent records.
  • Refresh failures are recorded as events even when the use case does not return a success result.

Open Banking API Endpoints

backend/src/interface/open_banking_endpoints.py

Dependency Providers

Function Description
get_repository Creates SQLOpenBankingConsentRepository from the SQLAlchemy session
get_housing_repository Creates SQLAlchemyHousingApplicationRepository from the SQLAlchemy session
get_bank_gateway Returns PlaidBankGateway
get_transactions_gateway Returns PlaidKycGateway

ConsentResponse

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent identifier used by the API
customer_reference str Customer identifier stored with the consent
customer_name Optional[str] Human-readable customer name
application_id Optional[int] Housing application ID linked to the consent
scopes List[str] OAuth-style consent scopes
expires_at datetime Consent expiration timestamp
revoked_at Optional[datetime] Revocation timestamp when present
allowed_operator_ids List[str] Operators allowed to view or manage the consent
metadata Dict[str, Any] Consent metadata, including application and token fingerprint data
plaid_item_id Optional[str] Plaid item identifier
auto_refresh_enabled bool Whether automatic refresh is enabled
auto_refresh_interval_minutes int Refresh interval in minutes
last_refreshed_at Optional[datetime] Last successful refresh timestamp
created_at Optional[datetime] Creation timestamp
updated_at Optional[datetime] Update timestamp

Refresh Response Model

RefreshResponse

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent identifier that was refreshed
status str Refresh outcome
refreshed_at datetime Timestamp for the refresh result
balances Dict[str, Any] Retrieved balances payload
transactions Dict[str, Any] Retrieved transactions payload
error_message Optional[str] Failure message when the refresh did not succeed

Repatriation Risk Request Model

RepatriationRiskRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
lookback_days int Window size for risk analysis, default 90
min_home_country_transactions int Minimum count required to flag a result, default 3
min_home_country_share float Minimum share threshold for home-country activity, default 0.2

Repatriation Risk Response Model

RepatriationRiskResponse

backend/src/interface/open_banking_endpoints.py

Property Type Description
application_id int Housing application ID
home_country_code str Country code used for analysis
lookback_days int Analysis window
flagged bool Result flag from the risk assessment
home_country_transactions int Count of home-country transactions
total_transactions int Total transactions analyzed
home_country_share float Share of home-country transactions
reasons List[str] Risk reasons emitted by the use case
refreshed_at datetime Latest refresh timestamp computed by the endpoint
latest_home_country_activity Optional[datetime] Most recent home-country activity timestamp

List Application Consents

GET /open-banking/applications/{application_id}/consents

{
    "title": "List Application Consents",
    "description": "Returns consent records linked to a housing application after syncing Plaid connected accounts into consent rows",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/open-banking/applications/{application_id}/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "application_id",
            "value": "123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[\n    {\n        \"consent_reference\": \"application-123-0f9a2d44b1c7\",\n        \"customer_reference\": \"[email protected]\",\n        \"customer_name\": \"Jane Doe\",\n        \"application_id\": 123,\n        \"scopes\": [\n            \"balances:read\",\n            \"transactions:read\"\n        ],\n        \"expires_at\": \"2026-04-26T12:00:00Z\",\n        \"revoked_at\": null,\n        \"allowed_operator_ids\": [\n            \"[email protected]\"\n        ],\n        \"metadata\": {\n            \"application_id\": 123,\n            \"application_email\": \"[email protected]\",\n            \"application_phone\": \"+1 555 123 4567\",\n            \"token_fingerprint\": \"0f9a2d44b1c7e1c4\",\n            \"connection_name\": \"Primary Account\",\n            \"institution_name\": \"Chase\",\n            \"account_ids\": [\n                \"acct-001\"\n            ]\n        },\n        \"plaid_item_id\": \"item-abc\",\n        \"auto_refresh_enabled\": true,\n        \"auto_refresh_interval_minutes\": 720,\n        \"last_refreshed_at\": \"2026-04-26T12:10:00Z\",\n        \"created_at\": \"2026-04-26T11:00:00Z\",\n        \"updated_at\": \"2026-04-26T12:10:00Z\"\n    }\n]"
        }
    }
}

POST /open-banking/consents

{
    "title": "Create Consent",
    "description": "Creates a consent record for a user and stores operator access, expiry, and refresh settings",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/open-banking/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_reference\": \"consent-123\",\n    \"customer_reference\": \"customer-001\",\n    \"customer_name\": \"Jane Doe\",\n    \"expires_at\": \"2026-05-26T12:00:00Z\",\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 60\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Created",
            "body": "{\n    \"consent_reference\": \"consent-123\",\n    \"customer_reference\": \"customer-001\",\n    \"customer_name\": \"Jane Doe\",\n    \"application_id\": null,\n    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2026-05-26T12:00:00Z\",\n    \"revoked_at\": null,\n    \"allowed_operator_ids\": [\n        \"[email protected]\",\n        \"[email protected]\"\n    ],\n    \"metadata\": [],\n    \"plaid_item_id\": null,\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 60,\n    \"last_refreshed_at\": null,\n    \"created_at\": \"2026-04-26T12:00:00Z\",\n    \"updated_at\": \"2026-04-26T12:00:00Z\"\n}"
        }
    }
}

Exchange Public Token

POST /open-banking/consents/{consent_reference}/exchange

{
    "title": "Exchange Public Token",
    "description": "Exchanges a Plaid public token for an access token and stores it against the consent",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/open-banking/consents/{consent_reference}/exchange",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_reference",
            "value": "consent-123",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"public_token\": \"public-sandbox-token-123\",\n    \"consent_expires_at\": \"2026-06-01T12:00:00Z\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_reference\": \"consent-123\",\n    \"customer_reference\": \"customer-001\",\n    \"customer_name\": \"Jane Doe\",\n    \"application_id\": null,\n    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2026-06-01T12:00:00Z\",\n    \"revoked_at\": null,\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"metadata\": [],\n    \"plaid_item_id\": \"item-123\",\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 60,\n    \"last_refreshed_at\": null,\n    \"created_at\": \"2026-04-26T12:00:00Z\",\n    \"updated_at\": \"2026-04-26T12:01:00Z\"\n}"
        }
    }
}

POST /open-banking/refresh

{
    "title": "Refresh Consent",
    "description": "Refreshes a single consent by fetching balances and transactions from Plaid-backed gateways",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/open-banking/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_reference\": \"consent-123\",\n    \"lookback_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_reference\": \"consent-123\",\n    \"status\": \"succeeded\",\n    \"refreshed_at\": \"2026-04-26T12:10:00Z\",\n    \"balances\": {\n        \"acct\": {\n            \"current\": 100\n        }\n    },\n    \"transactions\": {\n        \"transactions\": [\n            {\n                \"transaction_id\": \"txn-1\",\n                \"amount\": 42.5,\n                \"date\": \"2026-04-25\",\n                \"category\": \"groceries\"\n            }\n        ],\n        \"accounts\": [\n            {\n                \"account_id\": \"acct\",\n                \"currency\": \"USD\"\n            }\n        ],\n        \"total_transactions\": 1\n    },\n    \"error_message\": null\n}"
        }
    }
}

Refresh Application Consents

POST /open-banking/applications/{application_id}/refresh

{
    "title": "Refresh Application Consents",
    "description": "Refreshes all accessible consents linked to a housing application and returns one result per consent",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/open-banking/applications/{application_id}/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "application_id",
            "value": "123",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"lookback_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[\n    {\n        \"consent_reference\": \"application-123-0f9a2d44b1c7\",\n        \"status\": \"succeeded\",\n        \"refreshed_at\": \"2026-04-26T12:10:00Z\",\n        \"balances\": {\n            \"acct\": {\n                \"current\": 100\n            }\n        },\n        \"transactions\": {\n            \"transactions\": [\n                {\n                    \"transaction_id\": \"txn-1\",\n                    \"amount\": 42.5,\n                    \"date\": \"2026-04-25\",\n                    \"category\": \"groceries\"\n                }\n            ],\n            \"accounts\": [\n                {\n                    \"account_id\": \"acct\",\n                    \"currency\": \"USD\"\n                }\n            ],\n            \"total_transactions\": 1\n        },\n        \"error_message\": null\n    }\n]"
        }
    }
}

Auto Refresh Due Consents

POST /open-banking/refresh/auto

{
    "title": "Auto Refresh Due Consents",
    "description": "Refreshes all active consent records that are due and have auto refresh enabled",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/open-banking/refresh/auto",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"lookback_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[\n    {\n        \"consent_reference\": \"consent-123\",\n        \"status\": \"succeeded\",\n        \"refreshed_at\": \"2026-04-26T12:10:00Z\"\n    }\n]"
        }
    }
}

Detect Repatriation Risk

POST /open-banking/applications/{application_id}/repatriation-risk

{
    "title": "Detect Repatriation Risk",
    "description": "Computes a repatriation-risk signal using the housing application country and transaction data",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/open-banking/applications/{application_id}/repatriation-risk",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "application_id",
            "value": "123",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"lookback_days\": 30,\n    \"min_home_country_transactions\": 2,\n    \"min_home_country_share\": 0.2\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"application_id\": 123,\n    \"home_country_code\": \"JP\",\n    \"lookback_days\": 30,\n    \"flagged\": true,\n    \"home_country_transactions\": 2,\n    \"total_transactions\": 3,\n    \"home_country_share\": 0.6666666667,\n    \"reasons\": [\n        \"home-country accounts detected\",\n        \"share above threshold\"\n    ],\n    \"refreshed_at\": \"2026-04-26T12:10:00Z\",\n    \"latest_home_country_activity\": \"2026-04-26T00:00:00Z\"\n}"
        }
    }
}

Request and Response Path for Risk Assessment

The endpoint first loads the housing application by ID, then passes:

  • application.country
  • payload.lookback_days
  • payload.min_home_country_transactions
  • payload.min_home_country_share

into detect_repatriation_risk. It also pulls any refreshed timestamps returned by the refresh step and uses the latest ISO timestamp as refreshed_at in the response.

sequenceDiagram
    participant Client as Client
    participant API as Open Banking API
    participant AppRepo as Housing Repository
    participant Risk as detect_repatriation_risk
    participant Tx as Transactions Gateway

    Client->>API: POST repatriation risk
    API->>AppRepo: get housing application
    API->>Risk: detect_repatriation_risk
    Risk->>Tx: fetch transactions by lookback window
    Tx-->>Risk: transactions payload
    Risk-->>API: risk result
    API-->>Client: RepatriationRiskResponse

Salt Edge Models and Endpoints

backend/src/interface/saltedge_endpoints.py

backend/src/interface/http_endpoints.py

Salt Edge handling is split between request and response models in saltedge_endpoints.py and the onboarding-style endpoints in http_endpoints.py.

SaltEdge Endpoint Models

SaltEdgeCustomerData

backend/src/interface/saltedge_endpoints.py

Property Type Description
customer_id str Salt Edge customer identifier
identifier str Customer identifier used by the app
created_at str Creation timestamp

SaltEdgeConnectionData

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Connection identifier
provider_name str Provider name returned by Salt Edge

SaltEdgeAccountData

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Account identifier
connection_id str Parent connection identifier
name str Account name
nature str Account nature
balance float Current balance
currency_code str Account currency
extra Dict[str, Any] Extra account metadata
created_at str Creation timestamp
updated_at str Update timestamp

SaltEdgeAccountListResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
data List[SaltEdgeAccountData] List of Salt Edge account records

SaltEdgeConnectionWithAccountsData

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Connection identifier
provider_name Optional[str] Salt Edge provider name
categorization Optional[str] Connection categorization
accounts List[Dict[str, Any]] Accounts attached to the connection

SaltEdgeConnectionsForCustomerResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
connections List[SaltEdgeConnectionWithAccountsData] Connections returned for a customer

SaltEdgeSingleConnectionResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Connection identifier
customer_id Optional[str] Salt Edge customer identifier
provider_name Optional[str] Provider name
categorization Optional[str] Connection categorization
status Optional[str] Connection status
accounts List[Dict[str, Any]] Attached accounts

SaltEdgeV6ConnectSessionRequest

backend/src/interface/saltedge_endpoints.py

Property Type Description
customer_id str Salt Edge customer identifier
return_to str Redirect target after connect flow
consent_scopes List[str] Default scopes: accounts, transactions, holder_info
categorization str Default categorization: personal

Create Salt Edge Lead Session

POST /saltedge/lead-session

{
    "title": "Create Salt Edge Lead Session",
    "description": "Creates a Salt Edge Partners lead session for onboarding",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/saltedge/lead-session",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"expires_at\": \"2026-04-26T12:30:00Z\",\n    \"redirect_url\": \"https://partners.saltedge.example/connect/session\"\n}"
        }
    }
}

Get Salt Edge Connection

GET /saltedge/connection/{connection_id}

{
    "title": "Get Salt Edge Connection",
    "description": "Fetches a Salt Edge connection and returns the provider and account metadata projected by the backend",
    "method": "GET",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/saltedge/connection/{connection_id}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "connection_id",
            "value": "conn-123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"connection_id\": \"conn-123\",\n    \"provider_name\": \"monzo_uk\",\n    \"provider_code\": \"monzo\",\n    \"categorization\": \"personal\",\n    \"status\": \"active\",\n    \"country_code\": \"GB\",\n    \"customer_id\": \"cust-123\",\n    \"created_at\": \"2026-04-26T12:00:00Z\"\n}"
        }
    }
}

Salt Edge Connect Session Flow

SaltEdgeV6ConnectSessionRequest drives the onboarding connect flow. The backend builds a connect URL using generate_saltedge_connect_url with:

  • user_identifier=request_data.email
  • return_to_url=return_to_for_widget
  • saltedge_client=saltedge_client

When a connect URL is generated successfully, the backend returns:

  • connect_url
  • expires_at
  • customer_id

The handler also defaults return_to to http://localhost:3001/application/review when the request omits it.

Plaid and Open Banking Testing Coverage

backend/tests/ml/test_adapters.py

backend/tests/interface/test_open_banking_endpoints.py

backend/tests/infra/external_apis/test_plaid_transactions_handling.py

backend/test_plaid_balance.py

backend/test_plaid_transactions.py

backend/test_plaid_balance_integration.py

backend/test_plaid_transactions_integration.py

backend/tests/usecase/get_plaid_token.py

Adapter Test Coverage

TestOpenBankingAdapterPlaid

Method What it verifies
test_provider_is_plaid OpenBankingAdapter.from_plaid sets provider to plaid
test_transactions_merged_by_account Plaid transactions are merged by account_id
test_accounts_from_plaid_counted Plaid account count is derived from the merged payload
test_institution_name_used Institution name is preserved in institutions

TestOpenBankingAdapterSaltEdge

Method What it verifies
test_provider_is_saltedge OpenBankingAdapter.from_saltedge sets provider to saltedge
test_gbp_balance_converted_to_usd GBP balances are converted using the USD FX map
test_salary_transaction_captured Salary transaction entries are captured in transactions_90d

TestOpenBankingAdapterConnectedAccounts

Method What it verifies
test_basic_account_count Account count increments for generic connected accounts
test_institution_name_captured Provider key is recorded in institutions
test_usd_balance_captured_unchanged USD balances remain unchanged
test_eur_balance_converted_to_usd EUR balances are converted to USD
test_jpy_transaction_converted_to_usd Transaction amounts inherit account currency conversion
test_transaction_older_than_90d_excluded Transactions older than 90 days are dropped
test_transaction_within_90d_included Transactions inside 90 days are kept
test_days_covered_computed_from_tx_span days_covered follows the transaction span
test_no_transactions_gives_zero_days_covered Empty payloads produce days_covered == 0
test_bureau_key_excluded_from_ob_accounts Bureau-only keys are not counted as bank institutions
test_direction_inferred_from_sign_when_missing Transaction direction is inferred from amount sign
test_plaid_provider_detected Single Plaid inputs resolve to plaid
test_saltedge_provider_detected Single Salt Edge inputs resolve to saltedge
test_single_unknown_provider_name_preserved A single unknown provider name is preserved
test_multiple_providers_gives_mixed Multiple providers resolve to mixed
test_none_payload_gives_empty_canonical None input becomes an empty canonical object
test_list_payload_wrapped_as_default_key Bare lists are wrapped under "default"
test_category_lowercased Categories are normalized to lowercase
test_amount_always_positive_usd Canonical transaction amounts are stored as positive USD values

Endpoint Test Coverage

This test proves the consent lifecycle path:

  1. create consent
  2. exchange public token
  3. auto refresh due consents
  4. manual refresh

It also verifies that Plaid’s access token is stored and later reused by the refresh path.

test_application_sync_and_refresh

This test exercises:

  • application creation with connected_accounts
  • consent synchronization through /open-banking/applications/{application_id}/consents
  • application-wide refresh through /open-banking/applications/{application_id}/refresh

It verifies that the refreshed payload includes a successful result and that StubTransactionsGateway.fetch_transactions receives the stored access token.

test_repatriation_risk_detection

This test verifies the risk endpoint path:

  • a housing application is created
  • the risk endpoint is called for that application
  • home-country transaction counts are computed from the stubbed transaction set
  • the response includes a flagged result, country code, counts, and reasons

test_repatriation_risk_accounts_only_signal

This test confirms that account-currency and account-country signals can drive the repatriation-risk result even when the transaction feed is account-centric.

Plaid Gateway Handling Tests

test_get_transaction_data_handles_invalid_product

backend/tests/infra/external_apis/test_plaid_transactions_handling.py

This test verifies the error mapping for Plaid transaction retrieval when Plaid returns INVALID_PRODUCT. The gateway returns a structured result instead of raising:

  • metadata.status = "not_supported"
  • metadata.error_code = "INVALID_PRODUCT"
  • summary error text includes the transactions-product warning

Plaid CLI and Integration Scripts

main()

backend/test_plaid_balance.py

Fetches account balances from PlaidKycGateway.get_account_balances(access_token) and prints account balance fields.

main()

backend/test_plaid_transactions.py

Fetches transaction data from PlaidKycGateway.get_transaction_data(access_token, lookback_days=90) and prints the summary, sources, metadata, and serialized payload.

get_plaid_client()

backend/tests/usecase/get_plaid_token.py

Builds a sandbox PlaidApi client using PLAID_CLIENT_ID and PLAID_SECRET, then returns it for sandbox token creation and exchange tests.

TestPlaidIntegration

backend/test_plaid_balance_integration.py

Method What it verifies
test_plaid_client_initialization PlaidKycGateway can initialize a Plaid client
test_sandbox_public_token_creation Sandbox public token creation succeeds
test_exchange_public_token Public token exchange returns access token and item ID
test_get_account_balances Balance retrieval returns account-shaped records
test_full_flow End-to-end sandbox flow from token creation to balance retrieval succeeds

TestPlaidTransactionsIntegration

backend/test_plaid_transactions_integration.py

Method What it verifies
setUpClass Environment credentials are available before the integration test runs
setUp The Plaid client is patched with a mock before each test
tearDown The patch is removed after each test
test_get_transaction_data_structure The transaction API response contains the expected summary, sources, and metadata sections

Error Handling

The open banking layer maps provider and consent errors into explicit HTTP responses or recorded refresh outcomes.

Open Banking Error Paths

  • OpenBankingConsentNotFound

Used when a consent reference does not resolve to a stored consent.

  • OpenBankingConsentNotAuthorised

Returned as 403 when the current operator is not allowed to view or manage the consent.

  • OpenBankingConsentInactive

Raised when a refresh is attempted against an inactive consent.

  • OpenBankingConsentMissingToken

Causes auto-refresh to skip the consent.

  • OpenBankingRefreshFailed

Returned as 502 by /open-banking/refresh and /open-banking/applications/{application_id}/refresh.

Provider Error Paths

  • bank_gateway.exchange_public_token(...) exceptions are mapped to 502 Bad Gateway.
  • SaltEdgeAPIError is translated into an HTTP error using the provider status code or a 500 fallback.
  • create_saltedge_lead_session and get_saltedge_connection wrap unexpected exceptions into 500.

Plaid Transaction Retrieval Handling

The Plaid transaction tests show a special case where INVALID_PRODUCT is converted into a structured result with metadata.status = "not_supported" instead of a thrown exception. That keeps consumers from treating unsupported product configuration as a hard failure.

Caching Strategy

backend/src/interface/saltedge_endpoints.py

The Salt Edge endpoint module declares a short-lived shared customer cache:

Item Type Purpose
_customer_cache Dict[str, Any] Shared cache slot for cached customer data
_customer_cache_lock asyncio.Lock Guards concurrent cache access
CUSTOMER_CACHE_TTL_SECONDS int Cache TTL set to 60 seconds

The cache is module-scoped, making it shared across requests handled by the same process. It is paired with an async lock so cache reads and writes can be coordinated safely.

Dependencies

Backend Services and Repositories

  • PlaidBankGateway
  • PlaidKycGateway
  • SaltEdgeClient
  • SaltEdgePartnersClient
  • SQLOpenBankingConsentRepository
  • SQLAlchemyHousingApplicationRepository
  • get_db
  • get_current_user_email

Use Case Dependencies

  • detect_repatriation_risk
  • get_housing_application
  • register_consent
  • refresh_application_consents
  • OpenBankingRefreshEvent
  • attach_plaid_tokens

Data and Normalization Dependencies

  • CanonicalOpenBankingData
  • CanonicalTransaction
  • datetime, timezone, and timedelta for consent expiry and refresh windows
  • hashlib.sha256 for consent reference fingerprinting

Key Classes Reference

Class Responsibility
open_banking_endpoints.py Consent sync, Plaid token exchange, refresh orchestration, and repatriation-risk API routes
saltedge_endpoints.py Salt Edge request and response models plus connect-session request shaping
credit_adapters.py Provider normalization into CanonicalOpenBankingData
credit_canonical_schema.py Canonical provider-agnostic bank data model
open_banking.py Consent extraction, Plaid token attachment, and refresh use cases
account_detection.py Plaid token and account extraction from connected-account records
http_endpoints.py Salt Edge lead session and connection lookup endpoints
test_adapters.py Plaid, Salt Edge, and connected-account adapter verification
test_open_banking_endpoints.py Consent, refresh, and repatriation-risk endpoint coverage
test_plaid_balance_integration.py Plaid sandbox balance flow verification
test_plaid_transactions_integration.py Plaid transaction flow verification
test_plaid_transactions_handling.py Plaid unsupported-product error mapping coverage