Introduction

Overview

Kontomatik is a read-only API to banks.
Kontomatik is able to import personal data, account balances and full statements from any supported bank into your system.
To do that, Kontomatik API will need end-user bank credentials (most often a bank login and password).
To ask the end user for his bank credentials, we offer a widget that you can embed on your website, as an iframe.

Kontomatik Demo

Kontomatik Demo is example Kontomatik deployment.
See how things can work for your end users.
Kontomatik Demo allows for real data import to prove our technology worldwide.

While using the demo, don’t forget that Kontomatik is just an API, plus a small widget. You need to build your web app or mobile app on top of it. The frontend look-and-feel is entirely up to you.

Permissionless innovation

Under the hood, Kontomatik uses screen-scraping to mimic a human using his web browser.
By using the very same protocol as a web browser, Kontomatik can potentially support any online bank worldwide.

Glossary

Word

Description

Command

Provides interaction with a remote online transaction system.

Session

Context for all commands that interact with a remote online transaction system.

Sign-in widget

Embeddable iframe providing a convenient and secure way of authenticating into a remote transaction system. The end user can select the target from a long (and constantly-growing) list of banks. Once the end user has successfully logged in, you can use Kontomatik API server-side to import data.

Target

Online transaction system (internet banking platform). In the future, the API will likely support non-banking institutions, so please prefer the more general term ‘target’, instead of 'bank’, in your implementation.

Get API access

Authentication

Kontomatik API is protected by two-factor authentication:

API key is a shared secret you are supposed to keep safe. You need to pass the secret key in all your requests to the service. The recommended way is to pass the API key as the value of a header named X-Api-Key. We strongly encourage you to use this option. You can also pass the key as an HTTP param encoded in the URL, however this is less secure.

IP address is the source IP of your requests. It will be your production server public IP. You can whitelist multiple IP addresses for your convenience. For the test API we will whitelist a wildcard * IP address to make it easier for your developers.

You can always request a new API key and retire an old one. In fact it is highly recommended to rotate your API keys every couple of months. This can be done gracefully as we support multiple API keys per account.

Test environment

Use the test environment for testing and development.

The test environment is fully-featured and unrestricted, including real data import.

Production environment

Kontomatik is also offered in the on-premises model. Contact our Sales team to get the best offer for your individual use case.

Switching to the production environment

Clients migrating to the production environment often report receiving a 404 'InvalidSessionId’ error.
This is a common mistake. You are calling the production API endpoint with a session generated for your test client id.

Before using the API in production mode, please double-check that you have replaced:

test client id with PRODUCTION CLIENT ID - in the frontend

test api key with PRODUCTION API KEY - in the backend

Another thing that triggers a 404 error is a non-whitelisted IP, which prompts the server to respond with 'We don’t know who you are…’.
Please use a whitelisted IP or request your IP to be whitelisted at [email protected].

SignIn Widget

Overview

Kontomatik SignIn Widget takes end-to-end care of the bank selection and login process, at the end providing you with an authenticated session so you can focus on reading the data.

Embedding the widget

// index.jsembedKontomatik({client:'YOUR_CLIENT_ID',// replace it with your assigned client iddivId:'kontomatik',// must match the div element idonSuccess:function(target,sessionId,sessionIdSignature,options){// End-user successfully signed in to the bank// Pass target, sessionId and sessionIdSignature to your backendalert('It works!');}});

To embed the widget on your web page:

Reference the widget’s JavaScript library

Add an empty <div id="kontomatik" /> element, where you want your widget to be rendered

Pre-selects the bank. If omitted, the bank drop down list will be shown. Accepted values: check target name attribute in Catalog command response.

ownerExternalId

null

Your own arbitrary identifier of the end user. For a lender, this might be your loan application id. If you are a bank, a credit application id might be appropriate. If you are a PFM vendor, this could be your end-user database id. Passing this param is highly recommended. It allows you to group all imported data and fetch them together, even if they span across multiple Kontomatik sessions.

showFavicons

false

Set to true to show banks’ favicons in a drop down list. Makes it easier for the end user to find a bank. Also it looks more appealing and professional. This is off by default because using bank logotypes can be a grey area in some jurisdictions.

showScreenshots

true

By default, screenshot of bank’s login page is displayed. Set the value to false if you do not wish the widget to display screenshots.

showBetaQualityLabels

true/false

Option to toggle the visibility of beta quality labels for beta quality targets. Please note the default is true on the test environment and false on production. This is an exception that breaks the symmetry between test and production.

showTargetMissingOption

true

By default, “My bank is not listed…” option is displayed on the bank selection list. Set the value to false if you do not want this option to show up on the list.

showTargetMissingForm

true

Option to control whether the user who clicked on “My bank is not listed…” option is then redirected to a form prompting the user to enter the name and url address of the unsupported bank. Passing false enables you to handle this scenario however you prefer.

showDefaultTarget

true

The widget displays a bank with a large market share as the default value of the bank selection list. If instead of a default target you prefer to display the message Select from list, set showDefaultTarget to false.

dynamicHeight

false

If set to true, the <iframe> height will change based on the content of the element. This feature is currently in beta state.

styles

null

Optional object defining the look and feel of the widget. For more information please refer to styling the widget section.

PSD2 params (beta version, might change in the nearest future)

// index.jsembedKontomatik({//client: 'YOUR_CLIENT_ID', divId: 'kontomatik', // must match the div element idonSuccess:function(target,sessionId,sessionIdSignature,options){alert('It works!');// End-user successfully signed in to the bank}psd2:{multipleImport:false,// set to true to enable multiple imports in the background polishAPISpecific:{accountNumbers:['PL32114020040000320250132522'],// the end-user won't be asked to choose accountstransactionsStatus:['DONE'],// we will fetch all transactions defined by this dictionary valuesince:2019-02-01,// // fill only if you hold an AISP license and need to adjust this valueconsentTimeLimit:'PT1H'// fill only if you hold an AISP license and need to adjust this value}}});

The embedKontomatik() function takes an additional (optional) parameter psd2 which contains an object with properties specific to PSD2 Open Banking API:

Parameter

Default

Description

multipleImport

false

(beta) A flag enabling multiple imports up to 4 times per day, throughout 90 days, in the background. Requires additional backend integration.

polishAPISpecific

null

Object containing fields specific to PolishAPI standard. Read further for more information.

In Poland it is possible to limit the scope of an import by passing the list of account numbers to the Widget. The end-user will have to grant the consents only for those particular accounts. This value is also required for multiple import when the consent has expired and you do not want to ask the user to choose accounts again. This parameter takes the array of account numbers. The account numbers are formatted in accordance with ISO 13616.

transactionsStatus

['DONE’]

It is possible to specify one or multiple dictionary values: ALL, DONE, PENDING, REJECTED, CANCELLED, SCHEDULED, HOLD. Each value limits the scope of imported transactions. If more than one value is passed then the logical OR is applied.

since

null

(beta) Date of the oldest transaction to fetch, in YYYY-MM-DD format. Important notice: this value doesn’t define the final since date, final since date is passed when issuing the actual data import command and can’t be earlier than this one. This parameter is especially usefull for multiple import, where the overall consent is granted for a longer time than consecutive imports. This field is to be used only by AIS entities.

consentTimeLimit

60min/90days single/multiple import

(beta) Consent validity period. Format: ISO 8601 duration format (e.g. PT1H - 1 hour). This field is to be used only by AIS entities.

Callbacks

Signin Widget provides a set of several callbacks, which are invoked when widget enters a new state or an important event takes place.
It should be emphasized, that you only need to implement the onSuccess callback.

(beta) An identifier of the multiple import, used to extract sessionId for consecutive imports without the end-user login (in the background). multipleImport flag in the Widget has to be set to true for this parameter to be generated.

At the very least you should pass the sessionId and sessionIdSignature parameters to your backend application, which will use them later on to call Kontomatik API.

For approved clients only, the widget will prompt for a full password even though only selected characters from the credential are needed to log into the bank. This feature is required by PFM applications to store end-user credentials in the browser’s local storage. Please see our FAQ for a detailed description of acceptable use cases.

The options object contains the following properties:

Property

Available

Description

endUserFingerprint

always

the value can be used to identify the end user in order to decide whether to continue or abandon Kontomatik session

credentials

restricted

an array of objects with three properties: kind, value and unmasked. kind is an identifier for the credential type provided by the end user. value contains the credential as it was sent by the widget to the online system. unmasked contains the full credential as it was entered by the end user.

officialName

always

the full bank name

Note: By default, the options object will never contain a credentials array. You must specifically ask for this feature to be enabled.

onError callback

The onError callback is called when the user fails to sign into the bank (i.e. the user provided invalid credentials, the bank transactions system is offline). It will be passed the following parameters:

Parameter

Description

exception

indicates what went wrong during the attempt to sign in. For more details please refer to error handling.

Please note that you do not have to implement this. The widget handles error paths gracefully. This only serves informational purposes and should not affect your UI flow.

onUnsupportedTarget callback

In case when the user’s bank is not listed, the user can select “My bank is not listed…” option on the dropdown list.
The user is then redirected to a form, where he or she is prompted to enter the name and the url address of the missing bank.
Regardless whether the user enters any text, the onUnsupportedTarget callback is fired. It will be passed an object with the following properties:

Property

Description

target

the name of the bank the user has entered

country

location of the requested bank

address

the url address of the bank’s login page

onInitialized callback

The onInitialized callback is called when the widget is ready for user interaction, that is a fully initialized bank select list is shown.
The callback could be useful in case you decide to show your own spinner until the widget is initialized.

Note: the callback will be fired only once in widget’s lifecycle.

onStarted callback

In contrast to onInitialized callback, the onStarted callback is called each time a bank selection list is shown to the end user.

onTargetSelected callback

The onTargetSelected callback is called when the user selected a bank and clicked the “next” button.
The callback will be passed an object with the following properties:

Property

Description

name

an identifier of the bank the end user has selected

officialName

the full bank name

onCredentialEntered callback

The onCredentialEntered callback is called when user entered credential and clicked the “next” button.

CSS styling the widget

embedKontomatik({/*
... (see Embedding the widget for the full reference) ...
*/styles:{bodyBgColor:'#20252b',textColor:'#ebebeb',borderRadius:'10px',btnBgColor:'#4e5d6c',btnBorderColor:'transparent',btnTextColor:'#fff',btnPrimaryBgColor:'#e76d3b',btnPrimaryBorderColor:'transparent',btnPrimaryTextColor:'#fff',inputBgColor:'#4e5d6c',inputBorderColor:'transparent',inputBorderFocusColor:'#2c97de',inputTextColor:'#fff',inputDisabledTextColor:'#b4bcc2',alertErrorBgColor:'#d9534f',alertErrorBorderColor:'transparent',alertErrorTextColor:'#fff',menuHighlightBgColor:'#2c3e50'}});

Beta quality. The styling API may slightly change. Please report any issues to [email protected].
Most of our clients stick with the default look-and-feel. This is the safest and recommended choice.
The default look-and-feel is well tested and well recognized by end users.
It is also quite neutral and should fit most designs.

the first three keys control the background, border and text color of all inputs and dropdown lists. The inputDisabledTextColor key controls the text color of disabled element. The last key - inputBorderFocusColor - controls the border color of an input that has focus

menuHighlightBgColor

controls the background color of a menu item the mouse pointer is over

textColor

text color

The color values use a subset of standard CSS color definitions, you can use both the hexadecimal (#123456) as well as the standard RGB (rgb(12, 34, 56)) notations.

Additionally, you can also use transparent and inherit keywords. However the RGBA, HSL and HSLA notations are not supported. You cannot use predefined HTML and CSS color names.

The properties which take length values accept standard CSS length units like px, em and so on.

Best practices

For the end user the task of submitting bank credentials on your non-bank website can be a surprising and tricky task.

We must aim to make this process as pleasant and smooth as possible.

To maximize the conversion rate we highly recommend adhering to the following guidelines:

Provide extensive description

Explain to the end user that he is expected to provide his real bank credentials, typically a login and a password.

Explain why using the widget is safe, as some end users may have concerns about the need to provide bank credentials. You should strongly emphasize that under no circumstances users’ credentials are stored.

Make the widget a separate step in the application process

We strongly recommend to make the widget an individual and completely separate step in the loan application process:

Using the widget requires the end user’s ultimate focus:

the end user is expected to carefully read accompanying instructions

the end user must take extra care when entering credentials, especially when he or she does not use online banking on a regular basis

Using the widget might be a time-consuming task, as in most cases this would be the first time the end user has ever used such a tool.

Some of our clients use Kontomatik as the only or the primary scenario in their loan application processes.

It will unify loan application processing for all end users

It will put less stress on your IT resources, as there would be less support needed

Of course, details vary between markets and it is not always realistic to expect all users to go through Kontomatik.

Give users something to do while background import takes place

Design the loan application form so that the Kontomatik Sign-In widget is one of the intermediary steps.
The import process takes a short while to complete, so the end user might just as well continue filling out the rest of the application form.

Use gzip encoding in your HTTP requests to download data faster

In your HTTP client library add the Accept-Encoding header for all HTTP requests:

Accept-Encoding: gzip

PSD2 flow on native mobile apps

Kontomatik access to banking data may be based on the OAuth standard. In such cases, after the target is selected in the Widget, the end user is redirected to a web page on the bank’s domain for authentication.

In order 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.

Basic API

Tutorial

We recommend to get API access for this section, if you haven’t done so already.

The first step is to embed the SignIn Widget on your website.
Kontomatik SignIn widget takes care of asking the end user for his bank credentials
and logging into the bank on his behalf.

The following steps depict a common scenario to download all essential data.

End user visits your website and arrives to the step involving Kontomatik.

End user successfully logs into the selected internet banking using Kontomatik Sign-in widget.
The Widget will then provide you with the sessionId, sessionIdSignature, target and options parameters via JavaScript callback.
You will need both the sessionId and sessionIdSignature parameters to execute commands server-side.

Pass all received parameters to your backend application.
All remaining steps of this tutorial are performed server-side.

Execute default-import command. You will get command id in reply.
The command is asynchronous. It imports all essential personal and financial data.
Depending on the target and its present load, it takes anywhere from a few seconds to several minutes.
Our global median is 12 seconds.

At regular intervals poll the status of the default-import command (every ~1 second or so).
Once the command’s status changes to successful, the reply will also contain all data.

Initiates the default data import flow. Use it to get started quickly. This command will import all essential data with one API call.

This will get you:

account owner(s) personal data for KYC check

bank accounts listing with balances and account numbers

the full statements for the requested period

The command is asynchronous. It returns command id. Use this call to poll for command status and to fetch results once the command is done.

Important. Do not set a timeout for the polling loop. Be prepared to wait for several minutes until Kontomatik fetches all the transaction history you requested.
If you quit polling, you abandon the results and you pay for data you never received.
If you must set a timeout, then use an ownerExternalId parameter to retrieve the data later on.

Important. After the default-import command successfully completes, the user is automatically signed out of the bank’s transaction system and the session is closed.
You cannot use a closed session to execute additional commands.

HTTP Request

POST /v1/command/default-import.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

sessionId

obligatory

Session identifier.

sessionIdSignature

obligatory

Signature preventing session id enumeration by attacker.

since

obligatory

Start date in YYYY-MM-DD format. Only transactions that occurred on or after the since date will be imported.

Data returned

Command execution can take anywhere from several seconds to several minutes, with 12s being our global median. You will learn when it’s done by polling for the command status.

Once the command status turns to successful the <result> element will be present containing all imported data.

See on the right pane how the data structure looks like. You will get <owners>, <accounts>, and <moneyTransactions> all together.

For a detailed description of all XML elements see the documentation of the relevant commands in the advanced API.

Default import flow VS custom import flow

The primitive commands allow you to independently import owners and/or accounts and/or transactions on the selected accounts. You can build your custom-tailored import flow. In fact, the default-import is simply a macro-command implemented on top of other commands.

One day we may decide to change the default-import command to better fit common usage pattern among our customers.
This will be probably data extension (not removal) but if you need full control and flexibility simply call primitive commands instead.

a bug in Kontomatik software. If you use our hosted service we will learn about all fatal errors automatically. If you host Kontomatik on your servers you should report all fatals to us, including the full reply content.

successful, canceled, error and fatal are final command states. The client must quit polling when the command is in a final state. The result will be available for 60 seconds, after which Kontomatik will return an InvalidCommandId error.

Error handling

We can divide possible errors into four categories:

Caused by external factors (bank offline, network issues, etc)

Caused by bad API integration (incorrect API calls)

Caused by bugs in Kontomatik (unexpected corner cases we must fix)

Caused by the end user (entered invalid password, etc)

Errors caused by external factors

Command execution may fail due to causes beyond our control.
Temporary unavailability of the bank and expired sessions are just two examples of what can go wrong.

Exception

Description

IOException

Network issue between Kontomatik and bank occurred. For example the bank failed to respond in a timely manner. What to do: retry command that failed up to 3 times, then give up and ask user to try again later.

SessionExpired

The session with the online transaction system has expired. What to do: ask the user to try again (show the widget step) and to not use the bank manually at the same time as parallel sessions can kill each other.

ConcurrentSessionsLimitExceed

User has not signed out and second session cannot be started until the abandoned one expires. What to do: ask the user to try again (show the widget step) in a few hours.

ServiceTemporarilyUnavailable

Online transaction system is temporarily unavailable. What to do: ask the user to try again in a few minutes because his online banking is temporarily unavailable.

ServiceMaintenance

Online transaction system under maintenance. What to do: ask the user to try again in a few hours because his online banking is undergoing planned maintenance.

API integration errors

If you get one of these errors you should review your API client code for integration issues.
These errors can be caused by numerous factors, like passing invalid params or failure to pass all required params.

Exception

Description

CommandNotAvailable

The command is not available for the selected target

InvalidCommandId

Invalid command identifier (e.g. if client keeps polling a command that entered in a final state, after 60 seconds we return InvalidCommandId)

InvalidOwnerExternalId

Invalid identifier of the data owner

NotSignedIn

Only signed-in user can call the command

AlreadySignedIn

You cannot sign-in twice in the same session - start a new session

InvalidIban

Invalid bank account number (e.g. empty, incorrect syntax)

InvalidTarget

Invalid target identifier

InvalidSessionId

Invalid session identifier (e.g. client calls the production endpoint with a session created on the test environment)

InvalidSessionIdSignature

One or both of sessionId and sessionIdSignature passed parameters were malformed

InvalidSince

Invalid start date

JobsQuotaExceeded

Your app has started too many imports simultaneously. What to do: wait for 10-15 seconds to allow some of the imports to finish and resubmit the command. If you get the same error, repeat the process until the command is accepted.

Bugs in Kontomatik

The following should be considered bugs in the Kontomatik Service. Most likely, some edge case condition occured and our software was not prepared for this. Kontomatik should be improved to cover this case. You may want to excuse your user and redirect him to the other path.

In case of a SaaS deployment we will be automatically notified so you don’t have to take any action. In case of self-hosting these errors should be reported to [email protected], attaching the XML reply and logs of the application server.

There are two scenarios to consider:

HTTP response status code >= 500

As with any HTTP service, it is a good practice to properly handle occasional server hard fails like '500 Internal Server Error’ or '503 Service Unavailable’.

Unexpected async command failure

Please note that the HTTP response status code will be still '200 OK’ because your query for the command status worked fine. It is only the asynchronous command that failed earlier.

Exception

Description

KontoXBug

Unhandled condition occured. What to do: in a SaaS deployment you don’t have to do anything. We get notified and you can expect the bug will be resolved in a timely manner. In on-premises deployments you should send us the whole XML response.

Why KontoXBug and not KontomatikBug? This is because we rebranded from 'KontoX’ to 'Kontomatik’ but have to maintain backwards compatibility.

Errors caused by the end user

These errors are a “fault” of the end user. The SignIn Widget will handle it by kindly asking the user to resolve the issue and try again. You do not have to do anything.

These errors are entirely handled by the SignIn Widget. This is only relevant if you are not using the widget in your legacy integration.

Exception

Description

AccessBlocked

Access to the account is blocked. What to do: ask the user to call his bank and unblock his online access.

AccessTemporarilyBlocked

Access to the account is temporarily blocked and expected to auto-unlock. What to do: ask the user to try again in a few hours.

ManualActionRequired

A manual action in the online transaction system is required (e.g. accepting changes in terms of use). What to do: ask the user to manually log into the bank and take care of all pop-ups, new terms of use etc.

InvalidCredentials

End user entered invalid credential. What to do: let the user try again entering credentials.

TargetCredentialsMismatch

End user entered credentials that match a different, possibly unsupported, transactional system. For example company credentials are used instead of individual account credentials.

UnsupportedLoginMethod

This login scenario is not supported. What to do: ask the user to login in a more standard way.

UnsupportedLanguage

The language of the bank UI is not supported. What to do: ask the user to change the bank online UI locale to the default one.

InsufficientIdentificationLevel

The user has opened the account anonymously from his mobile phone and because of this, identification data is missing or cannot be validated. This error can only occur for the target Webmoney_ru.

User successfully logs into the selected internet banking using Kontomatik Sign-in Widget.
The Widget will provide you with the sessionId, sessionIdSignature, target and options parameters via JavaScript callback.
You will need both the sessionId and sessionIdSignature parameters to execute commands server-side.

Pass all received parameters to your backend application.
It is assumed that the remaining steps of this tutorial are performed server-side.

Execute import-owners command. You will get commandId in reply.
The command is asynchronous and it fetches personal data of the account owner(s).
Depending on the target and its present load, it takes about 0.5 - 10s.

At regular intervals poll the status of the command.
Once the command’s status changes to successful, the reply will also contain the data.

Execute import-accounts command. You will get commandId in reply.
The command is asynchronous and it fetches user’s bank accounts.
Please note only accounts are fetched without any transactions.
Depending on the target and its present load, it takes about 0.5 - 15s.

At regular intervals poll the status of the command.
Once the command’s status changes to successful, the reply will also contain a list of imported accounts.

For each account imported in previous step:

Execute import-account-transactions command parameterized with the account number (iban) and start date (since) to initiate transactions import. You will get a commandId in reply. The command is asynchronous. It usually takes anywhere from a few seconds to up to several minutes in the worst case scenario.

At regular intervals poll the status of the import-account-transactions command.
Once the command’s status changes to successful, the reply will also contain a list of imported transactions for the given account.

Optionallyfetch all data for the specified end user. While each command returns its data as soon as it finishes, it may be handy for you to fetch all data together in one XML at the end of the session or to aggregate several sessions of a single user. Pass your ownerExternalId to select the right end user.

Optionallyfetch aggregated values for the specified end user. This allows you to learn about the number and sum of incomes and spendings, among other things. Pass it your ownerExternalId and periodMonths.

Optionallylog out from the online transaction system if a given target supports sign-out.xml command.

Provide feedback to the end user regarding successful completion of the import process.

As a rule, commands can be executed in any order you prefer, with one small gotcha: if you try to import transactions for an account while passing an ownerExternalId parameter, it is absolutely necessary to execute import-accounts first, otherwise the command will fail.

Returns a list of supported banks and a list of available commands for each bank.

Both of the supported banks and available commands lists are dynamical, so it is recommended not to hard-code them into the implementation of the client to Kontomatik.
The client should request the catalog whenever a list of banks or commands is needed.

HTTP Request

GET /v1/command-catalog.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

country

pl

Filters banks by the country they operate in. The parameter is case insensitive and uses two letter country codes as defined by the ISO 3166-1 standard. The default value is pl; to display banks available in all supported countries use all value for the parameter.

favicons

false

Controls whether the catalog should return banks’ favicons. If you are using Kontomatik Sign-in Widget then it is strongly recommended not to use this feature in order to save on bandwith.

Data returned

Description of <target> element:

Attribute

Description

name

an internal identifier for the bank

officialName

full bank name

Description of <command> element:

Attribute

Description

name

holds command’s formal name; by searching the catalog you can check if the given functionality (e.g. owners’ details import) is available for a given bank

The <favicon> element is displayed only if the favicons parameter was set to true.
The tag holds base64 encoded bytes of the bank’s favicon. The imageFormat attribute indicates the image format of the favicon.

Initiates import of a bank account’s owners and co-owners.
The command aims to return all possible details about every owner.
In contrast to the import-accounts this command takes data from the global settings/profile rather than from the individual sub-accounts.

The command is asynchronous and it returns command id. Use this call to poll for command status and to fetch results once the command is done.

HTTP Request

POST /v1/command/import-owners.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

sessionId

obligatory

Session identifier.

sessionIdSignature

obligatory

Security parameter to prevent session enumeration.

Data returned

Once the command status turns to successful the <result> element will be present containing a list of owners.

See on the right pane how the data structure looks like.

TODO: add missing attributes we support

Data

Availability

Description

kind

guaranteed

one of: “OWNER”, “CO_OWNER, "COMPANY”

name

guaranteed

name (name and surname or company’s name)

address

possibly none

address of the owner, as presented by bank; if multiple addresses are found (such as permanent address and contact address) the field will contain all of them, in a comma-separated list

The command is asynchronous and it returns command id. Use this call to poll for command status and to fetch results once the command is done.

HTTP Request

POST /v1/command/import-accounts.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

sessionId

obligatory

Session identifier.

sessionIdSignature

obligatory

Security parameter to prevent session enumeration.

fast

true

Pass false to get a richer data set in some banks. In slow mode you are much more likely to get additional details such as the owner’s address and opening dates of the user’s accounts. Slow mode decreases execution speed but the time overhead is reasonable. Use fast mode only if execution speed is critical for you.

Data returned

Once the command status turns to successful the <result> element will be present containing a list of accounts.

See on the right pane how the data structure looks like.

Data

Availability

Description

name

guaranteed

official account name, as shown in the bank’s transaction system

friendlyName

possibly none

a name assigned by the user for this account

iban

guaranteed

full account number (with country code for 'true’ IBAN accounts)

currencyBalance

guaranteed

current account balance in an account’s currency (it can be different than the currency of the country in which the bank is located in)

currencyFundsAvailable

available except for exceptional circumstances

equals to the balance being at user’s immediate disposal (it can be different than the currency of the country in which the bank is located in). Can be lower than currencyBalance field.

currencyName

guaranteed

currency symbol, e.g. “PLN”

owner

available except for exceptional circumstances

name of the owner or owners of the account as supplied by the bank system. The information can be scraped either from account details or from outgoing transfers. The field is filled in more than 99% cases. In rare circumstances it can be empty, e.g. all of the following conditions are satisfied: the bank does not present owner in the account details or profile/settings and there were no outgoing transactions found.

activeSinceAtLeast

available except for exceptional circumstances

the date when the account was opened or the date of the oldest transaction found (but not older than a year if searching for older transactions would substantially affect the execution time of the command

directDebit

possibly none

marks whether the account supports direct debit or not, using a true or false value for the available attribute. Direct debit accounts can be safely selected by lenders as the destination account for the loan transfer, while non direct debit accounts are tipically savings accounts that do not accept direct transfers. If there is not enough data to resolve this field, the tag will not be present.

Initiates import of transactions for the selected bank account and period.

The command is asynchronous and returns command id. Use this call to poll for command status and to fetch results once the command is done.

HTTP Request

POST /v1/command/import-account-transactions.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

sessionId

obligatory

Session identifier.

sessionIdSignature

obligatory

Security parameter to prevent session enumeration.

iban

obligatory

Full account number of the account for which the list of transactions should be fetched. Preferably, use the iban value returned by the import-accounts command.

since

obligatory

Start date in YYYY-MM-DD format. Only transactions that occurred on or after the since date will be imported.

Data returned

Once the command status turns to successful the <result> element will be present containing a list of transactions.

See on the right pane how the data structure looks like.

Data

Availability

Description

transactionOn

guaranteed

actual transaction date

bookedOn

guaranteed

transaction’s booking date (sometimes even 10 days after the transactionOn). In exceptional circumstances, transaction date or value date will be assigned to this attribute

currencyAmount

guaranteed

transaction amount expressed in account’s currency (it can be different than the currency of the country in which the bank is located). The currencyAmount is negative for debit transactions (outgoing amount) and positive for credit transactions (incoming amount).

currencyBalance

possibly none

account balance expressed in account’s currency

partyIban

guaranteed for transactions with a non-empty party attribute

full account number of the other party of the transaction. The field is always available for transfers between accounts. For some transactions (i.e. payments by debit/credit card, bank fees and commissions) the account number is unavailable.

party

possibly none

the name of the other party of the transaction is always available. For some transactions (i.e. contra-entry type transactions) the name of the other party is unavailable.

title

possibly none

transaction title

kind

possibly none

transaction type, as presented in the online transaction system (e.g. “INTEREST COMPOUNDING”)

status

possibly none

(beta) transaction status, can take one of the following values DONE, PENDING, REJECTED, CANCELLED, SCHEDULED, HOLD

Extra data

The <moneyTransaction> element may be extended in some cases with additional tags.
The extra tags may contain PSD2-related information, country-specific parameters or any other details which are not a part of the standard response.

The ImportAccountTransactions command execution time cannot exceed 10 minutes. If the import fails to complete during this time, the scraping process is terminated and a “successful” response with a partial list of transactions is returned. The result will contain a “partialDueToTimeout” attribute with a value of “true”.

Import Credit Cards (command)

POST /v1/command/import-credit-cards.xml

Initiates import of credit cards’ details. The command is synchronous and returns the command id. Use this call to poll for command status and to fetch results once the command is done.

card number, as presented in the bank’s system. Vast majority of the banks present credit card number with most significant digits replaced with asterisks, just a few banks present unmasked credit card number. Use this number when importing money transactions associated with the given credit card.

currencyBalance

guaranteed

current credit card balance in card’s currency (it can be different than the currency of the country which the bank is located in)

currencyFundsAvailable

possibly none

the amount of available credit in card’s currency (it can be different than the currency of the country which the bank is located in)

currencyName

guaranteed

currency symbol, e.g. “PLN”

owner

possibly none

name of the credit card holder, as presented in the online transaction system

Initiates import of money transactions associated with a given credit card. The command is synchronous and returns the command id. Use this call to poll for command status and to fetch results once the command is done.

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

sessionId

obligatory

Session identifier.

sessionIdSignature

obligatory

Security parameter to prevent session enumeration.

since

obligatory

start date in YYYY-MM-DD format, only transactions that occurred on or after the since date will be imported

cardNumber

obligatory

identifies the credit card for which the transactions should be fetched. Preferably, use the number value returned by the import-credit-cards command. If the full number is unavailable, you can pass asterisks in place of the missing digits. Please see the pattern-matching description for details.

Data

Availability

Description

transactionOn

guaranteed

transaction date; in some cases the attribute will be assigned with another date, e.g. currency date

bookedOn

guaranteed

transaction’s booking date (sometimes even 10 days after the transactionOn); in some cases this field will be assigned with currency date or transaction date if booking date is missing

currencyAmount

guaranteed

transaction amount in an card’s currency (it can be different than the currency of the country which the bank is located in)

title

possibly none

transaction title

party

possibly none

the name of the other party of the transaction

partyIban

possibly none

full account number of other party of the transaction

kind

possibly none

type of transaction, just as it is presented in the online transaction system (e.g. “INTEREST COMPOUNDING”)

every digit can be replaced with an asterisk, which causes globing (wildcard)

if many cards fit the pattern, transactions associated with the first matched card will be returned

The command’s execution time is limited to 10 minutes. If the import fails to complete during this time, the scraping process is terminated and a “successful” response with a partial list of transactions is returned. The result will then contain “partialDueToTimeout” attribute set to true.
Credit card import commands are only available in Poland and Spain.

Synchronous command that logs out of the bank’s transaction system.
Given that the bank supports the sign out command, it is advised to log out of the bank’s transaction system once you have imported all data to prevent blocking of the system for the end user.

HTTP Request

POST /v1/command/sign-out.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

sessionId

obligatory

Session identifier.

sessionIdSignature

obligatory

Security parameter to prevent session enumeration.

HTTP Response

An empty xml is returned - please see in the right pane what the response looks like.

Cancels command execution.
The command is asynchronous.
If the command is in the in_progress state, it will be cancelled before making another request (still, the current request has to end).
A cancelled command cannot be resumed.

Cancelling is useful if it is necessary to provide the user with the ability to stop an action.
When a command is cancelled the working thread is released back into the pool, optimizing resource usage.

After cancelling a command it is recommended to create a new session, if the import from a given target is to be continued.
Cancelling a command can leave the http agent’s library in an inconsistent state, causing errors while executing other commands within the same session.

HTTP Request

Parameters

Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in Widget.

only

optional

Filters the results returned by the data type. You can pass one of the following values: owners, accounts, transactions.

Data returned

Each <target> tag contains all data imported for the end user from a given bank.
A sample response is provided on the right pane.
If you closely examined the structure of the xml then you probably had noticed that the <target> encapsulates the data structures returned by import accounts and owner details commands.
Furthermore, the <account> tag contains a list of transactions associated with the given account.

For a detailed description of data structures encapsulated by the <owners>, <accounts> and <moneyTransactions> tags, please consult the descriptions of the related commands.

The aggregated data command does not import anything, it just merges data already fetched by primitive commands such as import-accounts or import-transactions. Its result will be dependent on the final status of the associated sub-commands, which may successfully complete or fail with an exception. That means you need to wait for the primitive import commands to complete execution and log or handle possible exceptions, before requesting the aggregated data result.

Kontomatik is not a credit bureau and does not offer credit scoring. While leveraging Kontomatik’s financial behavior analysis may be very helpful, you are still responsible for your scoring model and related risk.

Kontomatik offers a number of high-level scores assessing financial behavior of the loan applicant. Those scores proved to be highly predictive in our cross validation benchmarks.

The primary score (<score>) is a numerical value estimating on a 0..1 scale the creditworthiness of an individual - the higher the better. The score is inversely correlated with the probability of default.

The percentile score (<scorePercentile>) estimates the percentile of population the lendee is better than - the higher the better.

The (lender-specific) tier score (<scoreTier>) estimates the client’s rank according to a particular ranking system agreed upon with the lender, e.g. 'ABCDEF’, '1234’, 'Bronze Silver Gold’ etc.

Kontomatik offers:

common scores - available immediately, trained on generic dataset, not specific to any lender, recommended as a starting point

lender-specific scores - developed in cooperation with the lender, based on lender-specific historical repayment data

Usage

Scores are calculated based on bank accounts and transactions already imported within the scope of specific ownerExternalId.

For that reason it is essential to wait for import commands to finish before requesting the score, otherwise the algorithm will work on partial data and produce unreliable results.

HTTP Request

GET /v1/owner-scores.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

ownerExternalId

obligatory

Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in widget.

Data returned

Critical:

Pick specific <model> by id. The response will likely contain multiple models - typically the common one and the lender-tailored one. You are free to use any of them but it is critical to do it consciously and to not mix the results. Do not rely on models order. The order is randomized to avoid coupling.

Within selected model pick specific a specific score by XML element name. Do not rely on scores order.

In machine learning a feature is an individual measurable property or characteristic of a phenomenon being observed.

In context of lending features reflect financial behavior of the loan applicant.

Features offered by Kontomatik proved to be highly predictive in our cross validation benchmarks.

Predictive power can be further improved by re-training the model on the lender-specific historical repayment data.

HTTP Request

GET /v1/owner-features.xml

Parameters

Parameter

Default

Description

apiKey

optional

API key. (Better to use X-Api-Key header)

ownerExternalId

obligatory

Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in widget.

Data returned

It is critical to pick specific <model> by id.

Model id stabilizes feature semantics. The same set of features will be present and feature semantics won’t change. With the new model (new id) everything is reset. Lending company must then re-check which features are predictive. New version of the model will offer a new set of features to pick from. Features present in the old version are not guaranteed to be present in the new version. Typically, new model replaces many features with more powerful alternatives.

Model retrainedAt attribute describes the training dataset. The same model can be re-trained on the new dataset (the larger and more current one). Feature set and semantics stay the same. Lending company does not need to take any action when the model is retrained. The timestamp format is ISO 8601.

Every <feature /> contains the following structure:

Data

Availability

Description

id

guaranteed

Unique identifier of the feature. It is guaranteed to be stable across model retrains (but not across model versions).

value

guaranteed

Decimal value of the feature in range <-∞, +∞> inclusive. Possible values are a number, -INF, INF, NaN (see xs:double). The value is standard deviation from the population. Using standard deviation instead of base units allows for the same treatment of all kinds of units like amounts, counters, or ratios. Standard deviations themselves are also normalized (scaled to the same distribution) across all features so they can be treated consistently.

relevance

guaranteed

Decimal number representing how much the feature influenced the final score of the client; a positive value means that the feature worked in favor of the client repaying, while a negative value means the feature worked in favor of the client defaulting. Only numeric values are possible - NaN or INF are not allowed. Relevance “0” means the feature did not influence the outcome at all.

How to use features in existing scoring model?

Kontomatik publishes hundreds of features that can be potentially predictive in your context (your customers and your scoring model).

You are not expected to understand semantics of individual features published by Kontomatik. Please do not attempt to apply domain expert knowledge to manually assess and combine Kontomatik features into your scoring model.

The correct approach is to test all features on your real world loans using your existing scoring model.

Once predictive and independent features have been identified, apply them to your scoring model along your own input features.

This feature is not included in the standard offer and will be disabled by default on your account. Please contact the Sales for details.
While we aim to make this feature as meaningful as possible, it comes with no warranty of any kind. Use it only as an auxiliary tool on top of your proven practices.

Labels provide additional data about transactions and help put together a comprehensive view of the customer’s financial status.

Using the meta data contained in labels, it is possible to gauge trends and metrics across various dimensions such as revenue, loans, lifestyle, healthcare spending, recurrent money obligations and others.
Identifying complex risk conditions such as gambling or internal transfers between the user’s accounts becomes a matter of simply reading a red flag label.

We developed the feature by consulting with lenders and with a focus on risk assessment. Thus transaction labels are significantly different from categories, which classify transactions from the end user’s perspective.

HTTP Request

If the feature is activated for your account the transactions will simply be labeled. There is no labeling API call.

Labels will be present in the result of any command that returns transactions such as default-import or import-transactions. For optimal results it is best to fetch all of the owner’s data. This way, the full context of the user’s transactions and accounts will be available to the labeling engine.

Data returned

The following table describes the currently supported labels. Please note that we have not deemed it necessary to mark transactions as income or spending. This basic distinction can be made based on the negative or positive value of <currencyAmount>field.

Technical

label

direction

description

internal

both

transactions between person’s own accounts (self-to-self) or within the immediate family (same surname)

monthly

both

transactions that occur monthly around the same date

overdraft

expense

user has withdrawn more money than the account holds

verification

both

transactions which serve to prove user’s identity or account ownership, typically with a very small nominal amount like 1 EUR or 0.01 EUR

State

any kind of social security - money received from the state, private charities and NGOs; income from alimony

500+

income

specific welfare benefit granted in Poland for every next child under 18

tax

both

income tax (PIT), property tax, capital gain tax, interest tax (in Poland: “Belka”), excise, duty, value added tax (VAT), state social insurance (in Poland: ZUS), inheritance tax, and any other form of taxation. Transactions with this label are usually expense transactions, but they could also represent income.

children-related expense and income; toys, accessories and clothes for babies, toddlers and young teenagers, children stores, kindergarten and pre-school payments, primary school books and expenses; does not cover: higher education, university fees, specialised trainings and courses e.g. photography school

HTTP Request

Parameters

Your identifier for the end-user, that you passed as one of the parameters to Kontomatik Sign-in widget.

periodMonths

obligatory

Period in months that the aggregates will be calculated for, including current month.

Data returned

See on the right pane what the data structure looks like.

Each <target> element contains a collection of accounts opened in a given bank (name attribute holds an Kontomatik’s internal code for the bank).
The aggregates are grouped by an account and a month.
The <account> tag contains some basic information about the account (for description of the data please consult the summary of import accounts command).
Each <month> tag encapsulates the following elements:

Data

Availability

Description

daysInMonth

guaranteed

number of days in a given month

withdrawalsCount

guaranteed

total number of withdrawals from the account

withdrawalsTotal

guaranteed

value of all withdrawals from the account

depositsCount

guaranteed

total number of deposits in an account

depositsTotal

guaranteed

value of all deposits in an account

balance

available except for exceptional cases

account balance at the end of month

balanceAverage

available except for exceptional cases

average monthly account balance

positiveBalanceAverage

possibly none

average account balance for days with balance over 0 monetary units

negativeBalanceAverage

possibly none

average account balance for days with balance below 0 monetary units

maxBalance

available except for exceptional cases

maximum daily closing balance in a given month

minBalance

available except for exceptional cases

minimum daily closing balance in a given month

polishZusTransactionsCount

possibly none

total number of transactions from/to Polish Social Insurance Institution (ZUS)

How to

This section addresses the topic of how to customize your import flow or achieve specific goals with Kontomatik.

Programmers who want to learn the about full potential of the API, improve the UX or fine-tune a Kontomatik integration are strongly advised to read further.

Import multiple banks

Kontomatik lends itself perfectly to fetching data from multiple online banking accounts. Let’s assume your end user has many accounts and you would like to import them all.

The flow goes like this:

Generate a unique id for the end user and render it as the value of the ownerExternalId Widget parameter. The ownerExternalId parameter instructs Kontomatik to persist the user’s data under the provided identifier.
If different sessions are created with the same owner id, then the associated import results can be fetched as a single response.

Prompt the end user to sign into a bank, then into the next one and so forth. After each successful login you will receive a sessionId in response.

Call default-import for every sessionId you get. Note that you can initiate a maximum of 8 imports at the same time.

At regular intervals poll the default-import command status using the commandIds.

When all command statuses have turned to successful call Data command passing ownerExternalId parameter that you generated at the beginning.

You’re done!

Fetch auto-imported data visible in Insight

To use Insight, developers just need to enable auto-import flag in the Widget and pass an externalOwnerId parameter to identify the end user. When the user signs into a bank, Kontomatik executes a default-import command automatically and pushes the report to the Insight dashboard application. The report will be visible to any authorised staff in the client organisation.

While this flow provides excellent input for human review, you may also want to download and process data automatically. In such case:

Implement the onSuccess() method in order to be alerted when a user has signed in successfully. Do not call any API command yet!

Allow some time for the automatic default-import to complete, 10 minutes should be enough even for exceptionally large imports.

The public key can be used to verify responses on both test and production environments.

Signature calculation

To sign a response, Kontomatik builds a byte sequence containing data in this order:

the bytes of a string obtained by concatenating headers in the format HeaderName: HeaderValue

the bytes of the response body

The byte sequence is signed using SHA256withRSA and the resulting signature data is base64-encoded.

The final base64-encoded value is assigned to the signature field of the Signature response header.

The header names used as input to the signature have a capital initial letter, while header names in a Kontomatik response may be lowercased. The correct sequence of header names/values, properly capitalized and ordered, required to verify the signature is given as a comma-separated list in the headers field of the Signature response header.

KeyId calculation

This section details the algorithm used by Kontomatik to calculate the keyId value. The keyId could be useful if Kontomatik publishes multiple keys. In this case, the keyId would allow clients to determine which public key must be used to verify a response.

The example assumes no headers were included in the signature calculation, i.e. the headers field in the Signature header is empty, which means the text in the response body - 'I am working.’ - is the actual signed content.

Testing

You don’t need to own a bank account in all banks to test your integration with Kontomatik Service.

Kontomatik Service offers mock (example) responses for all commands in all banks.

To use it, you must either:

enter “test” as first credential

mark “Test credentials” checkbox on the bank selection list - in this case you can use whatever login as the first credential. Please note this option is available only for selected clients.

For the other credentials you must use “Test123”.

In exceptional cases:

if it asks you for date, enter “00/00/0000”

if it asks you to choose picture, select “white clouds in the blue sky”

By using test credentials the session gets internally marked as a testing session and example (hardcoded) data are returned instead of connecting to banks.
That being said one small request to the bank is made just to check connectivity.

Getting help

Reporting issues

Aggregating account information is tough. The specifics of how data services work in
each bank, the myriad types of accounts and authentication paths, the unexpected pitfalls and
tendency of bank websites to change without warning - all require special maintenance efforts that scale up in proportion to
coverage.

Despite this, over the years Kontomatik quality has nicely increased.

However, errors in the operation of the application may still occur, which is normal in this case due to the circumstances described above. As a user you must be aware of this.

Before reporting a problem, please remember that:

we are automatically notified about KontoXBug exceptions; it’s not necessary to contact us in such cases, except if
you want to track the progress in solving a bug or increase its priority.

always create a ticket by writing to [email protected]; never request tech support by writing in private to a staff member.

please include in your report, along with a description of the request, something to help us identify the session, such as a sessionId,
commandId or even an externalOwnerId parameter.

Please do not report errors related to external factors or user actions. Before contacting support, kindly take a moment to read the chapter on error handling.

Integration examples

The following unofficial projects offer additional help to developers looking to integrate Kontomatik API.

Kontomatik-help-kit simplifies the process of manually importing data from terminal, using curl. The kit contains a index.html page embedding the Sign-In Widget and simple shell scripts which build and submit the Http requests corresponding to the main API methods.

KontomatikServiceDemo is an example web application with a backend Kontomatik API client implemented in .NET.

Please note that these projects do not represent software products officially supported by Kontomatik. We will not assist with any related technical questions, nor be responsible for any inconveniences resulting from using the source code.