Update a Bank Connection - for Web Form 2.0 customers

Overview

After you have imported the bank connection(s), you may want to keep the bank account data up-to-date.

You could use the finAPI Batch Update add-on to enable automated updates (more information: Automated Update of the Bank Data (Batch Updates)).

You can also use the Update a bank connection endpoint to trigger the updates:

POST /api/tasks/backgroundUpdate

There are several use cases where you may need to use this service (use cases can be combined):

• Update existing accounts and download new transactions;

• Import new accounts + update existing accounts and download new transactions;

• Update user’s credentials + update existing accounts and download new transactions.

Use cases

Update existing accounts and download new transactions

In many cases, we will be able to update users' accounts and transactions without needing end-user intervention to enter their bank credentials and provide a TAN.

However, it is not always possible. Sometimes, depending on the feedback from the bank, we will need to ask end-users to enter credentials and/or provide the second factor. For example, if the last authorization at the bank was performed more than 90 days ago. Some banks may require to get a new user token for each interaction, so unless the user has saved the credentials at finAPI, we would require the user to provide them with every update. There could be other cases as well. As a general rule, finAPI will always try to perform an update without getting users to re-enter credentials whenever possible.

1. In the API request, provide the bankConnectionIds for which you would like to update the account and transaction data. The service will generate a task that will try to update the given bank connection without user interaction.

2. Retrieve the status of the task. You can either call the Get a task service until the task status changes or a callback can be sent to the callbacks' URL provided in the request payload. There are two possible outcomes for task execution:

   1. Task status = WEB_FORM_REQUIRED. This step is optional and means user action is required.

      1. Once you receive this status, either by polling or through a callback (callbacks.webFormRequired), you have to redirect the user to the web form.

      2. The user will have to complete the actions on the web form.

      3. Retrieve the status of the web form. You can either call the Get a web form service or a callback can be sent to the callback URL provided in the request payload (callbacks. finalized).

      4. The task status will not change any further once it reaches this state. Any further tracking of status should be directed towards the associated Web Form.

   2. Task status = COMPLETED or COMPLETED_WITH_ERROR. This means the task completed

      1. The task was completed without user action required.

3. Get the status of the bank connection via the Get a bank connection endpoint:

   CODE

   GET /bankConnections/{id}

4. Upon successful completion of the bank connection update, you can get the updated account and transaction data:

GET /accounts
GET /transactions

Import new accounts + update existing accounts and download new transactions

If there are more accounts at the bank that you want to import for your user, you can use the Update a bank connection service and set importNewAccounts to true in the payload. Without this parameter, we will always update only those accounts which were downloaded during the initial import.

You may also specify the accountTypes which you want to import. When you provide this parameter, the API will attempt to import only those account types and stop once we have covered every account type that is requested. (BAUSPAREN┃CHECKING┃CREDIT_CARD┃LOAN┃MEMBERSHIP┃SAVINGS┃SECURITY)

The flow is the same as for the above use case. Please note, that in some cases, the user will have to enter the bank credentials and the second factor.

Update user’s credentials + update existing accounts and download new transactions

If the user has saved the login credentials (during import or later updates) and the credentials have changed since then, you can trigger the Update bank connection endpoint and indicate that you want the user to update the credentials by adding the following to the request payload:

"manageSavedSettings": [
    "CREDENTIALS"
  ]

The flow will always require a web form to edit credentials, and as such, the endpoint will respond with a task directly in WEB_FORM_REQUIRED status. No callbacks.webFormRequired callback will be triggered.

Immediate Web Form

The web form checks the given bank connection in finAPI Access and based on this information, it determines if the update operation will require user action (e.g. new version of terms and conditions or while the user wants to manage the bank credentials he has stored with us). In those cases, the service directly responds with the task status WEB_FORM_REQUIRED and the web form URL. No callbacks.webFormRequired callback will be triggered.