Live Bank Connection — A Guide from Scratch

If you have an agreement with your bank, you can receive account transactions directly from the bank without downloading a statement file. The system administrator sets up the connection once under Settings › Company Information › Bank connections; transactions then arrive at the chosen interval (or with Fetch now) and go through the same matching as imported files. Even if the same transaction comes both from the connection and from a file, it is never written twice.

1. What it does and does not do

It only reads from the bank: account list, balance and transactions. It sends no payment orders and moves no money.
Incoming transactions land in the Bank Transactions window and are matched there; you (or the automatic receipt setting) still write the receipt.
The older bank service that reads e-mail notifications (mail/PDF statements) is a separate path and keeps working.

2. Connection methods

Method	What it needs	Status
Turkish open banking (ÖHVPS · account information service)	A company cannot connect to the bank directly: it needs a licensed YÖS (payment service provider) as intermediary, a consent approved in the bank app and an access token.	Written to the standard; becomes active with a YÖS agreement.
The corporate account-transaction web service of Turkish banks (Garanti BBVA, İş Bankası, Yapı Kredi, Akbank, Ziraat, Halkbank, VakıfBank, QNB, DenizBank, Kuveyt Türk)	An ERP integration agreement with the branch; web service user name/password, customer number, IP permission for the server (for Garanti BBVA a client id/secret and a consent number created in internet banking).	Listed in the catalogue; the driver is completed when the bank sends its service document. Until then the status is "Bank agreement required".
Indonesia Bank Indonesia SNAP (BCA, Bank Mandiri, BNI, BRI)	Registration on the bank's developer portal and a corporate agreement; X-CLIENT-KEY, client secret, the public key of an RSA key pair we generate given to the bank, X-PARTNER-ID, CHANNEL-ID, account numbers.	Signatures and endpoints written to the standard; the first test with a real bank comes after the agreement.
Simulation (test bank)	User name `demo`, any password. It never reaches a real bank; it always produces the same sample transactions for each day.	For rehearsing the setup and for training.

3. The credential encryption key

The password, client secret and private key given by the bank are written to the database encrypted (AES-256-GCM). The encryption key is not in the database but in the server's environment: HNR_BANKA_KIMLIK_ANAHTARI. In this installation the key is kept with Windows' per-user protection (java\gpt\tls\banka-kimlik.dpapi.xml) and the Node launcher supplies it at start. Without the key the screen warns "The credential encryption key is not defined"; credentials cannot be saved and the bank cannot be reached. If the key changes, saved credentials cannot be decrypted — the screen says "The encryption key has changed" and the credentials are entered again.

4. Setting up a connection — four steps

Bank and connection method: Settings › Company Information › Bank connections › New connection. Choose the bank/method from the list; below it appear the source document and the Information to request from the bank list — apply to the bank with this list.
Credentials and connection settings: give the connection a name, fill in the fields the bank gave you and press Save and continue. Secret fields (password, secret, private key) are never shown again after saving; the box reads "Saved — type a new value to change it". If you leave it empty, the old value is kept.
Connection test: Test connection signs in at the bank and brings the account list and balances. If it succeeds the status becomes "Connection is working"; otherwise the reason is shown (section 7).
Account mapping and fetching: next to each bank account choose the cash/bank account in HNR (an unmapped account is not fetched; one HNR account maps to only one bank account). Fetch interval 5-60 minutes, days to go back on the first fetch 0-90. If Automatic fetch on is not ticked, transactions arrive only with Fetch now. Save and close.

First set up a rehearsal connection with the Simulation driver (user name demo): you see the four steps, fetching and matching without waiting for a real bank. By writing giris|amount|description|counterparty|tax id lines in the "Sample transactions" box you can try matching against your own open invoices. Delete the connection after the rehearsal.

5. Fetching, the duplicate guard and matching

Each fetch asks for the transactions from one day before the last successful fetch up to today (on the first fetch, as many days as "days to go back"; at most 31 days at once). The overlapping day is deliberate: the same transaction is recognised by bank reference, date, amount and direction, counted as a duplicate and not written.
New transactions land in the Bank Transactions window with the "Live" source and are matched at once (exact / suggestion / unmatched). The automatic receipt does not run during live fetching: you write the receipts of exact matches from the window.
If you later load the same day's statement as an MT940 file too, rows with the same bank reference show as duplicates.

6. Automatic fetching and notifications

Automatic fetching is off by default on the server; the system administrator turns it on with BANKA_CANLI_GOREV=1. When on, each connection is synchronised at its own interval. After an error the waiting time doubles at every attempt (at most 6 hours); on permanent errors such as rejected credentials, a missing agreement or incomplete settings, automatic retries stop and wait for the administrator. When new transactions arrive, the administrator who set up the connection gets a "… new bank transactions received, … transactions awaiting matching." message in Messages; on the third consecutive error a warning comes once. A failing connection is also listed in the Queued section of the Pulse screen.

7. Statuses and error reasons

On screen	Meaning and what to do
Configured, awaiting test	Saved; press Test connection.
Connection is working	The last test or fetch succeeded.
Bank agreement required	There is no service document for this bank yet, or the bank has not opened the service. Apply to the bank with the list in section 2.
Credentials rejected	The password/secret/consent has expired or is wrong. Enter the new value and test again. Automatic retries stop on this error.
The bank could not be reached · The bank service is temporarily not responding	A temporary problem on the network or at the bank; automatic fetching retries at growing intervals.
Connection settings incomplete	A required field is empty, the address is not https or there is no account mapping. Complete the form.

8. The Live tab and the synchronisation log

The Bank Transactions › Live tab shows each connection's status, last synchronisation, last successful fetch, number of mapped accounts and fetch interval; the red number on the tab name is the number of failing connections. Here the administrator can press Fetch now and open the Sync log: each row holds the time, the reason (manual / scheduler / when the window opened / connection test), the status, the received, new, duplicate, exact and suggestion counts and the error message if any. Credentials are never written to the log.

9. Permissions and security

Creating, changing, deleting and testing connections, Fetch now and the log: system administrator only. Other users with the Bank permission only see the status on the Live tab.
Credentials are never read back through the API; the screen shows only an "encrypted, saved" badge. If the encrypted value is copied to another connection or company, it cannot be decrypted.
Bank addresses can only be https://; only read calls are made to the bank; every action is written to the audit trail (who, when, which IP).

10. On the phone

In the Bank Transactions window the third tab is Live: connection cards, status, last synchronisation and a large Fetch now button.
On the phone the connection form in Settings opens step by step: Bank → Credentials → Test → Accounts.

11. Frequently asked questions

Question	Answer
Can I enter my own internet banking password?	No. The connection works with the web service user the bank issues separately for ERP integration, or with an open banking consent. Never give your internet banking password to any system.
My bank is in the list but the status is "Bank agreement required".	The bank's service document has not been built into the driver yet. Apply to your branch with the "Information to request from the bank" list in section 2; when the document arrives the driver is completed and the connection test opens.
Why do transactions not arrive by themselves?	Either Automatic fetch on is not ticked for the connection, or the automatic fetching task is off on the server (not `BANKA_CANLI_GOREV=1`). The top of the Live tab says which applies; meanwhile Fetch now can be used.
What happens to fetched transactions if I delete the connection?	They stay. Only the connection and its saved credentials are deleted; transactions, matches and written receipts remain.

Related guides: Bank Transactions · Finance · Settings · Mobile.