In this article, we want to give you some guidelines on how you can implement the import and update of bank connections / accounts in your application, with the aim of having both stable code in your application, as well as a solid end-user experience.
First, you should understand that it is actually only bank connections that you can import or update – there’s no services for importing or updating individual accounts. Accounts relate to bank connections, and whenever you import or update a bank connection, all accounts that this bank connection holds will be imported / updated. This means that when you want to update all accounts of a bank connection, you just have to call the update service for this connection once. Knowing this, let’s now get into the details of the bank connection import and update.
Import of a new bank connection:
For importing a new bank connection, you have to use the service /bankConnections/import. Given that the communication to the bank server was successful and the given credentials were valid, the service call returns with various information about the newly created bank connection; in particular it will contain the identifiers of the accounts that have been imported for the connection (field accountIds).
At this point, it is crucial that you regard the updateStatus field of the returned bank connection: This field can have two different values: READY, or IN_PROGRESS. When the import service call returns, you will find that the bank connection’s update status is usually IN_PROGRESS. What this means is that - while you can already process the bank connection’s data (e.g. the fields about money transfer support) or look up the accounts contained in the accountIds field - the data for the accounts might not be fully downloaded yet. More precisely, ‘data’ here means the account’s balance and transactions/security positions; other data like the account number, account name etc will already be available. But as long as the bank connection’s update status is still IN_PROGRESS, you might not have any balance information for the accounts, or no (or only a few) transactions / security positions. So what you should do is either wait until the bank connection’s status has switched to READY, or – if you want to show account details to the user as fast as possible – let the user know that data download is still in progress in the background.
Once the bank connection’s status field has switched to READY, the import process is completed. However, here’s another thing that you must be aware of: When the import has completed, it doesn’t necessarily mean that it was successful - in terms of that all data for all accounts could be successfully loaded. The data for some accounts might have been loaded successfully, while it could have failed for other accounts. The status READY just means that there is no ongoing import or update process for this bank connection, and it is ready to be updated again. But to find out the end result of the entire process, you have to now check the status field of the individual accounts. If an account’s status is UPDATED, it means that all data could be successfully downloaded. If it has status DOWNLOAD_FAILED, all or some of its data could not be loaded. For instance, you might have the account’s balance, but no transactions. Note that these two statuses are the only statuses that can appear when importing new accounts – the other statuses can appear only when updating an existing account.
Aside from the bank connection’s updateStatus field and the accounts’ status field, there is another field that might be of interest for you: The bank connection’s categorizationStatus field. Similar to the updateStatus field, as long as the categorizationStatus field is not READY, it means that the process of automatic transactions categorization is still going on. You and your users should be aware that as long as this field is not READY,transactions might still be assigned categories by a background process.
Putting all this information together, here’s a graphic that shows the abstract logic that you should follow in your implementation of the bank connection import:
Update of an existing bank connection:
The update of an existing bank connection basically follows the same process as the import. The only difference in the update process compared to the import process – aside of course from the fact that you need to call a different service, namely /bankConnections/update, and that this service returns HTTP code 200 instead of 201 in case of success - is that the status field of the accounts can have some new values. More precisely, there can be two new statuses:
- UPDATED_FIXED means that the data could be loaded, however finAPI detected inconsistencies between the account balance and its transactions. For more details, please see the documentation for this status
- DEPRECATED means that the account was no longer sent by the bank server, or could not get matched with an existing account by finAPI. Nothing was changed for this account.
So for the update process, you can re-use most of your code from the import process, and only add handling for the new possible account statuses (for instance, just show a different information/icon for the respective accounts in your frontend).
If you still have any questions left unanswered about how to implement the bank connection import or update, please let us know at firstname.lastname@example.org