Skip to content

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

feat: add nickname (display_name) to bank connections (#218)

Tássio Noronhaf9bd1b3224dc
diff --git a/backend/alembic/versions/051_bank_connection_display_name.py b/backend/alembic/versions/051_bank_connection_display_name.py
new file mode 100644
index 00000000..cb3e5ec7
--- /dev/null
+++ b/backend/alembic/versions/051_bank_connection_display_name.py
@@ -0,0 +1,22 @@
+"""add display_name to bank_connections
+
+Revision ID: 051
+Revises: 050
+Create Date: 2026-05-21
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "051"
+down_revision = "050"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+ op.add_column("bank_connections", sa.Column("display_name", sa.String(255), nullable=True))
+
+
+def downgrade() -> None:
+ op.drop_column("bank_connections", "display_name")
diff --git a/backend/app/models/bank_connection.py b/backend/app/models/bank_connection.py
index 76701670..0382c94d 100644
--- a/backend/app/models/bank_connection.py
+++ b/backend/app/models/bank_connection.py
@@ -21,6 +21,7 @@ class BankConnection(Base):
provider: Mapped[str] = mapped_column(String(50)) # "pluggy", "belvo", etc.
external_id: Mapped[str] = mapped_column(String(255)) # Provider's item ID
institution_name: Mapped[str] = mapped_column(String(255))
+ display_name: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
credentials: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True) # Encrypted tokens
settings: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True, default=dict)
status: Mapped[str] = mapped_column(String(50), default="active") # active, error, expired
diff --git a/backend/app/schemas/bank_connection.py b/backend/app/schemas/bank_connection.py
index 3d9c3bc5..2d83d37b 100644
--- a/backend/app/schemas/bank_connection.py
+++ b/backend/app/schemas/bank_connection.py
@@ -14,6 +14,7 @@ class BankConnectionRead(BankConnectionBase):
id: uuid.UUID
user_id: uuid.UUID
external_id: str
+ display_name: Optional[str] = None
settings: Optional[dict] = None
status: str
last_sync_at: Optional[datetime] = None
@@ -48,5 +49,6 @@ class ReconnectTokenResponse(BaseModel):
class ConnectionSettingsUpdate(BaseModel):
+ display_name: Optional[str] = None
payee_source: Optional[Literal["auto", "merchant", "payment_data", "description", "none"]] = None
import_pending: Optional[bool] = None
diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.py
index 577ca590..bad204c3 100644
--- a/backend/app/services/connection_service.py
+++ b/backend/app/services/connection_service.py
@@ -376,6 +376,11 @@ async def update_connection_settings(
if not connection:
return None
+ if "display_name" in settings_update:
+ raw = settings_update.pop("display_name")
+ trimmed = raw.strip() if isinstance(raw, str) else raw
+ connection.display_name = trimmed or None
+
current = dict(connection.settings or {})
for key, value in settings_update.items():
if value is not None:
diff --git a/frontend/src/components/connection-settings-dialog.tsx b/frontend/src/components/connection-settings-dialog.tsx
index 14c3e19a..c7ef4c0c 100644
--- a/frontend/src/components/connection-settings-dialog.tsx
+++ b/frontend/src/components/connection-settings-dialog.tsx
@@ -11,6 +11,7 @@ import {
DialogFooter,
} from '@/components/ui/dialog'
import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
import { Label } from '@/components/ui/label'
import type { BankConnection, ConnectionSettings } from '@/types'
@@ -30,11 +31,13 @@ export function ConnectionSettingsDialog({
const { t } = useTranslation()
const queryClient = useQueryClient()
+ const [displayName, setDisplayName] = useState('')
const [payeeSource, setPayeeSource] = useState<PayeeSource>('auto')
const [importPending, setImportPending] = useState(true)
useEffect(() => {
if (connection) {
+ setDisplayName(connection.display_name ?? '')
setPayeeSource(connection.settings?.payee_source ?? 'auto')
setImportPending(connection.settings?.import_pending ?? true)
}
@@ -43,6 +46,7 @@ export function ConnectionSettingsDialog({
const mutation = useMutation({
mutationFn: () =>
connections.updateSettings(connection!.id, {
+ display_name: displayName.trim() || null,
payee_source: payeeSource,
import_pending: importPending,
}),
@@ -61,6 +65,17 @@ export function ConnectionSettingsDialog({
<DialogTitle>{t('connections.settings')}</DialogTitle>
</DialogHeader>
<div className="space-y-4">
+ <div className="space-y-2">
+ <Label htmlFor="connection-display-name">{t('connections.displayName')}</Label>
+ <Input
+ id="connection-display-name"
+ value={displayName}
+ onChange={(e) => setDisplayName(e.target.value)}
+ placeholder={connection?.institution_name ?? t('connections.displayNamePlaceholder')}
+ maxLength={255}
+ />
+ <p className="text-[11px] text-muted-foreground">{t('connections.displayNameHint')}</p>
+ </div>
<div className="space-y-2">
<Label>{t('connections.payeeSource')}</Label>
<select
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index bc31a0d0..15c4ea92 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -191,7 +191,10 @@ export const connections = {
const { data } = await api.post(`/connections/${connectionId}/reconnect-token`)
return data.access_token
},
- updateSettings: async (id: string, settings: Partial<ConnectionSettings>): Promise<BankConnection> => {
+ updateSettings: async (
+ id: string,
+ settings: Partial<ConnectionSettings> & { display_name?: string | null },
+ ): Promise<BankConnection> => {
const { data } = await api.patch(`/connections/${id}/settings`, settings)
return data
},
diff --git a/frontend/src/lib/connection-utils.ts b/frontend/src/lib/connection-utils.ts
new file mode 100644
index 00000000..4a96e793
--- /dev/null
+++ b/frontend/src/lib/connection-utils.ts
@@ -0,0 +1,3 @@
+export function getConnectionName(connection: { institution_name: string; display_name?: string | null }): string {
+ return connection.display_name ?? connection.institution_name
+}
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index ebb55a28..7cf4b5cd 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -435,6 +435,9 @@
},
"connections": {
"settings": "Connection settings",
+ "displayName": "Nickname",
+ "displayNamePlaceholder": "e.g. Personal Nubank",
+ "displayNameHint": "Leave empty to show the institution name.",
"payeeSource": "Payee source",
"payeeAuto": "Auto (merchant > payment data)",
"payeeMerchant": "Merchant name only",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index ce1041ca..f921d56f 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -435,6 +435,9 @@
},
"connections": {
"settings": "Configurações da conexão",
+ "displayName": "Apelido",
+ "displayNamePlaceholder": "ex: Nubank Pessoal",
+ "displayNameHint": "Deixe vazio para usar o nome da instituição.",
"payeeSource": "Origem do beneficiário",
"payeeAuto": "Automático (comerciante > dados de pagamento)",
"payeeMerchant": "Apenas nome do comerciante",
diff --git a/frontend/src/pages/accounts.tsx b/frontend/src/pages/accounts.tsx
index 199eb35c..1e4bbe20 100644
--- a/frontend/src/pages/accounts.tsx
+++ b/frontend/src/pages/accounts.tsx
@@ -1,5 +1,6 @@
import { useEffect, useState } from 'react'
import { getAccountName } from '@/lib/account-utils'
+import { getConnectionName } from '@/lib/connection-utils'
import { Link } from 'react-router-dom'
import { useTranslation } from 'react-i18next'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
@@ -305,7 +306,7 @@ export default function AccountsPage() {
</div>
<div>
<div className="flex items-center gap-2">
- <p className="text-sm font-semibold text-foreground">{conn.institution_name}</p>
+ <p className="text-sm font-semibold text-foreground">{getConnectionName(conn)}</p>
<Badge
variant={conn.status === 'active' ? 'default' : 'secondary'}
className="text-[10px] px-1.5 py-0 h-4"
@@ -517,7 +518,7 @@ export default function AccountsPage() {
<DialogTitle>{t('accounts.confirmDisconnectTitle')}</DialogTitle>
</DialogHeader>
<p className="text-sm text-muted-foreground">
- {t('accounts.confirmDisconnectDesc', { institution: disconnectingConnection?.institution_name ?? '' })}
+ {t('accounts.confirmDisconnectDesc', { institution: disconnectingConnection ? getConnectionName(disconnectingConnection) : '' })}
</p>
<DialogFooter>
<Button variant="outline" onClick={() => setDisconnectingConnection(null)}>
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index 6a6e3a66..9e40bc2d 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -64,6 +64,7 @@ export interface BankConnection {
user_id: string
provider: string
institution_name: string
+ display_name: string | null
external_id: string
status: string
settings: ConnectionSettings | null