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_accountsaccepts:- 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_seenand collapsed into:plaidsaltedgefinverse- a single preserved provider name
mixed
- Bureau-only keys are skipped during ingestion.
- Balance snapshots are converted to USD from:
balances[*].balancebalances.currentbalance
- Transaction values are normalized to:
- 90-day window only
- absolute USD amounts
- lowercased categories
- inferred directions when missing
counterparty_hashorcounterparty
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
providerto"plaid"
- reads top-level
from_saltedge:- reads
payload["data"]or the payload itself - reads
connection.provider_nameorconnection.country_code - groups
accountsunder that key - sets final
providerto"saltedge"
- reads
Open Banking Use Cases
[!NOTE]
from_plaidandfrom_saltedgeboth delegate tofrom_connected_accounts, then overwrite the canonicalproviderfield 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 |
Consent Sync Flow
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_referencecustomer_nameexpires_atmetadataauto_refresh_enabledapplication_id
If it does not exist, it creates a new consent through register_consent with:
scopes=("balances:read", "transactions:read")auto_refresh_enabled=Trueauto_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_atonly when refresh succeeds - records an
OpenBankingRefreshEvent - raises
OpenBankingRefreshFailedwhen 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_idsconnection_nameinstitution_name
This makes Plaid-linked records searchable by token and preserves the connection metadata needed by consent-sync and risk flows.
Consent and Refresh State Management
sync_application_plaid_consentssets the consent up for auto-refresh immediately._ensure_active_consentrequires the consent to be active, authorized, and token-backed before refresh.trigger_refreshstoreslast_refreshed_atonly on success.auto_refresh_due_consentssilently 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 |
Consent Response Model
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]"
}
}
}
Create Consent
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}"
}
}
}
Refresh Consent
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.countrypayload.lookback_dayspayload.min_home_country_transactionspayload.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.emailreturn_to_url=return_to_for_widgetsaltedge_client=saltedge_client
When a connect URL is generated successfully, the backend returns:
connect_urlexpires_atcustomer_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
test_open_banking_consent_flow
This test proves the consent lifecycle path:
- create consent
- exchange public token
- auto refresh due consents
- 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 to502 Bad Gateway.SaltEdgeAPIErroris translated into an HTTP error using the provider status code or a500fallback.create_saltedge_lead_sessionandget_saltedge_connectionwrap unexpected exceptions into500.
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
PlaidBankGatewayPlaidKycGatewaySaltEdgeClientSaltEdgePartnersClientSQLOpenBankingConsentRepositorySQLAlchemyHousingApplicationRepositoryget_dbget_current_user_email
Use Case Dependencies
detect_repatriation_riskget_housing_applicationregister_consentrefresh_application_consentsOpenBankingRefreshEventattach_plaid_tokens
Data and Normalization Dependencies
CanonicalOpenBankingDataCanonicalTransactiondatetime,timezone, andtimedeltafor consent expiry and refresh windowshashlib.sha256for 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 |