Connect a provider access

In order to be able to fetch financial data from a provider, the corresponding access has to be configured first. The configuration procedure is summarized as follows

Lookup the financial provider to be connected in the catalog and select one of the available access methods. Also notice which credentials are required to be used for this provider access.
Obtain the required login credentials as specified by the access method from the customer.
Add a new access handle.
Start a synchronization for the access.
Guide the customer through the process of strong customer authentication.

Synchronize a provider access

To keep the financial data accessible through the finX API up-to-date, the financial provider has to be periodically queried for updates. This process is called synchronization. The finX API performs an automatic synchronization on a daily basis, as long as the customer has given the authorization to store the credentials for the provider access to be synchronized.

A synchronization that is manually triggered through the API allows the customer to respond to authorization challenges.

Synchronization scope

The kind of data that is fetched during a synchronization can be defined through the scope field. By default, account and transaction data is retrieved from the provider ("TRANSACTIONS" scope). If only account information is needed (as in the verifier use case), the "ACCOUNTS" scope should be provided. This will speed up the synchronization process. The "ACCOUNTS" scope can also be used on a previously synced access to add new accounts. This is useful if the customer has opened a new account with the provider and wants to add it to an existing access.

Access upgrades

Whenever a bank offers a PSD2 compliant API, TPPs have to change their means of accessing payment accounts at that bank. This process requires the active participation of your end-user as strong customer authentication is required when accessing accounts via the PSD2 APIs for the first time.

Once support for a new PSD2 API is rolled out to production, the autosync for affected accesses will stop. The first synchronization attempt by your application for affected accesses will initiate an access upgrade process and the synchronization will fail. The process updates existing access and associated accounts with regard to the linked access method.

Before retrying the synchronization process, it should be ensured that the end-user is ready to perform strong customer authentication within your application.

General information on what kind of updates were carried out during the upgrade process can be concluded from the error code. Specific details on new access_id per account and new access_method_id are included as data in the error object.

Error code	Description	Updates	Example
`40001`	Direct access upgrade	The access has been assigned a new access method.	An access with one `Giro account` is assigned a `API` access method instead of a `FINTS` access method.
`40002`	Multi-access upgrade	The access has been assigned a new access method. At least one additional access has been created.	An access with one `Giro account` and one `Savings account` is split into two accesses. The `Giro account` is associated with a new access linked to an `API` access method. The `Savings account` remains with existing access and is associated with `FINTS` access method
`40003`	Partial access upgrade	The access has been assigned a new access method. The new access method may not support all connected accounts anymore. Additional accesses may have been created.	An access with one `Giro account` and one `Savings account` is only partially supported with new `API` access method. `Giro account` is still supported with `API` access method, but `Savings account` is not supported anymore and remains with existing access.

Background operations

Interactions with a financial service provider are never executed in the scope of an API request, but rather performed asynchronously in the background. A synchronization is an example for such a background operation. The states that a synchronization can traverse during its lifetime are defined by the following state-machine.

Every synchronization starts in the QUEDED state and is moved to the RUNNING state when it is picked up by the job processing backend. While communicating with the financial service provider, an authorization challenge can be issued, in which case the synchronization is moved to the AWAIT_AUTH state. In this state, the end-user's interaction is required in order to solve the challenge. For a detailed description of available challenge types, see the section Strong Customer Authentication.

After the challenge has been solved, the synchronization switches back to the RUNNING state and eventually to the COMPLETED state. While processing a synchronization, multiple authorization challenges can be issued so that the state can toggle between AWAIT_AUTH and RUNNING. In case of an error, the work item's state will be set to FAILED and no further
processing will take place.