FAQ

Banking API

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 »

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 ».

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

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 the documentation in the Getting more than 90 days of data » section.

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.

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 in Poland and we call this service “Multiple Access”. The feature is supported only for the banks that have the API adhering to the PSD2 directive and its quality standards. It allows you to import the data up to 4 times per day throughout 90 days in the background.

In our documentation here », you’ll find a description on how it works. Supported banks are marked as ‘yes’ under the Multiple Access column in this sheet ».

Multiple Access is a separate service and different fees than in the Single Access may apply. Contact our Sales to find out more.

Please note that the service is still in beta state - supported banks, integration methods, used parameters or terms of use are subject to change.

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.

SignIn Widget

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 Importing data documentation.

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.
  • Having observed the behaviors of our end-users we have been able to tailor the solution, so it achieves a great conversion rate.
  • When buying our Banking API solution, you get the widget along with it free of charge.
  • 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 ».

Zero Integration Solution

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.

Insight portal

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.

Labelling and scoring

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 50 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 default (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 default 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

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.

Our technology

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.

Miscellaneous

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 [email protected] ». 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.

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 ».

Security

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

Please report any vulnerabilities to [email protected] » 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. In December 2018 Kontomatik was awarded ISO/IEC 27001:2013 Information Security Management System certificate and we continue to renew the certification yearly ever since.
  • Only the necessary and trained employees have access to Kontomatik production servers and the network.
  • 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 the Banking 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.

Documentation

Banking API

Read-only API to banks. Import all data from any supported bank into your system.

Open
Parsing API

PDF parsing API enables checking PDF statements against tampering attempts.

Open
Zero-integration solution

Easy integration with access to data via Customer Platform.

Open

Contact

Sales Contact

Do you need help in explaining our products, costs, and cooperation?

Contact our Sales team
Support Contact

Do you have technical questions about our products and services?

Contact Support