Bank Sync

BETA - Connect external bank accounts for automatic transaction imports. Must be enabled by a Nextcloud administrator.

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 three providers, each covering different regions:

ProviderRegionConnection Method
GoCardlessUK and European banksOAuth authorization flow
Enable BankingEuropean banksYour own Enable Banking application, then authorization at your bank
SimpleFINUS / Canadian banksToken-based authentication

Tip: If your bank isn't listed under one provider, try another. 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.

For European banks, Enable Banking can be used instead, and unlike GoCardless it can be used for your own accounts privately. Other aggregators (Tink, TrueLayer, etc.) require a business contract, 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.

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 Enable Banking or 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 Enable Banking#

Enable Banking connects European banks through an application you register with Enable Banking yourself. Budget signs its requests with that application's keys, so you set it up once and can then connect as many banks as you like.

Step 1: Create an Enable Banking Application#

  1. In the Enable Banking control panel, register an application and create its keys (see enablebanking.com/docs). You need the application ID and the private key (a PEM file)
  2. Register Budget's redirect URL for the application. Budget shows it in the connection form under Redirect URL to register in Enable Banking, with a Copy button. It is your Nextcloud address followed by /apps/budget/bank-sync/callback, for example https://cloud.example.com/apps/budget/bank-sync/callback

Note: Copy the redirect URL from the form rather than typing it. On a server whose addresses include index.php, the URL includes it too, and the one registered with Enable Banking must match exactly.

Step 2: Enter Your Keys#

  1. Navigate to your accounts list and select Add Bank Connection
  2. Choose Enable Banking (Europe) as the provider
  3. Enter a Connection Name (a label for your reference, e.g. "Main Bank")
  4. Enter your Application ID, and paste your Private Key (PEM) or load it from the file
  5. Click Next

Your application ID and private key are stored encrypted and belong to you rather than to one connection, so you only enter them once. The next time you add a connection the form says Your Enable Banking keys are stored. Click Replace keys to enter new ones. The keys are left out of backups, so after restoring a backup into another account you enter them again.

Step 3: Select Your Bank#

  1. Pick your bank's country from the dropdown (it starts on Germany)
  2. Use the search bar to find your bank and click it
  3. Click Connect

Step 4: Authorize at Your Bank#

  1. A new tab opens at your bank. Log in and confirm the access, for example in your bank's app
  2. Your bank sends you back to Budget, and the tab says Bank connected
  3. Return to the Budget window and click I've Completed Authorization
  4. On success, your bank accounts are listed for mapping

The bank's consent lasts up to 180 days, or less if your bank allows less. When it runs out, the connection shows Expired with a Re-authorize button. Your keys are still stored, so re-authorizing goes straight to choosing your bank and authorizing again, and your account mappings are kept.

Banks only allow a few reads of an account each day. To stay within that, a normal sync only reads the accounts you have mapped, while Refresh in the account mappings reads every account to update the list. The first sync of an account imports the last 90 days.

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.

The setup token must come from SimpleFIN itself. Budget only accepts a token that points at an https address on simplefin.org (such as bridge.simplefin.org), and refuses anything else as an invalid setup token, so the access the token grants to your accounts is only ever sent to SimpleFIN.

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. Each connection is synced as a job of its own, spread across the background job (cron) runs, so one slow bank does not hold up everyone else's.

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
  • Your Enable Banking application ID and private key are encrypted at rest and never included in a backup
  • 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
  • For GoCardless and Enable Banking, the access you granted is also ended at the provider
  • 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

A factory reset, Clear sample data and deleting the Nextcloud user also end every GoCardless and Enable Banking connection at the provider, once your data has been removed. If the provider can't be reached at that moment, the reset still goes ahead and the problem is written to the Nextcloud log.

Troubleshooting#

Common issues and solutions:

IssueSolution
Bank Sync option not visibleAsk your Nextcloud admin to enable it in Settings > Admin Settings
OAuth redirect failsEnsure your Nextcloud instance URL is publicly accessible and HTTPS is configured correctly
GoCardless bank not foundTry searching by the bank's official name rather than a nickname. Not all institutions are supported
Enable Banking tab says Bank connection failedCheck that the redirect URL registered for your Enable Banking application is exactly the one Budget shows in the connection form, then try again
"The bank only allows a few refreshes per day"Your bank limits how often an account can be read. Try again later, and avoid pressing Refresh or Sync repeatedly
SimpleFIN token rejectedTokens are single-use. Generate a new token from simplefin.org if the previous one was already claimed. A token that does not point at simplefin.org over https is refused as an invalid setup token
Sync shows no new transactionsCheck that the account is mapped. Unmapped accounts are skipped during sync. For SimpleFIN credit cards, ensure you are running v2.27.1+ which includes the required date range parameter
Transactions appear duplicatedThis should not happen due to import ID tracking. File a bug report with details
Connection expiredGoCardless connections expire after ~90 days, and Enable Banking ones after up to 180 days. Click Re-authorize on the expired connection and complete the wizard
Connection stuck on "Awaiting Authorization"Complete the bank authorization step. Open the connection and follow the wizard from where you left off
Daily sync not runningEnsure Nextcloud background jobs (cron) are configured and running on your server

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

  • 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