Repository navigation
Bank sync
This page is copied from
docs/bank-sync.mdwhenever it changes. To correct it, open a pull request on that file.
CloudBank can pull new transactions straight from your bank and import them — de-duplicated and run through your assignment rules — through three providers. All use a bring-your-own-credentials model: you supply the provider credentials, CloudBank stores them server-side (never returned to the browser) and signs the provider requests. CloudBank never sees your bank username or password.
Bank sync lives in Settings → Bank sync. Each provider is configured per wallet. Once an account is linked, its register shows when it last synced, a Sync button, and how many of its imported rows still need a look. The public demo does not reach any of them; it has a pretend bank instead (see demo.md).
| Provider | Coverage | You bring | Cost to you |
|---|---|---|---|
| SimpleFIN | Worldwide (via SimpleFIN Bridge) | A SimpleFIN setup token | ~$15/year SimpleFIN Bridge subscription |
| Enable Banking | EU/EEA + UK (PSD2 open banking) | Your own application (app id + RSA key) | Free sandbox; production is your own agreement with Enable Banking |
| Pluggy (experimental) | Brazil and Latin America | A Pluggy client id + secret, and the item id of each bank linked in Meu Pluggy | Free for personal use through Meu Pluggy |
The import itself reuses CloudBank's normal pipeline: transactions are de-duplicated (by the provider's transaction id, or a stable hash when none is given) and passed through your assignment rules, exactly like a file import. Signed amounts follow CloudBank's convention (negative = money out).
- Create a SimpleFIN Bridge account at https://beta-bridge.simplefin.org/ and connect your bank there. SimpleFIN Bridge is the paid piece (~$15/year).
- Generate a setup token in SimpleFIN Bridge.
- In CloudBank: Settings → Bank sync → SimpleFIN → Connect a bank, give it a name and paste the setup token. CloudBank claims the token once for a secret access URL (stored server-side) — a token can only be claimed once.
- Under the new connection, link each provider account to a CloudBank account, then click Sync now. Re-syncing only imports new transactions.
Enable Banking is PSD2 open banking for the EEA + UK. You register your own application; CloudBank uses it on your behalf.
-
Sign in at https://enablebanking.com/sign-in/ and open the Control Panel → Applications → Add a new application.
-
Choose an environment:
- Sandbox — free, activated instantly, connects to mock/test banks (and some banks' sandboxes). Best for trying the whole flow.
- Production — real banks. A new production app starts inactive. For personal, non-commercial use you can activate it with "Activate by linking accounts" in the Control Panel: link your own bank account(s) and authorize them — no commercial contract required (see Enable Banking's Linked accounts docs; commercial / at-scale use needs an agreement, and their Terms of Service set the exact limits). The API flow is the same as sandbox, so nothing changes in CloudBank — just set the environment to production.
Important — a personal (restricted) app can only read linked accounts. When you activate "by linking accounts", the app stays restricted, and per Enable Banking "you can only fetch data from accounts linked to the application." The accounts you link are exactly the ones CloudBank can see, so keep them linked. You still connect them through CloudBank's Connect a bank (the normal PSD2 authorization, step 3) — that is the session CloudBank actually uses. Common gotchas:
- "No accounts found" / "Imported 0" after connecting almost always means no accounts are linked to the app. Open the application in the Control Panel, click Link accounts, authorize your account(s), then Reconnect the bank in CloudBank.
- "Could not complete the connection" (a 502 on return): make sure your CloudBank is up to date — a card / non-IBAN linked account (e.g. a CPAN) previously broke the connect step. The callback page now shows the real Enable Banking error; a stale link from an earlier activation can also block a fresh authorization, so unlinking and re-linking the account can help.
- Link the same bank profile your accounts live under — e.g. Intesa Sanpaolo Private Banking vs Intesa Sanpaolo — otherwise the session comes back with no accounts.
-
Set the application's redirect URL to your CloudBank instance's callback, exactly:
https://YOUR-CLOUDBANK-HOST/bank-sync/callbackCloudBank shows this exact URL in the credentials dialog — copy it from there.
-
Provide the RSA key pair. The simplest option is "Generate in the browser and export private key" (no tooling needed) — it downloads a private key and registers the certificate for you. Or generate one yourself:
openssl genrsa -out private.key 4096 openssl req -new -x509 -days 365 -key private.key -out public.crt \ -subj "/C=IT/ST=State/L=City/O=CloudBank/CN=YOUR-CLOUDBANK-HOST"Upload
public.crt; keepprivate.key. -
After registering, copy the Application ID.
Keep the private key secret — treat it like a password. If it is ever exposed, rotate it in the Control Panel.
Settings → Bank sync → Enable Banking (EU) → Configure, then paste:
- Application ID
-
RSA private key (PEM — PKCS#1 from
openssl genrsa, or PKCS#8 from the browser export; both are accepted) - Environment (sandbox or production)
To later change only the environment or app id, open Edit credentials and leave the private-key field blank to keep the stored key.
- Connect a bank, choose the country and bank, give it a name, and continue. You are redirected to the bank to authorize access.
- On return, CloudBank exchanges the authorization for a session and creates the connection. Link each account to a CloudBank account and Sync now.
If the connection is created but shows "No accounts found" (and Sync now imports 0), the bank returned an empty account list. On a restricted production app that means the accounts are not linked to your Enable Banking application — see the note in step 1: Link accounts in the Control Panel, then Reconnect here.
A bank consent is time-limited (Enable Banking grants roughly 90 days). When it expires, sync reports it and you reconnect the bank.
Pluggy is open finance for Brazil and Latin America. It works differently from the other two: banks are linked outside CloudBank, in Pluggy's own consumer app, so there is no consent redirect to configure here.
- Sign up at Meu Pluggy and connect your banks there. Each connected institution becomes an item.
- Create an account on the Pluggy Dashboard, create an application, and note its Client ID and Client Secret.
- In the Dashboard, open your application and copy the item id of each connection you want CloudBank to read.
- In CloudBank: Settings → Bank sync → Pluggy → Configure, paste the client id and secret. They are verified against Pluggy before being saved, so a typo is caught immediately rather than at the first scheduled sync.
- Connect an item, paste the item id, then link each account to a CloudBank account and Sync now.
Pluggy's commercial plans are priced for companies, but Meu Pluggy is free for personal use and Pluggy states that access continues after the 15-day Dashboard trial at no cost.
One caveat worth knowing before you invest time: other projects integrating Pluggy report that linking a new bank in Meu Pluggy may require an active trial, even though existing connections keep syncing. If you plan to add more banks later, confirm this on your own account rather than assuming.
The integration follows Pluggy's published API, but unlike the other two providers it has not been exercised against a live Latin American bank by the maintainers.
If you use it, please report back. An issue saying what worked is as useful as one saying what did not, and these are the things most worth a second pair of eyes:
- Do credit-card amounts land the right way round — spending as an expense, a bill payment as money in?
- Do pending movements settle correctly once the bank books them, without leaving a duplicate behind?
- Does a second sync of an overlapping period import nothing new, as it should?
- Does connecting a new bank in Meu Pluggy still work for you after the 15-day Dashboard trial?
Two provider quirks it already accounts for, since both would be silent if wrong:
- Credit cards invert the sign. Pluggy reports a positive amount on a card as a new charge — money you owe — so CloudBank flips it to a negative (expense) entry. On a bank account the direction comes from the transaction type instead.
- Pending movements are not marked cleared, because a pending row can still change amount or disappear before it settles.
Bank-sync secrets — the SimpleFIN access URL, the Enable Banking application private key and the Pluggy client secret — are stored server-side in the SQLite database and are never returned to the browser.
Set CB_SECRET_KEY to encrypt them (and CloudBank's other reversible secrets
— AI API keys, 2FA secrets, the web-push signing key) at rest with AES-256-GCM.
It is optional and backward compatible: without it, secrets are stored in plaintext
(existing behaviour); set it and each secret is encrypted on its next write. Keep
the key stable — losing it makes the encrypted secrets unrecoverable.
Whether or not encryption is enabled, protect the database itself as you would the rest of your financial data:
- keep the
/datavolume on trusted, access-controlled storage, - store backups securely, and
- serve CloudBank over HTTPS (see reverse-proxy.md).
Connections are refreshed automatically in the background, so you normally don't need to click Sync now. Each connection has an Automatic sync toggle (on by default) and a schedule: the time of day and the days of the week it runs — pick, say, 03:00 on weekdays. Times are shown and saved in your local timezone (converted to UTC under the hood). A connection syncs at most once per scheduled day: PSD2 caps unattended access to a few calls per account per day, so there is no benefit to more. Turn the toggle off to sync a connection only on demand.
The background job wakes every CB_BANK_SYNC_INTERVAL (default 1h; set it to
0/off to disable background sync entirely) and runs each connection that is
due for its scheduled slot. Account balances shown in the bank sync settings are
cached and refreshed at most every 12h, so opening the page repeatedly does not
spend the daily budget. An Enable Banking connection whose consent has expired is
skipped until you reconnect it.
Each connection keeps a short sync history: expand it in the bank sync settings to see the recent runs — when each ran, whether it was manual or automatic, and, per linked account, how it went (fetched / imported / reconciled, or the error). It's the quickest way to answer "why didn't my last sync import anything?" without reading server logs.
Bank rows aren't just dumped into the register — they go through the same import pipeline as a file import, with extra reconciliation:
- No duplicates of what you already have. A bank row that matches an existing manual or scheduled transaction (same amount, within a date window) is merged into that transaction rather than added again — it inherits the bank reference (so the next sync recognises it), its date is corrected to the bank's, and its status is upgraded. Your meaningful memo from a schedule is replaced by the bank's description on a reconciled row; category, tags and payee are kept.
- Right status. A booked bank transaction is imported as reconciled, a pending one as cleared; when a pending row later books, it is settled up to reconciled instead of duplicated.
- A default payment mode by account type: an IBAN account's rows default to direct debit, a card account's to credit card (your import rules still win when they match).
- Assignment rules run on every imported row, so categories/payees you've set up are applied automatically.
Because imported rows arrive reconciled but the bank supplies no CloudBank category, the Review page helps you finish the job. It has no place in the sidebar: the register of a linked account shows "N to review" when there is something to look at, and the button opens Review on that account alone ("Show all accounts" widens it again).
- Needs a category lists imported transactions that still have none — pick one inline, or let Propose categories fill payee and category in from your history and the AI, then confirm them together (Review).
- Possible duplicates finds pairs that look like the same movement (same account and amount, close dates) that reconciliation didn't catch — for example a manual entry whose date was well off. The two are compared field by field — payee, category, the whole memo, info, payment, status, tags — with what they share dimmed, so the differences stand out. For each pair you can merge (keep one, carrying the bank reference over), edit or delete a row, or mark it "not a duplicate" so it is never shown again.
- Not confirmed by the bank lists transactions read from bank mails that the bank has not booked five days on, to merge into the bank's row or delete.
- The Enable Banking account list is captured when you connect; if the bank later exposes a new account, reconnect to pick it up.
- Balances shown for Enable Banking accounts are best-effort (cached, refreshed at most every 12h) and may be omitted if the bank does not return one.
- Some banks expose only booked transactions over PSD2. Intesa Sanpaolo is confirmed to be one of them (see below): pending/non-booked charges are not available until they book, so the register can trail the bank's own app by a day or two.
Many banks' PSD2 (open banking) interfaces expose only booked transactions — pending ones are frequently unavailable — so it's normal for an auto-sync to import only booked rows (as reconciled) even though you can see pending charges in the bank's own app. CloudBank's default transactions call already asks for everything the bank will return, so whatever pending the ASPSP exposes is imported (as cleared).
If you expect pending rows and none arrive, you can find out why without
guessing. Set CB_BANK_SYNC_DEBUG_PENDING=1, restart, run one Sync now, then
look at the server log (CB_LOG_LEVEL=info is enough):
-
bank sync: fetched account … booked=… pending=… other=… pendingDroppedNoDate=…— the breakdown of the normal call.pending=0means the bank returns no pending in the default call;pendingDroppedNoDate>0means pending arrive but lack a date and are skipped. -
bank sync: PDNG probe … count=…orbank sync: PDNG probe failed … error=…— the result of an explicittransaction_status=PDNGrequest (only made while the flag is on), including the exact HTTP status and body on failure.
Turn the flag back off afterwards: the probe makes an extra provider call per account, which eats into the small PSD2 daily budget.
Confirmed for Intesa Sanpaolo (Sept 2026): the default call returned only
booked rows (pending=0) and the explicit probe returned PDNG probe … count=0
(a successful call with nothing to give) — so Intesa does not expose pending
transactions over PSD2 at all. There is no sync-side workaround; the charges
import as reconciled once the bank books them. Until then, CloudBank's balance
is higher than the bank's available balance by the sum of those pending charges.
Start here
Using CloudBank
- Using CloudBank, page by page
- Importing transactions
- Automatic bank sync
- Bank mails
- Notifications
- The AI, and what it sees
- CloudBank in Home Assistant
- Adding from your phone
- Ask your data
- Schedules in your phone's calendar
Running CloudBank
Extending CloudBank
Project