Bank Sync

Overview#

Bank Sync allows you to connect your real bank accounts to the Budget app and automatically import transactions. Instead of manually uploading CSV or OFX files, transactions flow in directly from your bank.

Note: This is a beta feature and may have rough edges. If you encounter issues, please report them on the GitHub issue tracker.

Enabling Bank Sync (Admin)#

Bank Sync must be enabled by a Nextcloud administrator before any user can access it:

1. Log in as a Nextcloud admin
2. Open the Budget app and go to Settings
3. Scroll down to the Admin Settings section
4. Toggle Enable Bank Sync to on

Warning: This is an experimental feature. The warning banner displayed in Admin Settings explains that bank connectivity relies on third-party services and may experience interruptions or breaking changes.

Once enabled, all users on the instance will see the Bank Sync option in their account management interface.

Supported Providers#

Bank Sync supports two providers, each covering different regions:

Tip: If your bank isn't listed under one provider, try the other. Coverage varies and is continuously expanding.

⚠️ Important — GoCardless no longer accepts new sign-ups. As of late 2025, GoCardless (formerly Nordigen) has closed its free Bank Account Data API to new customers; it is moving to enterprise-only access. Existing GoCardless connections continue to work, but if you do not already have a GoCardless Bank Account Data account you will not be able to obtain the Secret ID / Secret Key needed below.

There is currently no free open-banking provider that onboards individual self-hosters for EU/UK banks — the remaining aggregators (Enable Banking, Tink, TrueLayer, etc.) require a business contract and KYB verification, and SimpleFIN only covers North American banks. If automatic sync isn't available to you, use manual import instead: most banks let you export CSV / OFX / QIF, and the importer supports per-account routing and saved templates so repeat imports are quick. If you know of a provider that lets individuals access their own EU bank data without a business contract, please open an issue — we'd like to add one.

Connecting via GoCardless#

GoCardless uses a 3-step wizard to guide you through connecting a UK or European bank account.

Note: This requires an existing GoCardless Bank Account Data account. New sign-ups are no longer accepted (see the warning under Supported Providers above). If you don't already have one, use manual import instead.

Step 1: Enter API Credentials#

1. Navigate to your accounts list and select Add Bank Connection
2. Choose GoCardless as the provider
3. Enter a Connection Name (a label for your reference, e.g. "Main Bank")
4. Enter your Secret ID and Secret Key from your GoCardless account
5. Click Next — the app validates your credentials before proceeding

Step 2: Select Your Bank#

1. Your country is auto-detected from your Nextcloud locale, but you can change it from the dropdown
2. Browse the grid of available banks (each shown with its logo) or use the search bar to find yours
3. Click your bank to select it
4. Click Connect to begin the authorization process

Step 3: Authorize at Your Bank#

1. A new browser window opens, directing you to your bank's authorization page
2. Log in to your bank and grant read access to your accounts and transactions
3. Once you have completed the authorization at your bank, return to the Budget app and click I've Completed Authorization
4. The app checks the authorization status with GoCardless
5. On success, your discovered bank accounts are displayed for mapping

Note: GoCardless connections typically remain valid for 90 days under PSD2 regulations before requiring re-authorization. See Re-Authorization below.

Pending Authorization Status#

If you close the wizard before completing Step 3, the connection is saved with an Awaiting Authorization status. You can return later to finish the process. Connections in this state are skipped by the daily background sync — only fully authorized connections are synced automatically.

Re-Authorization (GoCardless)#

GoCardless connections expire after approximately 90 days due to PSD2 regulations. When a connection expires:

1. The connection shows an Expired status with a Re-authorize button
2. Click Re-authorize to open the connection wizard
3. Walk through the same 3-step flow: enter your API credentials (Step 1), select your bank (Step 2), and authorize at your bank (Step 3)
4. Once re-authorized, the connection resumes normal operation

There is no need to disconnect and reconnect — re-authorization preserves your existing account mappings and transaction history.

Connecting via SimpleFIN#

To connect a US bank account:

1. Navigate to your accounts list and select Add Bank Connection
2. Choose SimpleFIN as the provider
3. Obtain a SimpleFIN token from simplefin.org (requires a SimpleFIN Bridge subscription)
4. Paste your token into the token field
5. Click Connect
6. The app claims the token and fetches your available accounts

Note: SimpleFIN tokens are single-use for claiming. Once claimed by the Budget app, the same token cannot be used elsewhere.

Each sync fetches the last 90 days of transactions. This includes credit card accounts, which require a date range parameter to return transaction data.

Account Mapping#

After connecting a bank, you must map external accounts to local Budget accounts:

1. A list of discovered external bank accounts is displayed
2. For each external account, select an existing local Budget account from the dropdown, or create a new one
3. Only mapped accounts will have their transactions synced
4. Unmapped accounts are ignored during sync

Tip: You can change account mappings at any time. Transactions already imported will remain in their original local account.

Refresh Accounts#

A Refresh button appears in the account mappings section for each connection. Clicking it re-fetches the account list from your bank provider, which is useful when:

• You have opened a new bank account since you first connected
• An account was not discovered during the initial connection

Refreshing does not trigger a full transaction sync — it only updates the list of available external accounts for mapping.

Syncing Transactions#

Transactions are synced in three ways:

• Manual sync - Click the Sync button on a connection to immediately fetch new transactions for that connection
• Sync All - When you have two or more active connections, a Sync All button appears. It syncs all connections sequentially, showing progress as it goes (e.g. "Syncing 1 of 3..."). When complete, it displays aggregated results across all connections.
• Automatic sync - A background job runs daily to sync all mapped accounts automatically. Connections with a pending or expired authorization status are skipped.

Duplicate detection prevents the same transaction from being imported twice. Each synced transaction carries a unique import ID from the bank, which is checked against existing transactions before importing.

Note: The first sync may take longer as it imports your recent transaction history. Subsequent syncs only fetch new transactions.

Security#

Bank Sync takes security seriously:

• All connection credentials (tokens, access keys) are encrypted at rest using Nextcloud's built-in encryption service
• Credentials are never exposed in API responses - the app only confirms whether a connection exists
• Communication with bank providers uses encrypted HTTPS connections
• You can revoke access at any time by disconnecting (see below)

Tip: Review your connected banks periodically and disconnect any you no longer use.

Disconnecting#

To remove a bank connection:

1. Go to the account management page
2. Find the bank connection you want to remove
3. Click Disconnect
4. Confirm the action

When disconnecting:

• The external link and stored credentials are permanently deleted
• All previously imported transactions remain in your local accounts
• You can reconnect the same bank later, but it will be treated as a new connection

Troubleshooting#

Common issues and solutions:

Note: If you encounter persistent issues, check your Nextcloud log file for error messages related to Bank Sync and include them when reporting bugs.

Related Features#

• Accounts - Managing your local budget accounts
• Transactions - Working with imported transactions
• Import - Manual file-based import as an alternative
• Settings - Admin toggle and general configuration