View source for AqBanking

'''[http://aquamaniac.de Aquamaniac]s Banking''' ([https://translate.google.com/translate?hl=de&sl=auto&tl=en&u=https%3A%2F%2Fwww.aquamaniac.de%2Frdm%2F translation]) is the successor of ''openhbci'', a module which supported the open [http://www.hbci-zka.de/english/ german online banking standard] '''''h'''ome '''b'''anking '''c'''ommon '''i'''nterface'', which since 2003 is called ''FinTS''. In between also
* ''Electronic Banking Internet Communication Standard'' [https://en.wikipedia.org/wiki/Electronic_Banking_Internet_Communication_Standard EBICS], used in CH, DE, FR and
* ''[[Setting_up_OFXDirectConnect_in_GnuCash_2|OFX Direct Connect]]'' are supported.

Deutsche Version: [[De/HBCI]] (German version of this page)

== Compatibility ==
[[GnuCash]] compiles with all available versions of AqBanking. There used to be some version restrictions, but since gnucash 2.2.7 all versions are supported, as noted on [[AqBanking3_Porting]].

== HBCI/FinTS Security Type ==
HBCI/AqBanking can use the following security Media
;Single step authentication:
:;HBCI 1: self-generated asymetric keypair with 
::* public part given to the bank
::* private part stored on your floppy or USB stick
::supported on all OS, but many banks dropped single step authentication.
;Two step authentication:
:;HBCI 2, FinTS 3: PIN/TAN pairs
::You have always to log in with your fix Personal Identification number (PIN).
::Then each transaction needs authentication with an own Transaction Authentification Number (TAN).
::The way, the TAN is generated varies by method:
::;PIN/TAN (classic): from simple ''paper list'': you can enter any ''unused'' TAN: supported on all OS
::;iTAN: from indexed ''paper list'': the bank challenges TAN[i]: supported on all OS
::;mTAN: TAN per SMS on your ''mobile'': supported on all OS
::;chipTAN: [same as below?]
::;opticalTAN, aka Flicker code: GC does not generate the flickering image, but you can manually enter the displayed number in your ''TAN generator''
;[more details required, not up to date]:
:;Chipcards: Supported on Linux, but '''Chipcards are not supported on Windows'''. (They are supported on Windows by the latest libchipcard version 4 with gwenhywfar version 3, but gnucash does not compile with those versions yet.)
::;Warning!:[https://www.redteam-pentesting.de/en/publications/MitM-chipTAN-comfort/-man-in-the-middle-attacks-against-the-chiptan-comfort-online-banking-system Man-in-the-Middle Attacks against the chipTAN comfort Online Banking System]

== Setting up a HBCI PIN/TAN account ==
=== By Commandline ===
This instructions will explain how to set up a HBCI account with PIN/TAN authentification. The access data is from a test account that can be used by any gnucash developer; the instructions are also in src/import-export/hbci/HACKING-HBCITEST.txt. 

Instructions are copied from http://linuxwiki.de/AqBanking/aqhbci-tool where they are in German. We have also a [[De/HBCI|german page (deutsche Seite)]] and the content might be partial different.

We assume you have aqbanking and gnucash installed, and aqbanking's program <tt>aqhbci-tool</tt> is in your PATH.

Attention developers: If you call these programs and/or gnucash from the MSYS command line, you must change your HOME env variable to be the value of the USERPROFILE variable. This is because MSYS sets a new HOME that isn't know to any other (normal) windows program that is started outside MSYS. In particular, if you start gnucash outside of msys, it will look for the configuration and also for aqbanking's configuration in $USERPROFILE, but in msys, it will look in HOME. So you always have to gnucash as <tt>HOME="$USERPROFILE" gnucash</tt>

==== Create/register a new security medium in AqBanking ====
 aqhbci-tool addmedium -t pintan

==== Find out the index number of the newly created security medium ====
 aqhbci-tool listmedia
The output will be something like 
 Medium 0: "PINTAN-20070216-214030" (pintan)
and the important part is the first number, here: 0.

==== Create a HBCI user ====
 aqhbci-tool adduser -m N -s SERVERURL -b BANKCODE -u USERID
where <tt>N</tt> is the medium number (0), SERVERURL is the full URL of the server application, BANKCODE is the bank code, and USERID is the identification string of the user that is allowed to access this account. For the test account, we have the following:
 aqhbci-tool adduser -m 0 -s www.hora-obscura.de/pintan/PinTanServlet -b 80007777 -u gnucash
There is an optional argument of the CUSTOMERID, but this concerns you only if your bank explicitly said you have to use some extra customer id that is different from the user id.

==== Connect HBCI user to account ====

To assign an account to a hbci user you might have problems using the AQBanking Assistant from GnuCash. For manual change you have to change the variable in the File

 /home/computer/.aqbanking/settings/accounts/uid%234a%234a00000001.conf

 int  user="XXX"

In XXX the UserID has to be inserted.

==== Retrieve a system identification number ====
This system identification is necessary for the HBCI protocol to identify you and your software; if this step is forgotten or fails, nothing else will work.
 aqhbci-tool getsysid -b BANKCODE
This command will ask you several questions. First it retrieves the server certificate and asks you whether you accept it. Then it asks whether you want to accept the certificate only this session or forever. Eventually, you have to enter the PIN number (password) of your online banking account. (For the gnucash test account, this is 12345.) The full output looks e.g. like this:

 aqhbci-tool getsysid -b 80007777
 ===== Certificate Received =====
 The following certificate has been received:
 Name        : www.hora-obscura.de
 Organisation: www.hora-obscura.de
 Department  : GT90185227
 Country     : DE
 City        : unknown
 State       : unknown
 Valid after : 2007/02/15 14:28:06
 Valid until : 2008/05/17 14:28:06
 Hash        : 69:CF:A0:D9:EA:1F:4B:DA:5F:FA:7D:EE:75:87:C9:FF
 Status      : Certificate is valid
 Do you wish to accept this certificate?
 (1) Yes  (2) No
 Please enter your choice: 1
 ===== Certificate =====
 Do you want to accept this certificate permanently?
 (1) Permanently  (2) This session only  (3) Abort
 Please enter your choice: 1
 ===== Enter Password =====
 Please enter the password for 
 PINTAN-20070216-215639
 Input: *****

Any additional (error) messages can be ignored for now; just continue to work.

==== List the resulting accounts ====
 aqhbci-tool listaccounts
The bank server should have sent a list of accounts in the last step already. If this is the case, you can view the list of accessible accounts now. The output for the gnucash test should look like this:
 Account 0: Bank: 80007777 Account Number: 2501111538
 Account 1: Bank: 80007777 Account Number: 2501111539
 Account 2: Bank: 80007777 Account Number: 2501111540
If you've come this far, then congratulations: Your online access works!

==== Match the HBCI accounts in gnucash ====
In order to access the accounts from gnucash, you need to match a HBCI account to one of your gnucash accounts each. The next time you start gnucash, press "Tools -> Online Banking Setup" to use the online banking setup wizard. Press "Next" there. Ignore the text that says you should start the external program "AqBanking setup wizard", because you've already set up aqbanking by the command line. Because of this, press "Next" again. 

You will now arrive at the "Match HBCI accounts with GnuCash accounts" window. You should see the three accounts mentioned above in the left column of the wizard window.

Click on an account name on the left (the account defined in the AqBanking setup wizard configuration), and select the GnuCash account that should be associated with it.

Click the Forward button.

In the next window, click the Apply button.

== Using HBCI accounts in GnuCash ==
You're now ready to use the HBCI accounts from the respective GnuCash register windows. See [[Setting_up_OFXDirectConnect_in_GnuCash_2#Using_Gnucash_to_download_transactions_directly_to_an_account_register]] on how to do this.

== Using the test account ==
As mentioned above, the gnucash developers can use a test account to test some of the aqbanking/HBCI features. Here's a step-by-step instruction of what you can do:
* Setup the accounts as described above.
* In gnucash, match one of your gnucash accounts with the first test account (bank code 80007777, account number 2501111538); press "Next" and "Finish" in the wizard.
=== Testing "Get Balance" === 
* Open the gnucash register of the account that you've matched with hbci above
* Press "Actions -> Online actions -> Get balance" 
* When asked for the password/PIN, enter <tt>12345</tt>
* If things run successfully, you are being told a balance and asked whether you want to reconcile your account. The balance value changes by the other test users anyway, so you don't have to care about the actual balance.

=== Testing "Get Transactions" ===
* Open the gnucash register of the account that you've matched with hbci above
* Press "Actions -> Online actions -> Get transactions" 
* When asked for the date, enter "From: 2007-02-15", but the To-date can be left at "now".
* When asked for the password/PIN, enter <tt>12345</tt>
* If things run successfully, you see the "transaction matcher window" with the downloaded transactions. You can select "New" for all of them. At subsequent downloads, those transactions that are downloaded again should automatically be marked as "Reconcile" instead.

=== Testing "Issue Transaction" ===
* Open the gnucash register of the account that you've matched with hbci above
* Press "Actions -> Online actions -> Issue transaction" 
* Enter the following values: 
** Recipient account number <tt>2501111539</tt> , recipient bank code <tt>80007777</tt>
** All other fields can contain whatever values you like; if they are not allowed to be empty, you will be told so when clicking "Ok".
* Click "Ok". Now select a destination account in gnucash, then click "Ok".
* When asked for the password/PIN, enter <tt>12345</tt>
* When asked for a '''TAN''' and specifically for TAN number 1 (or another number of 2 through 9), enter <tt>11111111</tt> (or <tt>22222222</tt>...), i.e. exactly eight times the number in the question.
** It seems like the test account does not give out any TANs anymore. The server asks for TAN number 'no_more_free_user_tans'.
* If things run successfully, you only see the transaction in the gnucash register now. If the transmission didn't work, the transaction in the register should have been deleted again. If things worked ok, your next statement download should download that transaction that you've just sent to the bank, and the next balance download should have changed by that amount as well.

== Debugging ==
If there are any problems during the HBCI or OFX connection, here are further options for debugging:
* Keep in mind that there are many many many different bank servers on this world, and every one of them might behave slightly differently. Hence, if you report a bug, please also state which '''bank server''' you are using (IP address and bank name).
* If there is a '''crash''', it would be good to provide a stack trace of the crash, see [[Stack Trace]] and [[Windows#Debugging with gdb]].
* To see much more '''log messages''' of aqbanking, you can set several environment variables either before starting gnucash or in the shell script gnucash or gnucash.bat. For example, in a Unix shell you would type
 export GWEN_LOGLEVEL=info
 export AQBANKING_LOGLEVEL=info
 export AQOFXCONNECT_LOGLEVEL=info
 export AQHBCI_LOGLEVEL=info
:Other possible values to all of these variables are 
:*<tt>debug</tt> (more verbose) or 
:*<tt>warn</tt> (less verbose) or 
:*<tt>error</tt> (even less verbose, default value).

However, these log messages are all sent to ''stdout'' or ''stderr'', which on [[Windows]] by default isn't available. To make these available on Windows, you need to change the exetype of ''gnucash-bin.exe'' from "Windows" to "Console", see [[Windows#Console output and exetype]].

=== Log Location ===
From the german mailing list in 2011:
AqBanking stores log files for '''HBCI''' under Linux in
:<code>~/.aqbanking/backends/aqhbci/data/banks/<country code>/<Bank ID>/logs/*</code>, with
:''.aqbanking'' a hidden directory,
:''<country code>'' your ISO country code,
:''<Bank ID>'' the name or the routing number of your bank.

To enable logging of the '''OFX''' communication to <code>/tmp/ofx.log</code> (with warnings about revealing passwords), see [[Setting up OFXDirectConnect in GnuCash 2#Enabling the OFX Log]].

=== Known Issues ===

* from 2.1.1 until before 2.2.5: http://bugzilla.gnome.org/show_bug.cgi?id=439654 AqBanking on Windows cannot download balance/transactions via HBCI - there is a "Unable to send (network error)" instead. The bugreport contains a patch for the gwenhywfar DLL which must be recompiled. If someone confirms that this patch fixes the problem, the patch will be included in a new gwenhywfar release, but currently the gwenhywfar maintainers are waiting for such feedback.

== References ==

* AqBanking:
** [https://www.aqbanking.de Homepage] mostly in german, includes mailing list and bug tracker.
** [https://sourceforge.net/projects/aqbanking/ @ Sourceforge] outdated
* HBCI, now official called FinTS - Financial Transaction Services:
** [http://www.hbci-zka.de/english/ FinTS - Financial Transaction Services] (former HBCI) specifications, including error codes ...
** [http://www.hbci-zka.de/institute/institut_auswahl.htm Search FinTS capable institutes] and their specific settings, requires 
*** former german routing number ("Bankleitzahl") or 
*** name ("Institut") and place ("Ort")

=== Git Repositories ===
AqBanking Git repositories of source code can be found here (mirrored at  ):
<syntaxhighlight lang="sh">
git clone https://git.aquamaniac.de/git/aqbanking   # the library
git clone https://git.aquamaniac.de/git/gwenhywfar  # its OS abstraction layer as dependency
git clone https://git.aquamaniac.de/git/libchipcard # optional for the use of chipcard readers
</syntaxhighlight>
There are also gitweb browser interfaces at 
:http://git.aqbanking.de/gitweb/?p=gwenhywfar.git , 
:http://git.aqbanking.de/gitweb/?p=aqbanking.git .

==== Unofficial GitHub Mirrors ====
Some community members set up (unofficial) github mirrors:

:;Christian Stimmig
::https://github.com/cstim/aqbanking
::https://github.com/cstim/gwenhywfar
::There is also a continuous integration build test of gwenhywfar here: https://travis-ci.org/cstim/gwenhywfar

:;Felix Schwarz, Lukas Matt
::https://github.com/aqbanking/gwenhywfar
::https://github.com/aqbanking/aqbanking
::https://github.com/aqbanking/libchipcard
::A bot script updates the "github.com/aqbanking" mirror on a daily basis so it should always be up-to-date.

=== Currently Unsupported Open Standards ===
While many banks still think ''Security by obscurity'' is a good concept, some countries are changing their opinion:
;AU: https://www.finder.com.au/open-banking
;GB (UK): https://www.openbanking.org.uk/