Frequently Asked Questions

The Banking API allows you to import data from the end-user account from any supported bank to your system. To do that, the user has to log in to a bank via our SignIn Widget. The widget is provided along with the API. To find out more about the widget please refer to widget section of the technical documentation here ».

After the end-user logs in you get the session parameters from The SignIn Widget that you can use to perform an import. There are two ways in which you can do it:

• Using Default import flow that downloads all available data with a single command
• Using Advanced import flow to get only information that is necessary to you.

We highly recommend using the Default import as it’s easiest to integrate with. If you plan to use Advanced version to get all the data, you need to consider that the import will be slower, it’s easier to make an integration mistake, and you can’t mix it with the Default version.

You can find the features table here »

Kontomatik Banking API supports major banks in many countries and we’re ready to add more. Additionally in Poland we also offer a PDF Parsing API. On top of that, both APIs come with extensions adding high-level analytics and transaction labels to the raw data extracted from online banks or the PDF statements. To help you get to know our full capabilities we’ve prepared a spreadsheet containing:

• covered countries, APIs and analytics products,
• detailed list of integrated banks with features such as credit cards or type of accounts,
• matrix of data possible to fetch from each bank,
• supported banks via PDF parsing API,
• list of available test accounts for Banking API.

Go to Kontomatik Services & Coverage table »

In some banks we do support corporate accounts. These banks will be tagged accordingly in the coverage table here », under the “Supported accounts” column.

However, please note that in most cases access to the account via PSD2 channels is blocked by default and any attempts to go through the Kontomatik process will result in an error on the redirection page. We have no control over this, nor do we get any feedback from the bank why an error occurred.

In such cases please inform the end-user that this option needs to be enabled in the online banking system - usually by a person with the highest access control, typically the account holder (owner or president of the company, CFO etc.).

This feature might be named differently in banks, but we’ve seen options such as “PSD2 consent” or “AIS / PIS / CAF access”.

The PSD2 directive specifies what type of data should be shared by banks. Nevertheless, banks may interpret the specific rules differently and as a result, share more or less data than necessary. As for Kontomatik, if it’s available via banking API, we support accessing:

• bank account’s owners and co-owners*
• bank accounts list
• transactions for the selected bank account and period**
• credit cards’ details***
• money transactions associated with a given credit card***

*Please note that each bank may share different details about owners. You can find the scope for each bank here ».

**You can only get data for up to 5 years in the past - older transactions cannot be downloaded.

***Importing credits cards is only available in Poland and Spain in selected banks.

Kontomatik is an AISP (Account Information Service Provider) provider in compliance with AISP regulations as per the implementation of the PSD2 directive. In the case of import using the PSD2 API interface, the European Directive guarantees the end user (PSU) to indicate the account to which he grants access to Kontomatik (AISP). Only accounts chosen by the PSU will be returned in the response.

By default, up to 90 days of the transaction history can be accessed. In selected banks, it is possible to obtain more transactions after applying appropriate parameters in the SignIn Widget. These parameters are described in one of our user guides Getting more than 90 days of data ».

This varies greatly between banks, users, and the kind of data you want to import. Some banks have very slow online platforms while others are blazing fast. Some users have few transactions while others have thousands.

Our worldwide median is 11.8 seconds. This is a total session ‘runtime’. The sole default import command median is 10.4 seconds, but if you are only after the owner’s data (identity confirmation), then the median goes down to 1.8 seconds.

Even though the import time via the PSD2 API is mainly influenced by the bank’s responsiveness, we strive to provide as fast service as possible on our end.

In case the fallback mechanism has to be used, we are proud to be known for speed among competing solutions. We are fast because we do not run a farm of headless browsers, we do not run any JavaScript, and we do not download any assets. We reverse engineer how HTTP requests are put together, and then we recreate them directly in Java with no overhead.

Kontomatik is a licensed Account Information Service Provider (AISP) and this allows us to access users’ accounts via APIs. Banks are obliged to provide the APIs in accordance with the Payment Services Directive 2 (PSD2) directive.

If a bank doesn’t provide a PSD2 API, we use the fallback mechanism, which typically requires us to use our proprietary screen scraping solution. The method mimics a human using a web browser and therefore can potentially access any bank.

In order to make the importing run and integrate with our service you need to follow these steps:

1. Get your client ID from Kontomatik Team, whitelist your backend IP addresses and generate API keys on our Insight platform.
2. Embed the SignIn Widget on your page - preferably a separate one in your process flow.
3. Handle callbacks returned by Widget - at least onSuccess and onError.
4. Integrate with our backend API following the technical documentation. Integrate with end-points you wish to use.
5. If the login process went well, your frontend will receive session information that you have to send to your backend.
6. As soon as possible, on your backend you need to set up a command on Kontomatik servers using the session information and your API key. You can use Default import or one of the Advanced API commands. As a response, you will get a command id.
7. Poll for the status of your command using previous information. Repeat until you receive an error or the requested data.
8. (if applicable) Request for Kontomatik Score as a separate request.
9. Done

When we use the PSD2 API provided by a bank, then the API automatically handles SCA. If we are unable to use the API, then our widget natively supports most SCA methods depending on a bank.

Some of the SCA methods we support include:

1. Hardware tokens
2. SMS codes.
3. Mobile OTPs
4. CAPTCHAs
5. Anti-phishing pictures

Importing data periodically in the background is available as a beta phase in Poland and Czech, and we call this service “Multiple access”. The service is described here » with additional FAQs under this section ».

Unfortunately, the design of our solution doesn’t allow to be notified when the import is complete. This decision has been made to greatly reduce the security risks arising from clients having to open their servers to incoming connections.

To find out about the progress of the import, you simply have to send an appropriate request to our server. For our server to authenticate you and respond to you with the status of the correct command, you will need the command id, session id, session id signature and your API key. You can read more about here ».

We have no control over the session duration. Access to banking data via Kontomatik is the same as access via the browser by the end-user - the bank server controls the session duration and inactive user sessions are terminated after 5 minutes or less. Therefore, it is important to start importing the data as soon as you get the necessary parameters: session id and session id signature. To know how to import data from the end-user account, please read about it here ».

In the SaaS model, this will be a Kontomatik-controlled IP.

Our API doesn’t provide a functionality that would allow to import the data from multiple accounts in one session.

You can ask the end-user whether they would like to use the widget again to share the data from a different account. Although, logging into another account will be counted as another session so you will be charged for it separately.

By setting the same externalOwnerId parameter in the widget for the aforementioned multiple sessions, the client is able to aggregate the imported data from multiple accounts using the data command described here ».

When it comes to the Kontomatik SignIn Widget, we only charge for sessions where all import commands have executed successfully. A session starts when the user logs into a bank through our widget, and it ends when the sign-out command is sent, or the maximum time of the session is reached (usually 5 minutes of inactivity).

If an import command fails for any reason, including factors beyond our control, such as connection issues, that session will not be added to your bill.

Please note that you will be charged the same whether you use Default or Advanced importing flow.

Multiple access is available only for select targets in Poland and Czech - you will find them here » (the targets using this feature will be marked “Yes” in the “Multiple access” column).

The service will only work with PSD2 API connections so if you’re switched to a fallback version of a given target, even for the Single access, it will not work in the Multiple access mode.

Due to technical reasons and PSD2 as well as RTS regulations, the limits are as follows:

1. The access is given for up to 180 days. The period can be shortened if either the bank or the user revoke the access earlier.
2. Using Multiple access, the session created right after the first end-user log in allows you to fetch the same amount of transaction history as you would get via Single access. However, each subsequent session within Multiple access will only return data up to the last 180 days.
3. Using Multiple access, you can import data up to 4 times in a 24 hour timeframe. This number can be lower if the user gave his account access to another company as well.

Every Multiple access consent is split into 30-day cycles of availability. At the end of each month you pay a basic fee per each cycle that ended within that month and additional fee for every successful Banking API session within those cycles.

The basic fee for a consent will not apply if all sessions end with an error within a cycle. However, if no import is made within that period or all have been abandoned by you (after using the Reuse Multiple Access endpoint), the basic fee will still apply.

If a consent has been withdrawn before the end of the 30-day cycle (if for example the user withdraws the consent), you will still be charged fully for that cycle.

Contact our Sales team to get more info and a quote for your business.

A proper error will be returned as a response to the Reuse Multiple access endpoint. See our documentation » for more details.

As we recently launched this service, we don’t have enough production usage to be sure that the service is sufficiently stable. There might be some bugs (including major ones) that we haven’t encountered yet - either in banks’ APIs or on our side.

Additionally, with more clients testing the service, we might make adjustments to fit better the actual usage and improve user experience.

Please note that this also means changes in our API and documentation, some of which will need to be implemented by you more often than when it comes to our stable services. The changes might cover supported banks, integration methods, used parameters, terms of use or any other part of the feature.

We don’t have a specific timeline for ending the beta phase. We will do so as soon as we see that the solution is used on a daily basis by our clients and popular bugs no longer occur.

We will look into expanding the service as soon as the beta phase concludes.

With that said, we are still limited by some APIs’ basic quality as well as actual demand in certain clients for this service.

If you have any specific banks or countries in mind, contact our Sales team to discuss your needs.

Kontomatik SignIn Widget is a front-end website widget that takes end-to-end care of the bank selection and login process of the end-user. Upon successful login, it provides you with an authenticated session that lets you import the data about the end-user from their bank.

The implementation of the widget is very easy and requires just a few lines of code in JavaScript and HTML. You can find out how to do it under this link ».

Note that you will need the API key and the Client ID to make the widget run. If you don’t have them yet, please request a demo under this link ».

Remember that you will need to send an appropriate request to the Kontomatik server to make it start importing the data from the end-user account. We suggest doing it as soon as the end-user logins to the bank and the widget returns the session id and the session id signature. To find out what you should use, please read through our Account Information Service documentation section.

You can easily customize the colors of the widget using CSS parameters predefined by us. We believe that you can set them so that the styling of the widget will match the branding of your company. You can find out how to do it here ».

Note that we do not allow arbitrary CSS overrides. This decision is based on the fact that we update the widget often to improve the conversion rate, security, and usability. This would effectively break any custom overrides after the update.

We strongly discourage our clients from implementing their login front-end. Based on the many years of practice and experience in the field, we developed an ecosystem that is secure without compromises and in which each part plays a crucial role.

Why implementing your login front-end is a bad idea?

• You would have to take care of the security of your solution, handling sensitive login information.
• The conversion rate may be affected due to unexpected and external issues the client will inevitably face. Having observed the behaviors of our end-users we have been able to tailor the solution, so it achieves the best possible conversion rate.
• The cost a company incurs while researching and developing a widget may be substantially high. When buying our Banking API, you get the ready-to-use login solution without additional costs.
• The ever-evolving login scenarios require heavy maintenance costs.
• You lose the Kontomatik end-to-end support.

Nevertheless, if you decide that changing the front-end is a must-have for you, then please contact us, and we will consider your specific case.

Kontomatik SignIn Widget provides a fully responsive design for all devices supporting HTML and Javascript in the native and third-party internet browsers (including PCs and smartphones). The implementation of the widget for the website that will be displayed on mobile devices is the same. The widget will automatically adjust to the size of the screen of the device. Nevertheless, please remember to make your web app’s design responsive.

In a mobile native app please use a WebView component to embed the widget. The details are platform-specific and not particularly related to our widget. You can find many tutorials on the web on how to use the WebView in your platform.

For the PSD2 flow to work properly on native mobile apps, window.open, and window.close function calls have to be handled by the native WebView or the app code.

For your convenience, we have prepared an example of how you might implement the SignIn Widget on an Android smartphone ».

The Zero-integration solution is a SignIn widget mechanism that allows to start importing data automatically after the user successfully logged in to the bank. After the import is finished, the data will be available to see in the Insight portal.

The main advantage of using this solution is that the data will not pass through your servers and as a result you will not be exposed to any security related issues. Moreover, it also takes the burden off you of integrating the Banking API into your pipeline.

After you have embedded the SignIn widget into your website, you will need to set the autoImport parameter along with the since parameter » in the widget.

The Insight portal is a website available to our clients that lets them easily configure API connection, see the imported data visually including the labels, and the scoring results*. Moreover, it also allows to check the statistics regarding the imports and upload a PDF bank statement for parsing**.

You can find out more about Insight here.

*Note that labelling and scoring are an optional extension to our Banking API and is charged separately.

**Note that the PDF Parsing API is a separate product to the Banking API.

The data will appear automatically in the Insight portal after a successful import. Therefore, the only thing you have to do beforehand is to implement the Banking API*. Nevertheless, there is also an option called Zero-integration solution that doesn’t require you to implement the Banking API, but in order for it to work, you must use our widget and configure the auto import parameter in it.

*Note that if you use the Advanced API command that deletes the imported data from the server, then it will not be available through Insight.

You will get access to the Insight portal from the sales team after signing the agreement with us for one of our products.

Transaction labelling is a method that assigns labels to a given transaction based on its details (e.g. title, amount and party). We have more than 60 labels to choose from that belong to one of 5 categories: technical, compensation, debt, state, cash, lifestyle and living. Each transaction can have multiple labels from different categories or have none if we can’t properly parse the title properly. The assignment is based on the relationship uncovered by the labelling model in the historical data. The data has been handcrafted by human engineers based on the strict rules defining each label.

Labeling is currently available » in Poland, Spain, Czech Republic, and Portugal.

Scoring is a method that calculates probability of someone’s repayment (score) given the labels and other transaction details. Specifically, the algorithm returns the score, percentile, and tier (e.g. A, B, C, or D). The algorithm is trained using historical data and so is able to recognize very intricate relationships not easily spotted.

If you already have a scoring implemented on your side, you can still use our solution - we consider our model to be a great addition to other scoring methods that supports decision-making.

Scoring is available only for clients who also use our labeling solutions.

If you have labelling enabled, you will get labels along with the transactions automatically. You can also find them in the Insight portal in the section with imports.

To get the scoring you’ll need to perform a separate request after all desired user data has been imported - you can find out more in our documentation.

The scoring algorithm has been designed to help lenders make the decision about their clients given the labels and other transactional data. Despite the fact that the transactions contain all the information that is needed for prediction, the relationship between them and the client’s default may not be easy to uncover for a human. The scoring algorithm was trained on massive amounts of data and so is able to spot these tiny dependencies. Moreover, it is able to explain its result by indicating the labels that were important in its decision process.

The scoring results should be treated as a guidance to make the final decision. The scoring algorithm was designed with great care about its reliability and accuracy, but we can’t guarantee that it will be right all the time. As a result, we ask our clients to look over its results and explanations by themselves before making the final decision.

Labelling and scoring are charged separately. Since labels are assigned automatically to each transaction in an import, you pay a labelling fee for each successful import.

On the other hand, for scoring you pay a fee only when you call the owner scores endpoint. Remember, that labels have to be turned on for scoring to work.

For each input, we are able to calculate the importance of its features on the probability of a person’s default returned by the scoring model. Given that information we are able to judge whether the returned value makes sense.

The scoring algorithm is the machine learning model that can predict the probability of account ‘s holder repayment given the transactions. The rough cookbook is as follows:

• Using our proprietary transactional data, we create heuristics that extract information from the transactions into different numeric features.
• We then train the model given the person’s features and the information whether they default.
• Since the dataset consists of many people, our model is able to learn relationships hidden in the data.

PDF parsing is a general term to describe a class of methods that are able to extract plain text from PDF documents that is human-readable.

Our proprietary PDF Parsing solution is designed specifically for handling bank documents. It automatically recognises transactions, KYC and other related data in a bank statement and extracts them for further processing.

Moreover, our algorithm always tries to verify if the statement wasn’t edited, the data is consistent, the digital signature is correct and other expected features are in place so that you can protect yourself from accepting statements that have been tempered with.

It depends on what is important to you and your end-users. In both cases, you will get the data in the same format. The main difference is that the PDF parsing doesn’t require the user to login to the online bank via our widget. As a result, the end-user has more flexibility on how they obtain the bank statement.

On the other hand, the Banking API combined with our widget makes the whole process of providing the data by the end-user easier.

Finally, the PDF Parsing solution can work entirely from your servers (on-premise) in contrast to the Banking API which is served only via the cloud (SaaS)*.

*On-premise PDF Parsing solution requires separate contracts and fees to the SaaS version. We recommend it only to big companies with highly developed infrastructure and security IT teams.

To parse a PDF bank statement, you need to upload it to the statement endpoint encoded using “Base64” to get the results back in the XML format.

If you choose our SaaS solution, you can also use our front-end widget to upload a pdf without encoding and get the XML later using the data endpoint.

Our PDF parsing solution is mainly used as a SaaS, but we also offer on-premises deployments. It is designed for clients who don’t want the data to go through other servers than their own.

The main disadvantage of using on-premises is the fact that you need to handle infrastructure, security and updates on your own as well as the debugging process becomes much harder and as result it might take longer for our developers to fix the problems.

The PDF Parsing API supports most of the banks in Poland. It is able to parse the data from the account history as well as from the monthly statement. Depending on a bank, each document will contain different types of information.

You can find what we support for each bank here »

All PDFs are checked for the credibility and integrity of the information they contain by our proprietary algorithm.

Whenever we spot that a PDF is not original or was tempered after it was downloaded from the bank website, we will reject the PDF with the appropriate message.

Supported types of documents include:

• Monthly statement (wyciąg)
• Account history (lista transakcji, historia rachunku itp.)

The following are not supported:

• statements from company/corporate accounts (other than sole traders i.e. “Jednoosobowa działalność gospodarcza”),
• statements in English or other languages (the layout needs to be in Polish),
• encrypted statements,
• scans or otherwise prepared documents not downloaded directly from the online banking websites.

The short answer is: no.

The long one includes the following reasoning:

• the OCR tools are still not (and might never be) reliable enough for us to accurately extract data from scanned documents;
• scanned documents are very prone to user errors and deliberate actions to the extent of having too low DPI, wrong brightness, unordered pages, manual modifications and many others;
• anti-tempering verification would not be possible.

Kontomatik charges a fixed price for each uploaded file to the PDF Parsing API in SaaS solution with a monthly base fee when you don’t reach the estimated document volume.

In contrast, the on-premises solution has a yearly fee for the license, support and updates with a one-time implementation fee.

In some cases, determining the status of a transaction is challenging due to the way certain banks prepare confirmations. For some banks, both booked and unbooked confirmations appear identical, making it impossible to distinguish between them. Consequently, there are no discernible differences from which we can determine the status of the transaction.

Like our other new products, Transaction Confirmation is using JSON structure. We also decided to use JSON format to not imply that the data behaves the same as that returned from Banking API or Statement parsing (available in Insight or using features based on aggregated), as the characteristics of transaction confirmations did not allow us to adapt the structure of the returned data to our current data model.

In order to adhere to the PSD2 directive, we strive to be connected to banks via the APIs they provide. Unfortunately, the consequence of it is that if an issue arises, we usually have to rely on a bank to solve it. We make a great effort to report all bugs to banks by constantly testing the APIs. Nevertheless, the time it takes to fix them depends solely on a bank.

Fortunately, we have backup connections ready as a part of the fallback mechanism allowed by the PSD2 directive. We switch to this connection when an error occurs that unable to use the PSD2 API. If the backup connection fails, then the fix takes between several hours and several days depending on the severity. Most issues are resolved very quickly.

In the extreme case of a completely redesigned online system or new version of an API connection, it can take us 1-3 weeks to add support. However, banks often allow both systems to be used for some time before retiring the old one, which buys us more than enough time to switch seamlessly.

If you want to report an issue, please email us at support@kontomatik.com ». If it’s of the technical nature, please make sure you’ve provided all adequate details, e.g.:

• sessionId/commandId,
• screenshots,
• description,
• Kontomatik server response.

Having them might be necessary to resolve the issue. Upon receiving the report, our system will send you an automated confirmation e-mail with the report identifier.

After we’ve had time to analyze the issue, one of our Support Team members will contact you to follow up on it - to say what happened, respond to questions, inform about a successful resolution or give you an estimation on time needed to resolve the bug.

Please don’t send us any personal information about the user. Not only is it unnecessary data processing through unsafe communication channels (email) but also we don’t have the option to search our logs using names or personal IDs, your internal case numbers or with any other data that may have been fetched during the import.

You can report bugs, issues or ask technical questions in Polish or English.

Reporting issues to Kontomatik by the end-users is not recommended, as without technical information (such as sessionId) it’s rarely possible for us to find the specific case in our logs and actually provide any help. Ideally our clients should report issues for the end-user.

The PSD2 Directive is an extensive EU directive designed to make it easier and more secure for users to use payment services. It is further extended by the Regulatory Technical Standards (RTS) which contains technical requirements of solutions proposed by the PSD2. Especially relevant for Kontomatik is a part commonly referred to as Open Banking. It specifies how providers of payment services (third party providers or TPP) should communicate with each other to deliver these services to the end-user (payment service user or PSU).

The PSD2 directive introduces three main types of licensed entities:

1. Account Information Service Provider (AISP),
2. Payment Initiation Service Provider (PISP) and
3. Account Servicing Payment Service Provider (ASPSP)

Kontomatik operates as a licensed AISP. This allows us to request information about PSU from their bank, which in this case works as ASPSP. According to PSD2 and RTS, the communication should happen via an API that is provided by ASPSP.

For situations when the API is temporarily not available, the PSD2 directive establishes the concept of the fallback mechanism. It allows TPPs to connect to the online banking systems like the PSU would do and extract information from there. In order to achieve this, Kontomatik uses screen-scraping technology.

If you’re interested in the full texts of the regulations, you’ll find them here:

1. PSD2: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32015L2366 »
2. RTS: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32018R0389 »

Before the PSD2 directive came into force, Kontomatik had to rely solely on the screen-scraping technology. Screen-scraping is a set of techniques allowing to mimic a human accessing services via browser. As a result, we have been able to extract the same information from the banking system as a human would have. Nevertheless, under the PSD2 directive some information is not meant to be shared with anyone apart from the owner of an account.

Our main objective is to preserve existing data guarantees while staying fully compliant. To this end, the plan is to gradually transition to Open Banking APIs as they become available, while also preserving our screen-scraping capabilities as a part of a fallback mechanism for targets which provide a low quality interface.

This highly depends on the online interface that a bank has and regulations in a given country. As a result, we would need some time to do research on whether we would be able to add a bank.

If you’re thinking about some particular bank, that is not on our list of supported banks », please contact us to see what we can do.

Kontomatik doesn’t provide any real accounts for testing.

However you can test our solution using our mock bank called “Kontomatik Bank”. It allows you to test both API and screen-scraping login flows. To find out more about testing see our Testing documentation ».

Yes, both widgets can work separately on one page in your online process, however please note the following:

• make sure you use different HTML containers for each one (divId in the embed function),
• handle callbacks separately and according to actions that are supposed to happen after each process is finished,
• prepare a clear communication to the user about which widget they should use,
• consider situations where user goes through just SignIn Widget, PDF Widget or both*.

*You can optionally prevent the user from using both by handling our callbacks (e.g. hide one of them when the other returns onSuccess callback).

You can PGP-encrypt communication with the Kontomatik public key available at https://get.kontomatik.com/keys/kontomatik.asc »

Please report any vulnerabilities to security@kontomatik.com » encrypted with our public key.

• Our services are hosted in Google Cloud Platform provided by Chmura Krajowa ». The servers are physically located in Frankfurt (Germany) and Amsterdam (Netherlands). Using the services of Chmura Krajowa ensures that Kontomatik is compliant with regulations set out by the Polish Financial Supervision Commission (KNF).
• Kontomatik processes personal data only in the EU area in accordance with the GDPR recommendations.
• Kontomatik complies with the highest market security standards and practices and is ISO/IEC 27001 certified in Information Security Management System. We renew our certification yearly.
• We follow the least privileges policy - only the necessary and trained employees have access to Kontomatik production servers and the network.
• Each data access is logged and monitored.
• We strive to have the highest quality code on the production. Source code must pass automatic tests and a code review before going live.
• We do not outsource software development.

• Bank credentials will never pass through your servers. Kontomatik SignIn Widget encapsulates the login process end to end.
• We don’t have access to the bank credentials during the standard AIS process. The only exception is when the fallback mechanism is used - then the bank credentials are temporarily stored in a volatile memory (RAM) and are discarded soon after logging the user into the bank.
• Financial data is removed automatically from Kontomatik servers after 24 hours. Clients can remove data sooner by using the appropriate endpoint in our API.
• Kontomatik connects with banks using HTTPS protocol - the very same way the end user would do using his web browser. Kontomatik checks the validity of banks’ certificates on each and every request.
• The API client connects with Kontomatik using high-grade HTTPS (by default).
• We require two-factor authentication with: API key and IP whitelist. Moreover, each session gets a unique id that only combined with the API key allows to get the financial data.