Kontomatik is a read-only API to banks. Kontomatik is able to import personal data, account balances and full statements from any supported bank to your system. To do that, Kontomatik will need end user bank credentials (most often a bank login and password). To ask the end user for bank credentials, Kontomatik offers a widget which you can embed on your website as an iframe.
Pleasure to integrate
Kontomatik offers a clean and consistent API over HTTPS.
The big picture:
- You embed the Kontomatik widget iframe on your website. The widget allows your users to securely sign in to enabled banks. The widget looks like this.
- Use the session in your server-side app to access the banking data of your user.
- Act upon the received data. Profit!
Banking API - tutorial and reference for programmers on how to embed the widget, import data and use the high-level lending features.
Zero-integration solution - no IT resources? No problem! Just copy-paste our widget into your website, go to our Insight app and display the essential in the user’s profile: identification data, street view of his home address and financial health assessment.
PDF parsing API - workaround for banks in Poland who cannot use screen-scraping based banking APIs for regulatory reasons.
Kontomatik products and world coverage
Kontomatik Banking API supports major banks in 10 countries on 3 continents. From Brazil to Spain or Russia, we go with our clients everywhere, worldwide. If the country you need is missing from our present coverage, just let us know and we will happily develop it for you. See detailed coverage reports below:
Our core technology comes with a number of API extensions adding high-level analytics and transaction labels to the raw data extracted from online banks. For the geographic availability of all Kontomatik products, components and features, please check this table:
Finally, for the coverage details of the PDF-Parsing API (currently available only in Poland) we have a separate report:
What data can I get?
Kontomatik supports accessing:
- personal data of the account owners (docs and examples)
- current and saving accounts (docs and examples)
- transaction history from those accounts (docs and examples)
How many months of transaction history can I access?
Kontomatik can access the whole transaction history available in an online bank. In practice, this translates to something between 10 years and 2 months depending on a bank.
Typically our clients import 3 months of history. This is a very good balance of speed, reliability and data.
Some clients import 6 months of history. This is also perfectly fine but you will have to wait a bit longer for data. It also very slightly increases the risk of a random error.
Most importantly, this is entirely under your control through the HTTP
How long does it take to import the data?
This varies greatly between banks, users and 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 12 seconds for 3 months of transactions. This is a total session ‘runtime’ including signing-in.
If you are only after owners personal data (identity confirmation) then it will get down to 1-3 seconds on average.
Does Kontomatik support importing credit cards, term deposits, mortgages, insurance policies, mutual funds, stocks and other assets?
Kontomatik supports importing personal data of account owner(s), current and saving accounts and transactions from those accounts.
As of today there is no support for importing any other data, except for Poland where we do support credit cards and term deposits.
If you need support for additional data then there is no technical limitation for us to develop it but we would need your close cooperation with regard to providing test bank accounts with those specific assets on your target market.
How does Kontomatik access bank data? Does Kontomatik have agreements with all supported banks?
Under the hood Kontomatik uses screen scraping to mimic a human using a web browser. By using the very same protocol as a web browser Kontomatik can potentially support any bank worldwide in a permissionless way. Kontomatik does not need agreements with all supported banks. Kontomatik exemplifies permissionless innovation.
When a bank introduces a change how long does it take for Kontomatik to catch up?
The fix takes between several hours and several days depending on the severity. Most issues are resolved very quickly.
By the way, most issues affect few users and do not impede the overall conversion rate in a meaningful way.
In the extreme case of a completely new online system 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 support for some bank is temporarily broken we dynamically turn it off in the widget and API with zero action necessary on your side.
To sum up, we aim to create a “just works” experience for the API client. You are not expected to manage this in any way.
Does Kontomatik support hardware tokens, SMS codes, mobile OTPs, CAPTCHA-s, anti-phishing pictures?
Yes, Kontomatik natively supports hardware tokens, SMS codes, mobile-application-generated One-Time Passwords, CAPTCHA pictures and anti-phishing pictures.
Can banks block Kontomatik?
Secondly, in the European Union, the Kontomatik model of operation is protected by the Payment Services Directive 2 (PSD2) which specifically requires banks to not hinder this kind of solutions. With PSD2, regulators aim to increase competition and benefit the customer.
That being said, in principle screen scraping can be detected and prevented, but this is a cat and mouse kind of thing and we are good at it. Our experience so far is that banks’ IT departments have more important things to do than targeting Kontomatik in a meaningful way.
We are doing pretty well on all covered markets and we feel confident entering new ones.
Can I safely assume Kontomatik can add support for any online bank in the world?
Well, almost. Our track record is to give up on about 1 bank in 25 - not because it’s impossible but because it would be very ineffective cost-wise (for us) or usability-wise (for the end user). Contact us for more information.
Can I easily CSS-customize Kontomatik SignIn Widget?
Please carefully read the docs to learn to what extent this is currently possible.
How can I implement my own login front-end? I don’t want to use Kontomatik Widget. I need a full control.
We do have a fully-featured login API to potentially enable custom front-ends but we highly discourage this path.
Without Kontomatik Widget:
You face a very serious security threat as sensitive bank credentials would pass through your servers. Do you have a security department to oversee your network and server infrastructure, audit your code, enforce security policy, etc? With the widget bank credentials never pass through your servers. They go from the end user directly to Kontomatik.
You face a substantially decreased conversion rate. Please be aware the end users find it intrisically hard to login to bank on any 3rd party website - they have to consciously map what they do in a bank to the new situation. We commit huge development resources to continuosly improve widget’s user experience, including matching what end users are used to experience in their banks. We match per-bank labels and copy, we update screenshots and favicons, we recreate and support the whole complex login schemes, paths and scenarios including masked passwords, picture / avatar selection, CAPTACH-s, one time passwords from hardware tokens and SMS-es, memorable information strongly typed input fields, document numbers, branches, etc.
You face heavy maintenance costs as the login scenarios employed by banks are complex and ever-evolving. You would have to continuosly recreate and update these scenarios in your frontend, otherwise you would quickly find your solution outdated and users unable to login.
You lose Kontomatik end-to-end support because we won’t be able to effectively debug the issues. You are on your own debugging why users struggle and why conversion is disappointing in some banks.
For the reasons outlined above we consider Kontomatik Widget obligatory part of our technology and offering.
If you strongly feel like developing your own frontend anyway, please let us know and we will reconsider your specific case.
Native mobile apps - how can I use Kontomatik there?
Kontomatik Widget sports a fully responsive design, ranging from iPhone 4 screen size.
In a mobile web app simply embed the widget as ususal. Don’t forget to make your web app’s design responsive.
Can I import data periodically in the background to update my application while end users are offline?
If you mean to import data from your own bank account(s) then yes. In this scenario you would not use the widget. Instead you would use our sign-in API directly, passing your own bank credentials every time. For example, this makes sense if you want to track incoming payments on your bank account to mark invoices as paid, or loans as repaid. Documentation for this (sign-in) part of the API is not available online. We will provide you with it once the contract is signed.
If you mean to import data from the bank accounts of a limited group of your trusted business contractors then yes. See the above answer. You would have to officially store the bank credentials of your contractors.
Also, please see the chapter on security.
Can you add callbacks to Kontomatik API?
Kontomatik never calls your app. You poll for results of async commands. This is by design. We believe this is right. Please consider:
Reduced coupling. Only one direction of API calling. Only one direction of dependencies. This enhances independent deployment. No retry schedules of missed callbacks. You will never miss a callback. Simply ask for data when you are back online and ready.
Allows the API client to implement the session flow in the imperative, easy-to-follow way. No event-driven parallel mess in your app. You know when you are done with the session. No late/unexpected events to deal with.
Does not require you to have a web server to receive callbacks. Your API client can be a backend process or a command line tool if you will.
Improved security of Kontomatik servers. We have outgoing connections disabled, except for whitelisted online banking systems.
The only downside is that you will need some kind of a background job runner in your app. But having one is best practice anyway, except for the most trivial apps.
What IP address will be used to access bank systems?
In the SaaS model, this will be a Kontomatik-controlled IP. In the on-premises model, this will be an IP controlled by our customer.
Will I be charged every time an end user connects to his bank through the Widget?
If no import commands are submitted during a Kontomatik session or 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.
We only charge for sessions where all import commands have executed successfully.
Can I have access to bank accounts maintained by Kontomatik for testing purposes?
Unfortunately no. Test accounts are a limited resource of critical importance for the company, entrusted to us by close collaborators and friends. For security and confidentiality reasons, we cannot share access with outside parties. Please note however that you can freely use our sandbox for testing purposes with either real or mock login credentials.
Kontomatik is securely hosted in our infrastructure so you can focus on your business. We take care of updates, security and reliability. This is a recommended option selected by most of our clients.
Kontomatik API can be hosted in your own infrastructure. Kontomatik API has few dependencies and is very lightweight on resource usage.
- Any modern Linux distribution
- Oracle Java 1.8.0_144+
- PostgreSQL 9.6.5
Please note that webapp server is not necessary. The application embeds its own webapp server to ease deployment.
Kontomatik requires a minimum of 1 dedicated server (physical or virtualized).
For HA setup, we suggest 4 servers (2 x webapp + 2 x db) in a sticky-session setup.
The above are requirements for financial data import service (Kontomatik API).
This does not include the Kontomatik SignIn Widget, a front-end piece to facilitate login.
With on-premises hosting you should be aware of several things:
- You are responsible for the security of your own infrastructure.
- You must be prepared to apply Kontomatik updates often (we suggest automating it).
- You must be prepared to update Kontomatik dependencies once in a while (Java version, Web app server version, PostgreSQL version, etc).
- Kontomatik SignIn Widget is an independent piece of software (on top of Kontomatik API) which is not part of the on-premises solution. You may want to develop your own front-end for the login process.
Reporting vulnerabilities (responsible disclosure)
Please kindly report any vulnerabilities to firstname.lastname@example.org. You can PGP-encrypt communication with Kontomatik public key available at https://keybase.io/kontomatik. We promise to credit you on this website for confirmed vulnerabilities.
Kontomatik servers store very little data. Bank passwords are never stored and financial data is removed ASAP.
Organizational security breakdown
Our services are hosted in Poland, Warsaw at Atman Data Center, one of the largest DCs in Poland. The Atman Data Center is ISO/IEC 27001:2013 certified.
Kontomatik undergone external security audit successfully concluded in June 2016 by LogicalTrust. The scope covered our core services - the API and the widget.
A minimal number of persons have access to Kontomatik production servers and network.
Source code must pass a code review before going live.
All our programmers work on-site. We do not outsource software development.
Technical security breakdown
Bank credentials will never pass through your servers. Kontomatik SignIn Widget encapsulates the login process end to end, so you can sleep well.
No bank credentials are ever stored in a persistent storage on Kontomatik servers (not stored in db, not written to logs, etc). Bank credentials are only stored in a volatile memory (RAM) and are discarded soon after usage.
Financial data is removed from Kontomatik servers in a 24-hour moving window. API clients can force data removal at any time.
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 either high-grade HTTPS (by default) or VPN (if requested).
Two-factor authentication is used: API key and IP whitelist. As this is a read-only API (no money-moving etc.), we consider reply-attacks a low-risk threat and consciously do not require request signing. This makes your integration much easier while still providing very good security.