Create your own bank selection

Kontomatik offers a solution where you can create your own frontend for the list of banks instead of users selecting a bank in our SignIn Flow.

Please note that you will not have control over the subsequent verification steps, which must remain unchanged for security and compliance reasons.

Required steps

In order to show such list to the users, you will need to:

1. Consider the desired access mode
2. Obtain the list of enabled banks
3. Pass the selected bank identifier to the SignIn Flow parameters

Enabled banks and access modes

To get the list of enabled banks and their identifiers to be passed to the SignIn Flow, we provide the AIS Catalog command.

Before you call the API you will need to consider which access mode you will require from the user and pass the adequate value to the accessMode parameter:

• SINGLE - you only need one-time access to user’s data (AIS Single Access)
• MULTIPLE - you have the AIS Multiple Access service in your contract and you will be refreshing the user data for up to 180 days
• MIXED (default) - you prefer the multiple access mode, but you want to get single access for banks that don’t support data refresh

The response returned by the /catalog.xml command will contain all currently enabled targets that are available in the chosen access mode, along with information about the currently used interface type, a list of available commands, and other relevant information.

Target and institution

Kontomatik may provide a multitude of connections per bank. This is due to banks providing multiple access points or different platforms for their customers (e.g. separate online banking for individual and corporate) and different implementations on our side.

When obtaining the list of enabled banks, you’re actually getting a list of enabled targets. The list may change dynamically, usually due to a bank failure - in such cases we switch the connection type from one to another to provide a seamless service within an institution or just disable the bank access entirely.

This is why you have to fetch the target list - your own list should be based on the institutions provided within the targets, but later in the process you will have to provide the target name to the SignIn Flow.

For example, you receive the following list of targets:

You should scan the list to find the institutions and then match them to your own list you will display to the user. When you do so, it will be possible to display the same list even if the targets change:

Please remember to handle cases where:

• an institution/target disappear entirely
• a new institution/target appears in the catalog

Passing the target to the SignIn Flow

As an example, let’s say that you’ve made a command catalog request and received a response that contains the following snippet:

<target country="pl" name="MBankApi" institution="MBank" officialName="mBank" officialUrl="https://www.mbank.pl" psd2="true">

After the user clicks this option, you should match the institution chosen to the target currently enabled and visible in the catalog. Then, you should pass the target name attribute as a value for the target parameter in the SignIn Flow.

Additionally, to ensure the user is directed to the correct process, you need to provide the accessMode parameter to the SignIn Flow as well. Remember that:

• It has to match the value that you provided earlier in the AIS Catalog API call
• MIXED is the default value in the AIS Catalog, but SINGLE is default for the SignIn Flow

For the SignIn Widget, the result would look something like this:

embedKontomatik({
  'client': 'YOUR_CLIENT_ID'
  'divId': 'kontomatik',
  'target': 'MBankApi',
  ...,
  'psd2': {
    'accessMode': 'MIXED'
  }
});

Frequency of fetching the catalog

We recommend asking for the AIS Catalog every time you need to display the list to your user.

You can cache the response and refresh it in 10 minute intervals, however, by doing so you risk that the target chosen by your user becomes unavailable between your last catalog call and your SignIn Flow invocation.

We strongly disapprove of creating a hard-coded list of the targets or fetching the catalog less often. Such an approach leads to many Widget errors received either by you or your users.