Open Banking and Financial Data Domain

Overview

This backend domain manages the consented open-banking lifecycle used by Dwilar/lita-ehousing for housing intake, underwriting, and analytics. It lets the platform register a consent record, attach Plaid tokens, refresh balances and transactions, infer account coverage, detect recurring housing payments, and run repatriation-risk checks against the applicant’s declared home country.

The code centers on a consent-plus-token-plus-refresh model. Consent records are persisted first, then Plaid access is attached later, and refresh operations read the stored token to pull balances and transactions on demand or on schedule. The resulting payloads feed downstream analysis such as coverage inference, housing-payment detection, and risk heuristics.

Architecture Overview

flowchart TB
    subgraph InterfaceLayer [Interface Layer]
        Endpoints[open_banking_endpoints.py]
        Schemas[schemas.py and schemas bank.py]
        Tests[test_open_banking_endpoints.py]
    end

    subgraph UseCaseLayer [Use Case Layer]
        OpenBanking[open_banking.py]
        AccountDetection[account_detection.py]
        HousingDetection[housing_detection.py]
        RepatriationRisk[repatriation_risk.py]
    end

    subgraph DataLayer [Repositories and Gateways]
        ConsentRepo[SQLOpenBankingConsentRepository]
        HousingRepo[SQLAlchemyHousingApplicationRepository]
        BankGateway[PlaidBankGateway]
        TransactionsGateway[PlaidKycGateway]
    end

    subgraph ExternalSystems [External Systems]
        PlaidAPI[Plaid API]
        HousingData[Housing application records]
    end

    Tests -.-> Endpoints
    Endpoints --> OpenBanking
    Endpoints --> AccountDetection
    Endpoints --> HousingDetection
    Endpoints --> RepatriationRisk
    Endpoints --> Schemas

    OpenBanking --> ConsentRepo
    OpenBanking --> BankGateway
    OpenBanking --> TransactionsGateway
    AccountDetection --> BankGateway
    RepatriationRisk --> HousingRepo

    HousingRepo --> HousingData
    BankGateway --> PlaidAPI
    TransactionsGateway --> PlaidAPI

API Integration

{
    "title": "Create Consent",
    "description": "Registers a new open-banking consent and persists the operator access list, scopes, expiry, and metadata",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "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    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2026-04-30T10:15:00Z\",\n    \"allowed_operator_ids\": [\n        \"[email protected]\",\n        \"[email protected]\"\n    ],\n    \"metadata\": {\n        \"source\": \"housing-application-intake\",\n        \"application_id\": 42\n    },\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 720,\n    \"application_id\": 42\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Consent created",
            "body": "{\n    \"consent_reference\": \"consent-123\",\n    \"customer_reference\": \"customer-001\",\n    \"customer_name\": \"Jane Doe\",\n    \"application_id\": 42,\n    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2026-04-30T10:15:00Z\",\n    \"revoked_at\": null,\n    \"allowed_operator_ids\": [\n        \"[email protected]\",\n        \"[email protected]\"\n    ],\n    \"metadata\": {\n        \"source\": \"housing-application-intake\",\n        \"application_id\": 42\n    },\n    \"plaid_item_id\": null,\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 720,\n    \"last_refreshed_at\": null,\n    \"created_at\": \"2026-03-31T10:15:00Z\",\n    \"updated_at\": \"2026-03-31T10:15:00Z\"\n}"
        },
        "409": {
            "description": "Consent reference already exists",
            "body": "{\n    \"detail\": \"Consent reference already exists\"\n}"
        }
    }
}
{
    "title": "Create Link Token",
    "description": "Validates consent access and active state, then requests a Plaid link token for onboarding",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/link-token",
    "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}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Link token created",
            "body": "{\n    \"link_token\": \"link-token\",\n    \"expiration\": \"2099-01-01T00:00:00Z\"\n}"
        },
        "400": {
            "description": "Consent is not active",
            "body": "{\n    \"detail\": \"Consent is not active\"\n}"
        },
        "403": {
            "description": "Operator is not authorised",
            "body": "{\n    \"detail\": \"Operator [email protected] is not authorised for this consent\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        },
        "502": {
            "description": "Plaid failed to create a link token",
            "body": "{\n    \"detail\": \"Failed to create link token\"\n}"
        }
    }
}

Exchange Public Token

{
    "title": "Exchange Public Token",
    "description": "Exchanges the Plaid public token, stores the access token and item id on the consent, and returns the consent state",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "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-abc123\",\n    \"consent_expires_at\": \"2027-03-31T10:15:00Z\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent updated with Plaid token data",
            "body": "{\n    \"consent_reference\": \"consent-123\",\n    \"customer_reference\": \"customer-001\",\n    \"customer_name\": \"Jane Doe\",\n    \"application_id\": 42,\n    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2027-03-31T10:15:00Z\",\n    \"revoked_at\": null,\n    \"allowed_operator_ids\": [\n        \"[email protected]\",\n        \"[email protected]\"\n    ],\n    \"metadata\": {\n        \"source\": \"housing-application-intake\",\n        \"application_id\": 42\n    },\n    \"plaid_item_id\": \"item-123\",\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 720,\n    \"last_refreshed_at\": null,\n    \"created_at\": \"2026-03-31T10:15:00Z\",\n    \"updated_at\": \"2026-03-31T10:15:00Z\"\n}"
        },
        "403": {
            "description": "Operator is not authorised",
            "body": "{\n    \"detail\": \"Operator [email protected] is not authorised for this consent\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        },
        "502": {
            "description": "Plaid exchange failed",
            "body": "{\n    \"detail\": \"Failed to exchange public token\"\n}"
        }
    }
}

Refresh Workflows

Manual Refresh

{
    "title": "Manual Refresh",
    "description": "Refreshes one consent by reference, fetches balances and transactions, records a refresh event, and returns the captured payloads",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "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": "Refresh completed",
            "body": "{\n    \"consent_reference\": \"consent-123\",\n    \"status\": \"succeeded\",\n    \"refreshed_at\": \"2026-03-31T10:20:00Z\",\n    \"balances\": {\n        \"acct\": {\n            \"current\": 100,\n            \"available\": 80,\n            \"limit\": null,\n            \"currency_code\": \"USD\"\n        }\n    },\n    \"transactions\": {\n        \"transactions\": [\n            {\n                \"transaction_id\": \"txn-1\",\n                \"amount\": 42.5,\n                \"date\": \"2026-03-30\",\n                \"account_id\": \"acct-1\"\n            }\n        ],\n        \"accounts\": [\n            {\n                \"account_id\": \"acct-1\",\n                \"current\": 100\n            }\n        ],\n        \"total_transactions\": 1\n    },\n    \"error_message\": null\n}"
        },
        "400": {
            "description": "Consent inactive or token missing",
            "body": "{\n    \"detail\": \"Consent is not active\"\n}"
        },
        "403": {
            "description": "Operator is not authorised",
            "body": "{\n    \"detail\": \"Operator [email protected] is not authorised for this consent\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        },
        "502": {
            "description": "Refresh failed",
            "body": "{\n    \"detail\": \"Refresh failed\"\n}"
        }
    }
}

Automatic Refresh

{
    "title": "Automatic Refresh",
    "description": "Refreshes all active consents that are due and have auto-refresh enabled, then returns the successful refresh summaries",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "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": "Auto refresh completed",
            "body": "[\n    {\n        \"consent_reference\": \"consent-123\",\n        \"status\": \"succeeded\",\n        \"refreshed_at\": \"2026-03-31T10:20:00Z\"\n    }\n]"
        },
        "400": {
            "description": "Missing Plaid access token",
            "body": "{\n    \"detail\": \"Consent consent-123 is missing a Plaid access token\"\n}"
        }
    }
}

Refresh Application Consents

{
    "title": "Refresh Application Consents",
    "description": "Refreshes every consent accessible to the current operator for a housing application and returns one result per consent",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "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": "42",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"lookback_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Refresh completed for one or more consents",
            "body": "[\n    {\n        \"consent_reference\": \"application-42-a1b2c3d4e5f6\",\n        \"status\": \"succeeded\",\n        \"refreshed_at\": \"2026-03-31T10:20: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-03-30\"\n                }\n            ]\n        },\n        \"error_message\": null\n    }\n]"
        },
        "403": {
            "description": "No accessible consents for the operator",
            "body": "{\n    \"detail\": \"Operator [email protected] is not authorised for application 42\"\n}"
        },
        "404": {
            "description": "Application or consent set not found",
            "body": "{\n    \"detail\": \"No open banking consents registered for application 42\"\n}"
        },
        "502": {
            "description": "All refresh attempts failed",
            "body": "{\n    \"detail\": \"Refresh failed\"\n}"
        }
    }
}

List Application Consents

{
    "title": "List Application Consents",
    "description": "Lists the consents attached to a housing application and filters them by current operator access",
    "method": "GET",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/applications/{application_id}/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "application_id",
            "value": "42",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Accessible consents",
            "body": "[\n    {\n        \"consent_reference\": \"application-42-a1b2c3d4e5f6\",\n        \"customer_reference\": \"[email protected]\",\n        \"customer_name\": \"Plaid Applicant\",\n        \"application_id\": 42,\n        \"scopes\": [\n            \"balances:read\",\n            \"transactions:read\"\n        ],\n        \"expires_at\": \"2027-03-31T10:15:00Z\",\n        \"revoked_at\": null,\n        \"allowed_operator_ids\": [\n            \"[email protected]\"\n        ],\n        \"metadata\": {\n            \"application_id\": 42,\n            \"application_email\": \"[email protected]\",\n            \"token_fingerprint\": \"c3f1b0a7d2f4...\"\n        },\n        \"plaid_item_id\": \"item-abc\",\n        \"auto_refresh_enabled\": true,\n        \"auto_refresh_interval_minutes\": 720,\n        \"last_refreshed_at\": \"2026-03-31T10:20:00Z\",\n        \"created_at\": \"2026-03-31T10:15:00Z\",\n        \"updated_at\": \"2026-03-31T10:20:00Z\"\n    }\n]"
        },
        "403": {
            "description": "No consent is accessible to the current operator",
            "body": "{\n    \"detail\": \"You are not authorised to view these consents.\"\n}"
        }
    }
}

Sync Application Consents

{
    "title": "Sync Application Consents",
    "description": "Scans the housing application connected accounts, derives Plaid consent references, persists or updates consent records, and returns accessible consents",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/applications/{application_id}/consents/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "application_id",
            "value": "42",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Accessible consents after sync",
            "body": "[\n    {\n        \"consent_reference\": \"application-42-a1b2c3d4e5f6\",\n        \"customer_reference\": \"[email protected]\",\n        \"customer_name\": \"Plaid Applicant\",\n        \"application_id\": 42,\n        \"scopes\": [\n            \"balances:read\",\n            \"transactions:read\"\n        ],\n        \"expires_at\": \"2027-03-31T10:15:00Z\",\n        \"revoked_at\": null,\n        \"allowed_operator_ids\": [\n            \"[email protected]\"\n        ],\n        \"metadata\": {\n            \"application_id\": 42,\n            \"application_email\": \"[email protected]\",\n            \"token_fingerprint\": \"c3f1b0a7d2f4...\"\n        },\n        \"plaid_item_id\": \"item-abc\",\n        \"auto_refresh_enabled\": true,\n        \"auto_refresh_interval_minutes\": 720,\n        \"last_refreshed_at\": null,\n        \"created_at\": \"2026-03-31T10:15:00Z\",\n        \"updated_at\": \"2026-03-31T10:15:00Z\"\n    }\n]"
        },
        "403": {
            "description": "Current operator cannot view any consent",
            "body": "{\n    \"detail\": \"You are not authorised to view these consents.\"\n}"
        },
        "404": {
            "description": "Housing application not found",
            "body": "{\n    \"detail\": \"Application not found\"\n}"
        }
    }
}

Assess Repatriation Risk

{
    "title": "Assess Repatriation Risk",
    "description": "Refreshes accessible application consents, runs the repatriation-risk heuristic against the applicant home country, and returns the flagged summary",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "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": "42",
            "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": "Risk summary",
            "body": "{\n    \"application_id\": 42,\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        \"home-country transaction activity exceeds threshold\"\n    ],\n    \"refreshed_at\": \"2026-03-31T10:20:00Z\",\n    \"latest_home_country_activity\": \"2026-03-31T00:00:00Z\"\n}"
        },
        "403": {
            "description": "Current operator is not authorised",
            "body": "{\n    \"detail\": \"Operator [email protected] is not authorised for application 42\"\n}"
        },
        "404": {
            "description": "Housing application or consent set not found",
            "body": "{\n    \"detail\": \"Application not found\"\n}"
        },
        "502": {
            "description": "Refresh failed before risk calculation",
            "body": "{\n    \"detail\": \"Refresh failed\"\n}"
        }
    }
}

Component Structure

Interface Layer

[!NOTE] Endpoints that depend on get_current_user_email are identity-gated before the handler logic runs. POST /open-banking/refresh/auto is the only route in this section that does not inject the current user email.

backend/src/interface/open_banking_endpoints.py

This module defines the /open-banking router and the request handlers that connect the user-facing API to the consent, refresh, coverage, and risk use cases. It also exposes the FastAPI dependency factories that build the SQL repositories and Plaid gateways used by the handlers.

Public Functions

Method Description
get_repository Builds SQLOpenBankingConsentRepository from the SQL session.
get_bank_gateway Returns PlaidBankGateway for link-token, token-exchange, and balance calls.
get_housing_repository Returns SQLAlchemyHousingApplicationRepository for housing application lookups.
get_transactions_gateway Returns PlaidKycGateway for transaction fetches in refresh flows.
create_consent Normalizes consent input, appends the current operator to the allowed list, and creates the consent.
create_link_token Validates consent access and active status, then requests a Plaid link token.
exchange_public_token Exchanges the Plaid public token and stores the access token and item id on the consent.
manual_refresh Refreshes one consent by reference and returns balances, transactions, and error context.
auto_refresh Refreshes all due auto-refresh consents and returns a list of successful refresh summaries.
list_application_consents Lists consents for an application that the current operator is allowed to see.
sync_application_consents Pulls Plaid account connections from the housing application and syncs them into consent records.
refresh_application Refreshes every consent accessible to the current operator for the application.
repatriation_risk Refreshes accessible consents and applies the repatriation-risk heuristic.

Internal Helper

Method Description
_serialise_consent Maps OpenBankingConsent fields into ConsentResponse.

Request Models

CreateConsentRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Unique consent reference, 1 to 128 characters.
customer_reference str Customer reference supplied by the caller, 1 to 128 characters.
customer_name Optional[str] Optional customer name, up to 255 characters.
scopes List[str] Consent scopes; defaults to ["balances:read", "transactions:read"].
expires_at datetime Consent expiry timestamp.
allowed_operator_ids List[str] Operator emails or IDs allowed to use the consent.
metadata Optional[Dict[str, Any]] Free-form metadata persisted with the consent.
auto_refresh_enabled bool Enables scheduled refreshes.
auto_refresh_interval_minutes int Refresh interval, constrained to 30 through 43200.
application_id Optional[int] Optional housing application identifier.
LinkTokenRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent reference used to fetch the stored consent before creating a link token.
ExchangePublicTokenRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
public_token str Plaid public token to exchange.
consent_expires_at Optional[datetime] Optional expiry override persisted on the consent.
RefreshRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent reference to refresh.
lookback_days int Transaction lookback window, default 90 and constrained to 1 through 365.
ApplicationRefreshRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
lookback_days int Transaction lookback window for application-wide refreshes, default 90 and constrained to 1 through 365.
AutoRefreshRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
lookback_days int Transaction lookback window for scheduled refreshes, default 90 and constrained to 1 through 365.
RepatriationRiskRequest

backend/src/interface/open_banking_endpoints.py

Property Type Description
lookback_days int Refresh lookback window, default 90 and constrained to 1 through 365.
min_home_country_transactions int Minimum home-country transaction count needed to flag risk.
min_home_country_share float Minimum home-country share needed to flag risk.

Response Models

ConsentResponse

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent reference persisted in the repository.
customer_reference str Customer reference saved with the consent.
customer_name Optional[str] Stored customer name.
application_id Optional[int] Housing application id linked to the consent.
scopes List[str] Consent scopes.
expires_at datetime Consent expiry timestamp.
revoked_at Optional[datetime] Revocation timestamp, if any.
allowed_operator_ids List[str] Operators allowed to access the consent.
metadata Dict[str, Any] Persisted metadata payload.
plaid_item_id Optional[str] Plaid item id stored after token exchange.
auto_refresh_enabled bool Auto-refresh flag.
auto_refresh_interval_minutes int Auto-refresh interval in minutes.
last_refreshed_at Optional[datetime] Timestamp of the last successful refresh.
created_at Optional[datetime] Creation timestamp.
updated_at Optional[datetime] Update timestamp.
RefreshResponse

[!NOTE] ConsentResponse exposes plaid_item_id but does not expose the Plaid access token. The access token stays in the consent record for refresh flows.

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent reference that was refreshed.
status str Refresh result status.
refreshed_at datetime Timestamp for the refresh attempt.
balances Dict[str, Any] Raw balances payload returned by the bank gateway.
transactions Dict[str, Any] Raw transactions payload returned by the transactions gateway.
error_message Optional[str] Error message for failed refreshes.
AutoRefreshResponse

backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent reference refreshed by the scheduler.
status str Refresh result status.
refreshed_at datetime Timestamp of the auto refresh.
RepatriationRiskResponse

backend/src/interface/open_banking_endpoints.py

Property Type Description
application_id int Housing application id.
home_country_code str Normalized home-country code from the application.
lookback_days int Lookback window used for the evaluation.
flagged bool Indicates whether the risk heuristic flagged the applicant.
home_country_transactions int Number of home-country transactions found.
total_transactions int Total transactions examined.
home_country_share float Share of home-country transactions in the examined set.
reasons List[str] Human-readable reasons returned by the heuristic.
refreshed_at datetime Timestamp of the most recent successful refresh used for the score.
latest_home_country_activity Optional[datetime] Most recent observed home-country activity.

Use Case Layer

backend/src/usecase/open_banking.py

This module implements the consent-plus-token-plus-refresh model that the interface layer exposes. It persists consent records, attaches Plaid tokens, orchestrates manual and scheduled refreshes, and records refresh events in the consent repository.

Public Functions

Method Description
register_consent Creates an OpenBankingConsent with deduplicated scopes and operators, then stores it.
attach_plaid_tokens Loads a consent by reference, writes Plaid token fields, and saves the record.
sync_application_plaid_consents Extracts Plaid connections from a housing application and creates or updates consent records for them.
refresh_application_consents Refreshes every consent accessible to an operator for a specific housing application.
auto_refresh_due_consents Refreshes active consents that are due and enabled for auto-refresh.
trigger_refresh Refreshes one consent, records the refresh event, and returns raw balances and transactions.

Protocol

TransactionsGateway

backend/src/usecase/open_banking.py

Method Description
fetch_transactions Fetches a transaction payload for an access token and date range.

Internal Helpers

Method Description
_ensure_active_consent Verifies the consent exists, is active, is operator-authorized, and has a token.
_extract_plaid_connections Pulls Plaid access tokens, item ids, connection names, institution names, and account ids from connected-account payloads.
_normalise_string Trims string values and returns None for empty values.

Workflow Notes

  • register_consent uses list(dict.fromkeys(...)) for both scopes and allowed operators, so duplicate values are removed before persistence.
  • attach_plaid_tokens preserves the previous plaid_item_id when the new item_id is empty.
  • sync_application_plaid_consents hashes each Plaid access token with SHA-256 and uses the first 12 hex characters as the consent-reference suffix.
  • refresh_application_consents returns partial success results when some consents refresh and others fail; it raises OpenBankingRefreshFailed only when no refresh succeeds.
  • auto_refresh_due_consents records failed refresh events and continues processing remaining consents.

Account Coverage Inference

backend/src/usecase/account_detection.py

infer_account_coverage compares the account ids reported in connected_accounts with the account ids returned by plaid_gateway.get_account_balances(token). It returns a coverage result with overall status, totals, per-connection details, and error messages when gateway calls fail.

Public Functions

Method Description
infer_account_coverage Compares submitted account ids with Plaid-detected account ids and calculates coverage status and ratio.

Coverage Output Shape

The function is paired with the response models in backend/src/interface/schemas.py.

AccountCoverageDetail

backend/src/interface/schemas.py

Property Type Description
connection_name Optional[str] Connection label provided by the applicant or sync payload.
institution_name Optional[str] Institution label associated with the connection.
reported_accounts int Number of account ids the application reported for the connection.
detected_accounts int Number of accounts returned by the Plaid gateway.
missing_accounts int Number of detected accounts that were not reported.
status Literal["complete", "incomplete", "error"] Per-connection coverage state.
AccountCoverageResponse

backend/src/interface/schemas.py

Property Type Description
application_id int Housing application id.
status Literal["complete", "incomplete", "unknown"] Overall coverage state.
reported_accounts int Total reported accounts across all connections.
detected_accounts int Total accounts returned by the gateway.
missing_accounts int Total missing accounts across all connections.
coverage_ratio Optional[float] Reported-to-detected ratio when detected accounts exist.
details List[AccountCoverageDetail] Per-connection breakdown.
errors List[str] Gateway error messages.

Recurring Housing Payment Detection

backend/src/usecase/housing_detection.py

This module mutates transaction records in place. When it finds a qualifying recurring payment series or a direct keyword match, it adds housing categories and writes a housing_detection metadata block for downstream consumers.

Dataclass

_SeriesCandidate

backend/src/usecase/housing_detection.py

Property Type Description
key str Descriptor key for the candidate series.
average_amount float Average recurring amount.
coefficient_of_variation float Stability metric for the amount series.
coverage float Month coverage ratio across the series span.
median_gap_days Optional[float] Median number of days between recurring months.
transactions List[Dict[str, Any]] Transactions that belong to the candidate series.
month_keys Sequence[str] Ordered month keys that were observed.
primary_currency Optional[str] Dominant currency code for the series.

Public Function

Method Description
annotate_housing_transactions Detects recurring housing payments and tags matching transactions in place.

Internal Helpers

Method Description
_collect_series_groups Groups positive-amount transactions by normalized descriptor key and month.
_derive_descriptor_key Builds the descriptor key from description, connection name, account name, or provider.
_normalise_descriptor_value Strips accents, punctuation, and separators from a descriptor string.
_apply_housing_categories Ensures housing and rent are present in the transaction categories.
_set_detection_metadata Writes the housing_detection metadata payload onto the transaction.
_normalise_categories Returns string categories from a list input.
_normalise_currency_code Uppercases a currency code string and returns None for empty values.
_matched_housing_terms Finds housing-related keywords in categories and transaction text fields.
_parse_date Parses ISO date strings or date objects into a date.
_safe_number Converts a value to float when possible.
_average Computes the arithmetic mean of a sequence.
_coefficient_of_variation Computes standard deviation divided by average.
_series_coverage Computes the observed-to-span month coverage ratio.
_inclusive_month_span Computes the inclusive number of months between two dates.
_median_month_gap Computes the median day gap between observed months.
_primary_currency Returns the dominant currency code and its share.
_expand_month_range Expands a month-key span into every month in between.
_parse_month_key Parses YYYY-MM strings into first-of-month dates.

Detection Rules

  • Only positive-amount transactions are considered for recurring-series grouping.
  • A recurring series must meet the minimum month count, average amount, coefficient-of-variation, coverage, gap, and currency-share thresholds visible in the code.
  • Direct keyword matches do not require a recurring series but still require a minimum absolute amount.
  • The function uses strategy values of keyword_match or recurring_series in the metadata it writes.

Repatriation Risk Workflow

backend/src/usecase/repatriation_risk.py

This module is the heuristic backend consumed by the /open-banking/applications/{application_id}/repatriation-risk endpoint. The endpoint refreshes transaction payloads first, then passes those payloads and the applicant’s home country into detect_repatriation_risk to build the response summary.

Feature Flows

sequenceDiagram
    participant Client
    participant API as open_banking_endpoints
    participant Repo as SQLOpenBankingConsentRepository
    participant Bank as PlaidBankGateway
    participant UseCase as open_banking

    Client->>API: POST /open-banking/consents
    API->>UseCase: register_consent
    UseCase->>Repo: create
    Repo-->>UseCase: OpenBankingConsent
    UseCase-->>API: OpenBankingConsent
    API-->>Client: ConsentResponse

    Client->>API: POST /open-banking/link-token
    API->>Repo: get_by_reference
    API->>Bank: create_link_token
    Bank-->>API: link token payload
    API-->>Client: LinkTokenResponse

    Client->>API: POST /open-banking/consents/{consent_reference}/exchange
    API->>Repo: get_by_reference
    API->>Bank: exchange_public_token
    Bank-->>API: access token payload
    API->>UseCase: attach_plaid_tokens
    UseCase->>Repo: save
    Repo-->>UseCase: OpenBankingConsent
    UseCase-->>API: OpenBankingConsent
    API-->>Client: ConsentResponse

Manual and Automatic Refresh

sequenceDiagram
    participant Client
    participant API as open_banking_endpoints
    participant Repo as SQLOpenBankingConsentRepository
    participant Bank as PlaidBankGateway
    participant Tx as PlaidKycGateway
    participant UseCase as open_banking

    Client->>API: POST /open-banking/refresh
    API->>UseCase: trigger_refresh
    UseCase->>Repo: get_by_reference
    UseCase->>Bank: get_balances
    UseCase->>Tx: fetch_transactions
    UseCase->>Repo: save
    UseCase->>Repo: record_refresh
    UseCase-->>API: refresh result
    API-->>Client: RefreshResponse

    Scheduler->>API: POST /open-banking/refresh/auto
    API->>UseCase: auto_refresh_due_consents
    loop Due consent
        UseCase->>Repo: list_active_consents
        UseCase->>Bank: get_balances
        UseCase->>Tx: fetch_transactions
        UseCase->>Repo: save
        UseCase->>Repo: record_refresh
    end
    UseCase-->>API: auto refresh summaries
    API-->>Scheduler: AutoRefreshResponse list

Application Sync and Repatriation Risk

sequenceDiagram
    participant Client
    participant API as open_banking_endpoints
    participant HousingRepo as SQLAlchemyHousingApplicationRepository
    participant ConsentRepo as SQLOpenBankingConsentRepository
    participant Bank as PlaidBankGateway
    participant Tx as PlaidKycGateway
    participant UseCase as open_banking

    Client->>API: POST /open-banking/applications/{application_id}/consents/sync
    API->>HousingRepo: get_housing_application
    API->>UseCase: sync_application_plaid_consents
    UseCase->>ConsentRepo: create or save
    UseCase->>ConsentRepo: get_by_reference
    UseCase->>ConsentRepo: save
    UseCase-->>API: synced consents
    API-->>Client: ConsentResponse list

    Client->>API: POST /open-banking/applications/{application_id}/repatriation-risk
    API->>HousingRepo: get_housing_application
    API->>UseCase: refresh_application_consents
    UseCase->>ConsentRepo: list_by_application_id
    UseCase->>Bank: get_balances
    UseCase->>Tx: fetch_transactions
    UseCase->>ConsentRepo: record_refresh
    UseCase-->>API: refreshed payloads
    API->>API: detect_repatriation_risk
    API-->>Client: RepatriationRiskResponse

Recurring Housing Payment Detection

flowchart TD
    Input[Transaction list] --> Group[Collect series groups]
    Group --> Filter[Apply recurring series rules]
    Group --> Match[Find direct keyword matches]
    Filter --> Best[Select best recurring series]
    Match --> Keyword[Prepare keyword match metadata]
    Best --> Annotate[Apply housing categories]
    Keyword --> Annotate
    Annotate --> Metadata[Write housing detection metadata]

State Management

State Area Values Seen in Code Where It Is Set Where It Is Consumed
Consent access active, inactive, authorised, not authorised, has token, missing token Consent checks in open_banking.py and endpoint guards Link-token creation, token exchange, refresh flows, consent listing
Refresh lifecycle manual, auto, succeeded, failed trigger_refresh, auto_refresh_due_consents, refresh_application_consents, and record_refresh API responses and refresh event persistence
Coverage status complete, incomplete, unknown, error infer_account_coverage AccountCoverageResponse
Housing detection strategy keyword_match, recurring_series annotate_housing_transactions Transaction metadata enrichment
Risk outcome flagged true or false detect_repatriation_risk via the endpoint RepatriationRiskResponse

Transaction and Balance Access Patterns

Access Pattern Method Payload Shape Purpose
Single-consent refresh BankGateway.get_balances + TransactionsGateway.fetch_transactions Raw dicts keyed by account and transaction collections Captures current balances and recent transactions for one consent
Scheduled refresh auto_refresh_due_consents Same raw dict shapes, one consent at a time Refreshes due consents without an operator call
Application-wide refresh refresh_application_consents List of per-consent refresh dictionaries Refreshes all operator-accessible consents for one housing application
Coverage inference plaid_gateway.get_account_balances List of account records Compares reported account ids with Plaid-detected accounts
Balance model shape BankAccountSchema, BalanceResponse, AccountBalancesResponse Account-level balance objects Normalizes balance responses used by downstream consumers

Balance Schema Models

backend/src/interface/schemas/bank.py

BankAccountSchema
Property Type Description
account_id str Account identifier.
name str Account display name.
official_name Optional[str] Official account name.
type str Account type.
subtype Optional[str] Account subtype.
balance_available Optional[float] Available balance.
balance_current Optional[float] Current balance.
balance_limit Optional[float] Credit limit or balance limit.
currency_code str Currency code, defaults to USD.
mask Optional[str] Account mask.
BalanceResponse
Property Type Description
account_id str Account identifier.
available Optional[float] Available balance.
current Optional[float] Current balance.
limit Optional[float] Balance or credit limit.
currency_code str Currency code, defaults to USD.
name Optional[str] Account display name.
official_name Optional[str] Official account name.
mask Optional[str] Account mask.
AccountBalancesResponse
Property Type Description
accounts List[BankAccountSchema] Account list returned by the balance endpoint shape.

Error Handling

Condition Code Path HTTP Status Outcome
Duplicate consent reference create_consent catches IntegrityError 409 Returns a conflict error with Consent reference already exists.
Consent not found create_link_token, exchange_public_token, manual_refresh, refresh_application, repatriation_risk 404 Returns a not-found error.
Operator not authorised Consent checks in endpoint guards 403 Returns an authorization error.
Consent inactive create_link_token, manual_refresh through _ensure_active_consent 400 Returns an inactive-consent error.
Missing Plaid token _ensure_active_consent, auto_refresh_due_consents 400 Returns a missing-token error.
Plaid link-token failure create_link_token 502 Returns a gateway error when Plaid does not return a link token.
Plaid token exchange failure exchange_public_token 502 Returns a gateway error when exchange fails.
Refresh failure trigger_refresh, refresh_application_consents, manual_refresh, repatriation_risk 502 Returns a refresh-failed error.
No accessible application consents list_application_consents, sync_application_consents 403 Returns a permission error.
No consents registered for application refresh_application_consents 404 Returns a not-found error.

Dependencies

[!IMPORTANT] refresh_application_consents preserves successful refreshes even when some consents fail. It only raises OpenBankingRefreshFailed when every attempted refresh fails.

  • fastapi.APIRouter, Depends, HTTPException, and status for routing and request handling.
  • pydantic.BaseModel and Field for request and response models.
  • sqlalchemy.exc.IntegrityError and sqlalchemy.orm.Session for consent persistence.
  • SQLOpenBankingConsentRepository and SQLAlchemyHousingApplicationRepository for database access.
  • PlaidBankGateway for link-token creation, public-token exchange, and balance retrieval.
  • PlaidKycGateway for transaction retrieval in refresh flows.
  • get_current_user_email for operator attribution and access control.
  • get_housing_application for housing-application lookup before sync and risk evaluation.
  • detect_repatriation_risk for the home-country spending heuristic.
  • hashlib, datetime, timezone, and timedelta for consent fingerprinting and refresh window calculation.

Testing Considerations

Test Support Classes

backend/tests/interface/test_open_banking_endpoints.py

StubBankGateway

Property Type Description
link_token_requests list[str] Captures each user id passed to create_link_token.
last_public_token `str None`
Method Description
__init__ Initializes request tracking fields.
create_link_token Returns a fixed Plaid-style link-token payload.
exchange_public_token Returns a fixed access-token and item-id payload.
get_accounts Returns an empty list in the tests.
get_balances Returns a simple balances dictionary used by refresh assertions.
create_processor_token Returns a fixed processor token string.

StubTransactionsGateway

Property Type Description
calls list[tuple[str, str, str]] Captures each transaction fetch call as access token and date range.
transactions list[dict[str, object]] Transaction payload returned by the stub.
accounts list[dict[str, object]] Account payload returned by the stub.
Method Description
__init__ Seeds the stub with optional transactions and accounts.
fetch_transactions Returns the stored transaction and account payloads plus a total count.

Covered Scenarios

Test Coverage
test_open_banking_consent_flow Consent creation, allowed-operator injection, link-token exchange, auto refresh, and manual refresh.
test_application_sync_and_refresh Application creation, consent sync, application-level refresh, and transaction gateway invocation.
test_repatriation_risk_detection Repatriation-risk response for transaction payloads with home-country activity.
test_repatriation_risk_accounts_only_signal Repatriation-risk behavior when home-country signal comes from account country metadata.
test_infer_account_coverage_detects_missing_accounts Account coverage inference, missing-account counting, and coverage-ratio calculation.

Key Classes Reference

Class Responsibility
open_banking_endpoints.py Exposes consent registration, Plaid token attachment, refresh, sync, and risk endpoints.
open_banking.py Implements consent persistence, Plaid token attachment, refresh orchestration, and refresh event recording.
account_detection.py Infers account coverage by comparing reported account ids with Plaid-detected accounts.
housing_detection.py Detects recurring housing payments and annotates matching transactions in place.
repatriation_risk.py Provides the heuristic used to flag home-country repatriation risk.
schemas.py Defines account-coverage response models.
schemas/bank.py Defines account and balance response models.
test_open_banking_endpoints.py Exercises consent, refresh, coverage, and repatriation-risk flows with stub gateways.