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
Consent Registration and Token Attachment
Create Consent
{
"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}"
}
}
}
Create Link Token
{
"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}"
}
}
}
Application Consent Sync and Risk Analysis
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
Consent Lifecycle and Plaid Token Exchange
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. |