Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

fix(simplefin): normalize credit-card balance sign so connected cards don't double-count (#351)

Albert Dolkunbb276300f96d
diff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.py
index 87132a9a..face8210 100644
--- a/backend/app/services/account_service.py
+++ b/backend/app/services/account_service.py
@@ -21,6 +21,21 @@ def get_account_name(account: Account) -> str:
return account.display_name or account.name
+def _simplefin_to_internal_balance(provider: str, account_type: str, balance: Decimal) -> Decimal:
+ """Normalize a SimpleFIN balance to Securo's positive-for-debt convention.
+
+ SimpleFIN reports a credit card's balance as negative debt and exposes no
+ account type, so the provider stores it raw and labels every account
+ "checking". Pluggy/Enable report card debt as a positive number, which is
+ the convention every downstream site (serialize_account, _account_balance_at,
+ sync_opening_balance_for_connected_account, ...) assumes. Flip SimpleFIN card
+ balances to match so those sites stay provider-agnostic.
+ """
+ if provider == "simplefin" and account_type == "credit_card":
+ return -balance
+ return balance
+
+
async def get_accounts(session: AsyncSession, workspace_id: uuid.UUID, include_closed: bool = False) -> list[dict]:
# Subquery: compute current_balance per account from transactions in one pass
# Use amount_primary only when tx currency differs from account currency
@@ -288,6 +303,7 @@ async def update_account(
disallowed = set(update_data.keys()) - editable_fields
if disallowed:
raise ValueError("Cannot edit bank-connected accounts")
+ old_type = account.type
new_type = update_data.get("type", account.type)
cc_fields = editable_fields - {"display_name", "type"}
cc_update = {k: v for k, v in update_data.items() if k in cc_fields}
@@ -295,6 +311,22 @@ async def update_account(
raise ValueError("Credit card fields can only be set on credit card accounts")
for key, value in update_data.items():
setattr(account, key, value)
+ # SimpleFIN stores a card's balance with the raw provider sign (negative
+ # for debt) under type="checking". When the user flips the type across
+ # the credit_card boundary, the downstream display sites start (or stop)
+ # applying the positive-for-debt negation, so the stored value must flip
+ # too — otherwise the card double-counts. Mirror the ingestion-time
+ # normalization (_simplefin_to_internal_balance) here so the correction
+ # is immediate, not deferred to the next sync. Load the provider via
+ # session.get (identity-map hit, never a lazy-load that throws).
+ if old_type != new_type and "credit_card" in (old_type, new_type):
+ conn = (
+ await session.get(BankConnection, account.connection_id)
+ if account.connection_id is not None
+ else None
+ )
+ if conn is not None and conn.provider == "simplefin":
+ account.balance = -account.balance
# If the override moves the account away from credit_card, drop any
# stale card metadata so it isn't left half credit-card.
if new_type != "credit_card":
diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.py
index d738f70f..d7a82801 100644
--- a/backend/app/services/connection_service.py
+++ b/backend/app/services/connection_service.py
@@ -28,7 +28,10 @@ from app.providers.base import (
)
from app.services import oauth_state
from app.services import admin_service
-from app.services.account_service import sync_opening_balance_for_connected_account
+from app.services.account_service import (
+ _simplefin_to_internal_balance,
+ sync_opening_balance_for_connected_account,
+)
from app.services.asset_group_service import ensure_group_for_connection
from app.services.credit_card_service import apply_effective_date
from app.services.rule_service import apply_rules_to_transaction
@@ -1166,7 +1169,15 @@ async def sync_connection(
continue
if account:
- account.balance = acc_data.balance
+ # Normalize the provider sign using the account's CURRENT type,
+ # which reflects any user override (sync never rewrites `type`).
+ # SimpleFIN reports card debt as negative under a "checking"
+ # label; once the user overrides the type to credit_card the
+ # downstream sites negate it, so store positive-for-debt to keep
+ # them provider-agnostic and avoid double-counting.
+ account.balance = _simplefin_to_internal_balance(
+ connection.provider, account.type, acc_data.balance
+ )
account.name = acc_data.name
if acc_data.type == "credit_card":
# Preserve existing CC metadata when the provider doesn't
diff --git a/backend/tests/test_account_service.py b/backend/tests/test_account_service.py
index 015f1a17..46589142 100644
--- a/backend/tests/test_account_service.py
+++ b/backend/tests/test_account_service.py
@@ -23,6 +23,7 @@ from app.models.recurring_transaction import RecurringTransaction
from app.models.transaction import Transaction
from app.schemas.account import AccountCreate, AccountUpdate
from app.services.account_service import (
+ _simplefin_to_internal_balance,
create_account,
close_account,
delete_account,
@@ -31,6 +32,7 @@ from app.services.account_service import (
get_account_summary,
get_accounts,
reopen_account,
+ serialize_account,
update_account,
)
@@ -769,3 +771,141 @@ async def test_get_account_balance_history_credit_card_negated(
# CC with connection_id has sign=-1.0: a debit (spending) on CC
# produces negative balance, negated to positive (showing debt increase)
assert history[0]["balance"] == pytest.approx(500.0)
+
+
+# ---------------------------------------------------------------------------
+# SimpleFIN credit-card balance-sign normalization
+# ---------------------------------------------------------------------------
+
+
+async def _make_provider_connection(
+ session: AsyncSession, user_id: uuid.UUID, provider: str,
+) -> "uuid.UUID":
+ from datetime import datetime, timezone
+ from app.models.bank_connection import BankConnection
+ conn = BankConnection(
+ id=uuid.uuid4(), user_id=user_id, provider=provider,
+ external_id=f"ext-{provider}-{uuid.uuid4().hex[:8]}",
+ institution_name=f"{provider} bank", credentials={"token": "fake"},
+ status="active", last_sync_at=datetime.now(timezone.utc),
+ created_at=datetime.now(timezone.utc),
+ )
+ session.add(conn)
+ await session.commit()
+ await session.refresh(conn)
+ return conn.id
+
+
+def test_simplefin_to_internal_balance_flips_card():
+ """SimpleFIN reports card debt as a negative number; normalize to positive."""
+ assert _simplefin_to_internal_balance(
+ "simplefin", "credit_card", Decimal("-500.00")
+ ) == Decimal("500.00")
+
+
+def test_simplefin_to_internal_balance_checking_unchanged():
+ """A SimpleFIN non-card balance is already in the right convention."""
+ assert _simplefin_to_internal_balance(
+ "simplefin", "checking", Decimal("1500.00")
+ ) == Decimal("1500.00")
+
+
+def test_simplefin_to_internal_balance_other_provider_unchanged():
+ """Pluggy/Enable already use positive-for-debt — never flip their cards."""
+ assert _simplefin_to_internal_balance(
+ "pluggy", "credit_card", Decimal("500.00")
+ ) == Decimal("500.00")
+ assert _simplefin_to_internal_balance(
+ "enable_banking", "credit_card", Decimal("500.00")
+ ) == Decimal("500.00")
+
+
+async def test_update_simplefin_account_to_credit_card_flips_balance(
+ session: AsyncSession, test_user, test_workspace,
+):
+ """Decisive case: a SimpleFIN account stores debt as a negative balance under
+ type="checking". When the user overrides the type to credit_card, the stored
+ balance must flip to positive-for-debt so the downstream negation in
+ serialize_account / dashboard yields -500 (owed) instead of +500 — without
+ the flip the card double-counts in net worth (≈2x the debt)."""
+ conn_id = await _make_provider_connection(session, test_user.id, "simplefin")
+ account = await _make_account(
+ session, test_user.id, "SimpleFIN Card", acc_type="checking",
+ balance="-500.00", connection_id=conn_id, external_id="sf-card-1",
+ )
+
+ updated = await update_account(
+ session, account.id, test_workspace.id, AccountUpdate(type="credit_card")
+ )
+ assert updated is not None
+ assert updated.type == "credit_card"
+ # Stored balance flips to positive-for-debt (matches Pluggy/Enable).
+ assert updated.balance == Decimal("500.00")
+ # Resolved/serialized balance is negative = the user owes 500.
+ payload = serialize_account(updated, None, None)
+ assert payload["current_balance"] == pytest.approx(-500.0)
+
+
+async def test_update_simplefin_account_away_from_credit_card_flips_back(
+ session: AsyncSession, test_user, test_workspace,
+):
+ """Reverse direction: moving a SimpleFIN card back to a non-card type must
+ flip the stored balance back to the raw provider sign so it stays
+ consistent with a fresh sync (which writes the raw negative value)."""
+ conn_id = await _make_provider_connection(session, test_user.id, "simplefin")
+ account = await _make_account(
+ session, test_user.id, "SimpleFIN WasCard", acc_type="credit_card",
+ balance="500.00", connection_id=conn_id, external_id="sf-card-2",
+ )
+
+ updated = await update_account(
+ session, account.id, test_workspace.id, AccountUpdate(type="checking")
+ )
+ assert updated is not None
+ assert updated.type == "checking"
+ assert updated.balance == Decimal("-500.00")
+
+
+async def test_update_pluggy_account_to_credit_card_does_not_flip(
+ session: AsyncSession, test_user, test_workspace,
+):
+ """No double-count for non-SimpleFIN providers: a Pluggy account already
+ uses positive-for-debt, so a type edit must NOT touch the stored balance."""
+ conn_id = await _make_provider_connection(session, test_user.id, "pluggy")
+ account = await _make_account(
+ session, test_user.id, "Pluggy Card", acc_type="checking",
+ balance="500.00", connection_id=conn_id, external_id="pl-card-1",
+ )
+
+ updated = await update_account(
+ session, account.id, test_workspace.id, AccountUpdate(type="credit_card")
+ )
+ assert updated is not None
+ assert updated.type == "credit_card"
+ # Untouched — Pluggy was already positive-for-debt.
+ assert updated.balance == Decimal("500.00")
+ payload = serialize_account(updated, None, None)
+ assert payload["current_balance"] == pytest.approx(-500.0)
+
+
+async def test_update_simplefin_type_change_not_crossing_card_keeps_balance(
+ session: AsyncSession, test_user, test_workspace,
+):
+ """A SimpleFIN type edit that doesn't cross the credit_card boundary (e.g.
+ checking → savings) must leave the stored balance alone."""
+ conn_id = await _make_provider_connection(session, test_user.id, "simplefin")
+ account = await _make_account(
+ session, test_user.id, "SimpleFIN Savings", acc_type="checking",
+ balance="1500.00", connection_id=conn_id, external_id="sf-sav-1",
+ )
+
+ updated = await update_account(
+ session, account.id, test_workspace.id, AccountUpdate(type="savings")
+ )
+ assert updated is not None
+ assert updated.type == "savings"
+ assert updated.balance == Decimal("1500.00")
diff --git a/backend/tests/test_connection_service.py b/backend/tests/test_connection_service.py
index 5b646ca3..01830c25 100644
--- a/backend/tests/test_connection_service.py
+++ b/backend/tests/test_connection_service.py
@@ -1979,3 +1979,111 @@ async def test_sync_keeps_genuine_same_day_repeats(
)
)).scalars().all()
assert len(rows) == 2, "identical-description same-day repeats must be kept"
+
+
+# ---------------------------------------------------------------------------
+# SimpleFIN credit-card balance-sign normalization on sync (UPDATE branch)
+# ---------------------------------------------------------------------------
+
+
+async def _make_simplefin_connection(
+ session: AsyncSession, user_id: uuid.UUID, name: str = "SimpleFIN Bank",
+) -> BankConnection:
+ conn = BankConnection(
+ id=uuid.uuid4(), user_id=user_id, provider="simplefin",
+ external_id=f"ext-sf-{uuid.uuid4().hex[:8]}",
+ institution_name=name, credentials={"token": "fake"},
+ status="active", last_sync_at=datetime.now(timezone.utc),
+ created_at=datetime.now(timezone.utc),
+ )
+ session.add(conn)
+ await session.commit()
+ await session.refresh(conn)
+ return conn
+
+
+async def test_sync_normalizes_simplefin_card_balance_to_positive_for_debt(
+ session: AsyncSession, test_user, test_workspace,
+):
+ """SimpleFIN reports a card's debt as a NEGATIVE balance under a "checking"
+ label. Once the user has overridden the account type to credit_card, a
+ re-sync must store the balance positive-for-debt (Pluggy/Enable convention)
+ so the downstream negation yields the right sign instead of double-counting.
+ The UPDATE branch keys the normalization off the account's CURRENT type,
+ which carries the user override (sync never rewrites `type`)."""
+ from app.models.account import Account
+
+ conn = await _make_simplefin_connection(session, test_user.id)
+ # Pre-existing account the user already flipped to credit_card. Stored
+ # balance is already positive-for-debt from the prior edit.
+ account = Account(
+ id=uuid.uuid4(), user_id=test_user.id, connection_id=conn.id,
+ external_id="sf-cc-1", name="SimpleFIN Card", type="credit_card",
+ balance=Decimal("500.00"), currency="USD",
+ )
+ session.add(account)
+ await session.commit()
+
+ mock_provider = AsyncMock()
+ mock_provider.refresh_credentials = AsyncMock(return_value={"token": "t"})
+ # SimpleFIN provider parses every account as type="checking" and reports
+ # the raw negative debt balance.
+ mock_provider.get_accounts = AsyncMock(return_value=[
+ AccountData(
+ external_id="sf-cc-1", name="SimpleFIN Card",
+ type="checking", balance=Decimal("-650.00"), currency="USD",
+ ),
+ ])
+ mock_provider.get_transactions = AsyncMock(return_value=[])
+ mock_provider.get_bills = AsyncMock(return_value=[])
+
+ with patch("app.services.connection_service.get_provider", return_value=mock_provider), \
+ patch("app.services.connection_service.detect_transfer_pairs", new_callable=AsyncMock), \
+ patch("app.services.connection_service.stamp_primary_amount", new_callable=AsyncMock), \
+ patch("app.services.connection_service.apply_rules_to_transaction", new_callable=AsyncMock):
+ await sync_connection(session, conn.id, test_workspace.id, test_user.id)
+
+ await session.refresh(account)
+ # Incoming -650 (raw SimpleFIN) → stored +650 (positive-for-debt). The user
+ # override (type=credit_card) is preserved.
+ assert account.type == "credit_card"
+ assert account.balance == Decimal("650.00")
+
+
+async def test_sync_leaves_simplefin_checking_balance_unchanged(
+ session: AsyncSession, test_user, test_workspace,
+):
+ """A SimpleFIN non-card account (no override) keeps the provider's balance
+ verbatim — the normalization only applies to credit_card."""
+ from app.models.account import Account
+
+ conn = await _make_simplefin_connection(session, test_user.id, "SF Checking")
+ account = Account(
+ id=uuid.uuid4(), user_id=test_user.id, connection_id=conn.id,
+ external_id="sf-chk-1", name="SimpleFIN Checking", type="checking",
+ balance=Decimal("0.00"), currency="USD",
+ )
+ session.add(account)
+ await session.commit()
+
+ mock_provider = AsyncMock()
+ mock_provider.refresh_credentials = AsyncMock(return_value={"token": "t"})
+ mock_provider.get_accounts = AsyncMock(return_value=[
+ AccountData(
+ external_id="sf-chk-1", name="SimpleFIN Checking",
+ type="checking", balance=Decimal("1234.56"), currency="USD",
+ ),
+ ])
+ mock_provider.get_transactions = AsyncMock(return_value=[])
+ mock_provider.get_bills = AsyncMock(return_value=[])
+
+ with patch("app.services.connection_service.get_provider", return_value=mock_provider), \
+ patch("app.services.connection_service.detect_transfer_pairs", new_callable=AsyncMock), \
+ patch("app.services.connection_service.stamp_primary_amount", new_callable=AsyncMock), \
+ patch("app.services.connection_service.apply_rules_to_transaction", new_callable=AsyncMock):
+ await sync_connection(session, conn.id, test_workspace.id, test_user.id)
+
+ await session.refresh(account)
+ assert account.balance == Decimal("1234.56")