NAV
code

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.

Ask for demo access.

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.
User The end user who owns bank credentials.

API Conventions

Get API access

Authentication

Kontomatik API is protected by two-factor authentication:

Test environment

Use the test environment for testing and development.

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

We kindly ask you to not use it for your production deployments.

The test API endpoint is: https://test.api.kontomatik.com/

Request test API access at kontomatik.com.

Production environment

The production API endpoint is: https://api.kontomatik.com/

To request your production API access, please contact your sales representative.

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:

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.

Kontomatik SignIn Widget:

Kontomatik SignIn Widget is an HTML5 iframe element that you embed on your website by calling our JavaScript.

Upon successful sign-in, you will be provided with the sessionId and sessionIdSignature parameters. You will need them to execute Kontomatik API commands.

Embedding the widget

<!-- index.html / head -->
<script src="https://signin.kontomatik.com/assets/signin-widget.js">
</script>

<!-- index.html / body -->
<div id="kontomatik" />

// index.js
embedKontomatik({
  client: 'YOUR_CLIENT_ID',  // replace it with your assigned client id
  divId: 'kontomatik',       // must match the div element id
  onSuccess: function(target, sessionId, sessionIdSignature, options) {
    // End-user successfully signed in to the bank
    // Pass target, sessionId and sessionIdSignature to your backend
    alert('It works!');
  }
});

To embed the widget on your web page:

See the example in the code section.

The client param identifies you and selects the API endpoint. See test and production to learn how to claim your API access.

Required params

The embedKontomatik() function takes the following obligatory parameters:

Parameter Description
client The client id you received from us. You will likely have two of them - one for the test and one for production API. See embedding the widget for details.
divId Where to render the widget. Make sure this div element already exists before calling the embedKontomatik() function.
onSuccess Callback function for end-user successful login into the bank. Please see onSuccess callback description for more details.

Optional params

The embedKontomatik() function takes the following optional parameters:

Parameter Default Description
country null Pre-selects the country. If omitted, the country drop down list will be shown. Accepted values: br cz es uk mx pl ru it lv ee.
clientIdentity null The full name under which your company is registered, ex. “Kreditech Holding SSL GmbH”.
locale en Determines end-user interface language. Accepted values: br cz en es mx pl ru.
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 Option to control whether beta quality banks display the warning label - (beta)
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.
showTargetsAsGridView false If true the Widget will display bank logos in a grid, instead of a drop-down list. The option requires the embedKontomatikPopup function. The option is intended to be used for Polish targets.
styles null Optional object defining the look and feel of the widget. For more information please refer to styling the widget section.

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.

Callbacks are passed to embedKontomatik() function as params.

Here is the brief summary of available callbacks:

Callback Required Description
onSuccess yes Callback function for end-user successful login into the bank. Please see onSuccess callback description for more details.
onError no Callback function for end-user failed login attempt into the bank (for any reason). Please see onError callback description for more details.
onUnsupportedTarget no Invoked when the user clicks “My bank is not listed…” option on the bank selection list. Please see onUnsupportedTarget callback description for more details.
onInitialized no Called when the application is fully initialized and ready for user interaction. Please see onInitialized callback description for more details.
onStarted no Called when bank selection list is shown. Please see onStarted callback description for more details.
onTargetSelected no Invoked when user selects bank from the list. Please see onTargetSelected callback description for more details.
onCredentialEntered no Called after user enters credential. Please see onCredentialEntered callback description for more details.
onUnloaded no If the Widget is displayed in a pop-up window, this function is called when the user closes the window.

The following figure presents a visual reference for the callbacks and widget’s transition between stages.

onSuccess callback

When the user successfully signs into the banking system the onSuccess callback is called. It will be passed the following parameters:

Parameter Description
target an identifier of the bank the end user has signed into
sessionId an identifier of the Kontomatik session
sessionIdSignature signature created for the sessionId to detect any attempt to tamper with its value
options an object containing extra properties, a more detailed explanation follows below

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.
options an object containing extra properties, a more detailed explanation follows below

The options object contains the following properties:

Property Available Description
target always an identifier of the bank the end user has attempted to sign into
sessionId always an identifier of the session that has resulted in an error
officialName always the full bank name

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.

Displaying the Widget in a pop-up window

You can display the SignIn Widget in a pop-up window loaded from our domain, instead of an HTML <iframe> embedded in your web page.

To this end:

On load, your page will have a button with the text Kontomatik SignIn. When the user clicks the button, the browser will display the SignIn Widget in a pop-up window loaded from the Kontomatik URL signin.kontomatik.com, allowing the user to perform the sign-in process on our domain.

This has both legal and technical implications.

Legally, the setup places data privacy responsibilities squarely on Kontomatik’s shoulders, as a PSD2-regulated AISP.

Technically, the pop-up window is also necessary if you want to display bank logos in a grid layout, as described here.

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'
  }
});

Scope and approach

Widget offers easy customization of colors but no arbitrary CSS overrides.

Why no CSS overrides? We improve the widget every month in a CSS-breaking way to further optimize conversion rate, security and usability.

Allowing for arbitrary CSS overrides would effectively block us from ongoing widget development (or we would break our customers layouts).

This limitation brings mutual benefits - you automatically get all important improvements, for free.

We believe you can get very close to your ideal visual effect just by smartly customizing the colors.

How to customize the colors?

Customization is achieved by passing the styles: { /* ... */ } option to embedKontomatik() function.

For a complete list of styles object properties see the following table.

Key Description
alertErrorBgColor
alertErrorBorderColor
alertErrorTextColor
 respectively controls the background, border and text color of an error message alert box
bodyBgColor the background color of the widget
borderRadius controls the corner roundness of all input components (buttons, inputs, alert box). The default value is 4px
btnBgColor
btnBorderColor
btnTextColor
 respectively controls the background, border and text color of the “Change bank” button
btnPrimaryBgColor
btnPrimaryBorderColor
btnPrimaryTextColor		 respectively controls the background, border and text color of the “Next” and “Try again” buttons
inputBgColor
inputBorderColor
inputTextColor
inputDisabledTextColor
inputBorderFocusColor		 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

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:

Consider making Kontomatik the primary scenario/path in your loan application process

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

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

Request

curl --get \
  --header "Accept-Encoding: gzip" \
  https://test.api.kontomatik.com/isItWorking

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

Accept-Encoding: gzip

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.

Default import command

Request

curl -X POST \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  --data "since=YYYY-MM-DD" \
  https://test.api.kontomatik.com/v1/command/default-import.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="000000" state="setup" name="DefaultImportCommand" target="Alior">
    <progress><value>0</value></progress>
  </command>
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/default_import.xsd" status="200 OK">
  <command id="653643" state="successful" name="DefaultImportCommand" target="Alior">
    <progress><value>13</value></progress>
    <result>
      <owners>
        <owner>
          <name>Jan Kowalski</name>
          <address>Kwiatowa 8/97 Warszawa  PL</address>
          <polishPesel>84011806651</polishPesel>
          <phone>+48612***078</phone>
          <email>[email protected]</email>
          <citizenship>PL</citizenship>
          <personalDocumentType>Identity document</personalDocumentType>
          <personalDocumentNumber>AAB123456</personalDocumentNumber>
          <birthDate>1984-01-18</birthDate>
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyFundsAvailable>1407.39</currencyFundsAvailable>
          <currencyName>PLN</currencyName>
          <owner>Jan Kowalski, Adam Nowak</owner>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <moneyTransactions>
            <moneyTransaction>
              <transactionOn>2012-06-28</transactionOn>
              <bookedOn>2012-06-30</bookedOn>
              <currencyAmount>20.00</currencyAmount>
              <title>Return for beer in a pub</title>
              <party>Jan Kowalski</party>
              <partyIban>PL68249000050000400075212326</partyIban>
              <kind>EXTERNAL INCOMING TRANSFER</kind>
              <labels>
                <label><!-- label type --></label>
                <!-- ... more labels ... -->
              </labels>
            </moneyTransaction>
            <!-- ... more transactions ... -->
          </moneyTransactions>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
    </result>
  </command>
</reply>

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:

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 obligatory API key.
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 default-import command is a high-level API on top of primitive commands, such as import-owners, import-accounts, import-account-transactions.

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.

Command status

Request

curl --get \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/000000.xml

Response for command in setup state

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
  <command id="000000" state="setup" name="...">
    <progress><value>0</value></progress>
  </command>
</reply>

Response for command in in_progress state

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
  <command id="000000" state="in_progress" name="...">
    <progress><value>8</value></progress>
  </command>
</reply>

Response for command in successful state:

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
  <command id="000000" state="successful" name="...">
    <progress><value>123</value></progress>
    <result>
      <!-- imported data, command specific -->
    </result>
  </command>
</reply>

Response for command in cancelled state

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
  <command id="000000" state="cancelled" name="...">
    <progress><value>123</value></progress>
  </command>
</reply>

Response for command in error state:

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
  <command id="000000" state="error" name="...">
    <progress><value>20</value></progress>
    <exception name="SessionExpired">
      <message>Exception message</message>
      <!-- optional tag --> 
      <friendlyMessage>Exception message in local language</friendlyMessage>
    </exception>
  </command>
</reply>

Response for command in fatal state:

<?xml version="1.0" encoding="utf-8"?>
<reply status="200 OK">
  <command id="000000" state="fatal">
    <progress><value>25</value></progress>
    <exception name="ExampleException">
      <message>Exception message</message>
    </exception>
  </command>
</reply>

Returns information about the status and progress of the command. Once the command has successfully completed, the request will also return the imported data.

Most of the commands are asynchronous and upon initiating them, the command identifier is immediately returned to the client. The client should poll the status of the command using command id.

HTTP Request

GET /v1/command/:id.xml

Parameters

Parameter Default Description
apiKey obligatory API key.
sessionId obligatory Session identifier.
sessionIdSignature obligatory Signature preventing session id enumeration by attacker.
:id obligatory Command identifier as part of the URL.

Data returned

See on the right pane how the data structure looks like per command status.

For a detailed description of <result> content see the documentation of the relevant commands in the advanced API.

Command states table:

State Description
setup command is queued and is awaiting allocation of resources
in_progress command is scraping data from online transaction system
successful the command has successfully executed. All data imported by the command is contained inside <result> tag.
cancelled the command has been cancelled by the service client
error command execution failed to complete due to: 1) errors beyond Kontomatik control (i.e. expired session with transaction system, target transaction system is experiencing some technical problems) 2) client induced errors (i.e. invalid bank account number, unsupported command for a given target). The <exception> element contains error details. Errors should not be reported to Kontomatik.
fatal 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.

Error handling

We can divide possible errors into four categories:

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

Response (example)

<?xml version="1.0" encoding="utf-8"?>
<reply status="404 Not Found">
  <exception name="InvalidCommandId">
  </exception>
</reply>

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

Simply check for the HTTP response status code. Of course, don’t assume XML body in this case.

Unexpected async command failure

You will learn about this error after polling for command status and noticing the fatal command state:

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.

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.

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.

Advanced API

Tutorial

Please get API access if you haven’t done so already.

Follow this if you need a full control over the data import process and flow. If you just want to get key data quickly see the basic tutorial.

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

Catalog

Request

curl --get \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "country=pl" \
  --data "favicons=false" \
  https://test.api.kontomatik.com/v1/catalog.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_catalog.xsd" status="200 OK">
  <targets>
    <target name="" officialName="BOŚ Bank">
      <commands>
        <command name="EnterCredentialCommand"/>
        <command name="ImportAccountTransactionsCommand"/>
        <command name="ImportAccountsCommand"/>
        <command name="ImportOwnersDetailsCommand"/>
      </commands>
      <favicon imageFormat="image/x-icon">
        AAABAAMAE...AAAAA=
      </favicon>
    </target>
    <!-- ... more targets ... -->
  </targets>
</reply>

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 obligatory API key.
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.

Import Owners (command)

Request

curl -X POST \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/import-owners.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportOwnersCommand" target="Alior">
  <progress><value>0</value></progress>
  </command>
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_owners_details.xsd" status="200 OK">  
<command id="653643" state="successful" name="ImportOwnersCommand" target="Alior">
    <progress><value>1</value></progress>
    <result>
      <owners>
        <owner>
          <kind>OWNER</kind>
          <name>Jan Witkacy Kowalski</name>
          <address>Krótka 8, Wąchock</address>
          <polishPesel>82012905123</polishPesel>
          <polishNip>1258882345</polishNip>
          <phone>694234567</phone>
          <email>[email protected]</email>
          <citizenship>Kazakhstan</citizenship>
          <nationality>Polskie</nationality>
          <personalDocumentType>Passport</personalDocumentType>
          <personalDocumentNumber>FGH123456</personalDocumentNumber>
          <birthDate>1960-02-29</birthDate>
          <polishRegon>121260111</polishRegon>
        </owner>
      </owners>
    </result>
  </command>
</reply>

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 obligatory API key.
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
polishPesel possibly none Polish PESEL number
polishNip possibly none Polish NIP number
phone possibly none phone
email possibly none e-mail
citizenship possibly none citizenship
nationality possibly none nationality
personalDocumentType possibly none identity document type, as presented by the bank
personalDocumentNumber possibly none identity document number
birthDate possibly none date of birth
polishRegon possibly none Polish REGON number
birthPlace possibly none Place of owner’s birth

Import Accounts (command)

Request

curl -X POST \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/import-accounts.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportAccountsCommand" target="Alior"/>
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_accounts.xsd" status="200 OK">  
<command id="653643" state="successful" name="ImportAccountsCommand" target="Alior">
    <progress><value>1</value></progress>
    <result>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyFundsAvailable>1407.39</currencyFundsAvailable>
          <currencyName>PLN</currencyName>
          <owner>Jan Kowalski, Adam Nowak</owner>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <directDebit available="true"/>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
    </result>
  </command>
</reply>

Initiates import of bank 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-accounts.xml

Parameters

Parameter Default Description
apiKey obligatory API key.
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.

Import Transactions (command)

Request

curl -X POST \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  --data "iban=PL00000000000000000000000000" \
  --data "since=2015-12-01" \
  https://test.api.kontomatik.com/v1/command/import-account-transactions.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportAccountTransactionsCommand" target="Alior">
    <progress><value>0</value></progress>
  </command>
</reply>

Final result of polling for this command status

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_account_transactions.xsd" status="200 OK">  
<command id="653643" state="successful" name="ImportAccountTransactionsCommand" target="Alior">
    <progress><value>97</value></progress>
    <result>
      <moneyTransactions>
        <moneyTransaction>
          <transactionOn>2012-06-28</transactionOn>
          <bookedOn>2012-06-30</bookedOn>
          <currencyAmount>20.00</currencyAmount>
          <currencyBalance>230.00</currencyBalance>
          <title>Return for beer in a pub</title>
          <party>Jan Kowalski</party>
          <partyIban>PL68249000050000400075212326</partyIban>
          <kind>EXTERNAL INCOMING TRANSFER</kind>
          <!-- variableSymbol: only in Czech accounts -->
          <variableSymbol>1234567890</variableSymbol>
          <labels>
            <label><!-- label type --></label>
            <!-- ... more labels ... -->
          </labels>
        </moneyTransaction>
        <!-- ... more transactions ... -->
      </moneyTransactions>
    </result>
  </command>
</reply>

<!-- Partial responses will include this attribute! --> 
<moneyTransactions partialDueToTimeout="true">
  <!-- ... transactions ... -->
</moneyTransactions>

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 obligatory API key.
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”)
variableSymbol possibly none identifier used for payments in Czech Republic (variabilní symbol)
labels possibly none list of transaction’s labels. See Transaction labeling for more information

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.

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportCreditCardsCommand"/>
</reply>
Parameter Default Description
apiKey obligatory API key.
sessionId obligatory Session identifier.
sessionIdSignature obligatory Security parameter to prevent session enumeration. 
<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_credit_card.xsd" status="200 OK">
<command id="89817419" state="successful" name="ImportCreditCardsCommand">
  <progress><value>2</value></progress>
    <result>
      <creditCards>
        <creditCard>
          <name>Visa</name>
          <number>1234 1234 1234 1234</number>
          <currencyBalance>-2467.39</currencyBalance>
          <currencyName>PLN</currencyName>
          <owner>Jan Kowalski, Adam Nowak</owner>
          <limit>5000.00</limit>
          <interest>20</interest>
          <dueDate>2013-10-26</dueDate>
        </creditCard>
       <!-- ... more credit cards ... -->
       </creditCards>
    </result>
  </command>
</reply>
Data Availability Description
name guaranteed card name, as stated in the bank’s system
number guaranteed 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
limit possibly none credit limit as a positive number
interest possibly none card’s interest rate, expressed in percentage
dueDate possibly none the day the payment is due; date format: YYYY-MM-DD

Import Credit Card Transactions (command)

POST /v1/command/import-credit-card-transactions.xml

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.

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/command.xsd" status="202 Accepted">
  <command id="653643" state="setup" name="ImportCreditCardTransactionsCommand"/>
</reply>
Parameter Default Description
apiKey obligatory API key.
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. 
<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/import_credit_card_transactions.xsd" status="200 OK">
  <command id="89817986" state="successful" name="ImportCreditCardTransactionsCommand">
    <progress><value>3</value></progress>
    <result>
      <moneyTransactions>
        <moneyTransaction>
          <transactionOn>2017-08-10</transactionOn>
          <bookedOn>2017-08-11</bookedOn>
          <currencyAmount>-20.00</currencyAmount>
          <currencyBalance>1100.99</currencyBalance>
          <title>Zwrot za Sylwestra</title>
          <party>Jan Kowalski Dunikowskiego 23B, 01-200 Warszawa</party>
          <partyIban>PL83130000002076700146310001</partyIban>
          <kind>PRZELEW ZEWNĘTRZNY</kind>
          <uid>2017-08-11__-20.00</uid>
          <labels>
            <label>internal</label>
          </labels>
        </moneyTransaction>
        <!-- ... more transactions ... -->
      </moneyTransactions>
    </result>
  </command>
</reply>
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”)

Pattern matching for credit card numbers

Credit card format examples: 

1234 0987 5678 0055           # matches entire number
1234098756780055              # matches entire number without spaces
1234 **** **** 0055           # matches a number where some digits are replaced by asterisks
**** **** **** ***5           # matches a number where most digits are replaced by asterisks
****************              # matches any card

The command to import credit card transactions supports pattern matching the card number:

Sign Out (command)

Request

curl -X POST \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/sign-out.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/layout.xsd" status="200 OK">
</reply>

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 obligatory API key.
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.

Cancel command

Request

curl -X POST \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  https://test.api.kontomatik.com/v1/command/YOUR_COMMAND_ID_HERE/cancel.xml

Response

<reply status="202 Accepted">
</reply>

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

POST /v1/command/COMMAND_ID/cancel.xml

Parameters

Parameter Default Description
apiKey obligatory API key.

Data

Request

curl --get \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
  https://test.api.kontomatik.com/v1/data.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_data.xsd" status="200 OK">  <owner externalId="653643">
    <target name="MBank">
      <owners>
        <owner>
          <name>Jan Kowalski</name>
          <address>Kwiatowa 8/97 Warszawa  PL</address>
          <polishPesel>84011806651</polishPesel>
          <phone>+48612***078</phone>
          <email>[email protected]</email>
          <citizenship>PL</citizenship>
          <personalDocumentType>Identity document</personalDocumentType>
          <personalDocumentNumber>AAB123456</personalDocumentNumber>
          <birthDate>1984-01-18</birthDate>
          <birthPlace>Warsaw</birthPlace>
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyFundsAvailable>1407.39</currencyFundsAvailable>
          <currencyName>PLN</currencyName>
          <owner>Jan Kowalski, Adam Nowak</owner>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <moneyTransactions>
            <moneyTransaction>
              <transactionOn>2012-06-28</transactionOn>
              <bookedOn>2012-06-30</bookedOn>
              <currencyAmount>20.00</currencyAmount>
              <currencyBalance>443.00</currencyBalance>
              <title>Return for beer in a pub</title>
              <party>Jan Kowalski</party>
              <partyIban>PL68249000050000400075212326</partyIban>
              <kind>EXTERNAL INCOMING TRANSFER</kind>
              <uid>2012-06-30__20.00</uid>
                <labels>
                  <label><!-- label type --></label>
                  <!-- ... more labels ... -->
                </labels>
            </moneyTransaction>
            <!-- ... more transactions ... -->
          </moneyTransactions>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
    </target>
  </owner>
</reply>

<!-- Partial responses will include this attribute! -->
<account partialDueToTimeout="true">
<!-- account details --> 
</account>

Returns all imported and aggregated data associated with the end user identified by an ownerExternalId parameter passed when embedding the Kontomatik Sign-in widget.

Response can take up to several seconds and potentially it may return lots of data (thousands of transactions) depending on the end user’s activity.

HTTP Request

GET /v1/data.xml

Parameters

Parameter Default Description
apiKey obligatory API key.
ownerExternalId obligatory 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.

Delete data

HTTP Request

DELETE /v1/owner.xml

curl -X DELETE --data-urlencode "apiKey=YOUR_API_KEY_VALUE"\
              --data-urlencode "ownerExternalId=222222"\
               https://test.api.kontomatik.com/v1/owner.xml


<reply status="200 OK">
</reply>

Deletes all imported and aggregated data associated with the end user identified by an ownerExternalId parameter passed when embedding the Kontomatik Sign-in widget.

Parameter Default Description
apiKey obligatory API key.
ownerExternalId obligatory Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in Widget.

Health Check

Request

curl --get \
  https://test.api.kontomatik.com/isItWorking

Response

I am working.

Used to ensure that Kontomatik server is up.

This is the only request that does not require the API key.

HTTP Request

GET /isItWorking

Data returned

The request should response with a plain text “I am working.”.

Lending API

Kontomatik offers powerful tools for financial behavior analysis.

Lending API makes it easy to take full advantage of the raw banking data.

The API works on the data you imported earlier. Be sure to import the data first.

Both screen-scraped data and PDF-extracted data are compatible with the lending API.

Scores

Request

curl --get \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
  https://test.api.kontomatik.com/v1/owner-scores.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_owner_scores.xsd"
  status="200 OK"
  client="fastmoney"
  ownerExternalId="4324-13-14">

  <models>

    <!-- Common model -->
    <model id="common-2018-08-18" retrainedAt="2018-08-20T16:16:45Z">
      <scores>
        <score id="default-probability">
          <!-- 0..1 value representing estimated probability of default (the lower the better) -->
          <value>0.03282</value>
        </score>
        <score id="population-percentile">
          <!-- 0..1 value representing population percentile (the higher the better) -->
          <value>0.49824</value>
        </score>
      </scores>
    </model>

    <!-- Model specific to lender "Fast Money" (just to give an example) -->
    <model id="fastmoney-2018-08-01" retrainedAt="2018-08-14T07:16:45Z">
      <scores>
        <score id="default-probability">
          <!-- 0..1 value representing estimated probability of default (the lower the better) -->
          <value>0.03517</value>
        </score>
        <score id="population-percentile">
          <!-- 0..1 value representing population percentile (the higher the better) -->
          <value>0.51069</value>
        </score>
      </scores>
    </model>

  </models>
</reply>

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 attempts to estimate probability of default on a loan. It comes by the name default-probability.

The supplementary score attemtps to estimate percentile of population the lendee is better then. It comes by the name population-percentile.

Kontomatik offers:

Our example lender-specific score achived Gini 0.56 (UAC 0.78) in our most conservative cross-validation benchmarks.

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 obligatory API key.
ownerExternalId obligatory Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in widget.

Data returned

Critical:

Every <score> has the following structure:

Data Availability Description
id guaranteed Unique identifier of the score.
value guaranteed Decimal value of the score.

We publish the following scores:

Input Features

Request

  curl --get \
    --data "apiKey=YOUR_LONG_API_KEY_HERE" \
    --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
    https://test.api.kontomatik.com/v1/owner-features.xml

Response

  <?xml version="1.0" encoding="utf-8"?>
  <reply
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_features.xsd"
  status="200 OK"
  client="fastmoney"
  ownerExternalId="4324-13-14">

  <models>

    <!-- Common model -->
    <model id="common-2018-08-18" retrainedAt="2018-08-20T16:16:45Z">
      <features>
        <feature id="d4f51702ea" value="-0.43" />
        <feature id="59ab5c6f97" value="2.00355" />
        <feature id="03d10dbf0a" value="1.932" />
        <feature id="ec4207aaf2" value="NaN" />
        <feature id="b31711374c" value="-INF" />
        <feature id="ddb0ebf93a" value="INF" />
        <!-- ...hundreds of features... -->
      </features>
    </model>

    <!-- Model specific to lender "Fast Money" (just to give an example) -->
    <model id="fastmoney-2018-08-01" retrainedAt="2018-08-14T07:16:45Z">
      <features>
        <feature id="d4f51702ea" value="-0.43" />
        <feature id="59ab5c6f97" value="2.00355" />
        <feature id="03d10dbf0a" value="1.932" />
        <feature id="ec4207aaf2" value="NaN" />
        <feature id="b31711374c" value="-INF" />
        <feature id="ddb0ebf93a" value="INF" />
        <!-- ...hundreds of features... -->
      </features>
    </model>

  </models>
</reply>

Kontomatik offers powerful input features for your existing scoring models.

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-specifc historical repayment data.

HTTP Request

GET /v1/owner-features.xml

Parameters

Parameter Default Description
apiKey obligatory API key.
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.

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.

Our data scientists can guide you through the process.

Transaction Labeling

<moneyTransactions>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>monthly</label>
      <label>repayment</label>
    </labels>
  </moneyTransaction>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>health</label>
    </labels>
  </moneyTransaction>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>gambling</label>
    </labels>
  </moneyTransaction>
  <moneyTransaction>
    <!-- ...transaction details... -->
    <labels>
      <label>loan</label>
    </labels>
  </moneyTransaction>
  <!-- ... more transactions ... -->
</moneyTransactions>

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
online expense internet payment of any kind: online shopping, online service subscription, including online payment for usual goods (online grocery stores, online utility payments); the label identifies a method of payment over the internet typically involving online card payment or a payment processor like PayPal, PayU, DotPay, Allegro, DialCom24; does not cover: transfers executed manually by the user via his online banking interface

Compensation

label direction description
salary income transfer from a company to an individual on the basis of an employment contract
compensation income widely understood compensation, including all cases where individual receives money from a company, such as on the basis of a B2B contract; compensation is wider than salary
pension both payments of retirement money received from the state

Debt

label direction description
loan income transactions indicating a loan from a lending company or a bank; the label covers payday loans, consumer loans etc; does not cover: mortgage or leasing-related transactions
mortgage both transactions indicating a mortgage repayment
leasing both transactions indicating a leasing repayment; often involves a car leasing
repayment expense repayment of a loan, installment, credit card, mortgage, or any other kind of debt
invoice both all incoming (mostly for companies) invoices, but also outgoing payments (often for phone and internet and tv)
bailiff expense transactions that are executed by bailiffs or enforcement agents following a court decision and without any action from the account owner
debt collection both voluntarily repayment of debt to specialized debt collection companies

State

label direction description
welfare income 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.

Cash

label direction description
cash withdrawal expense physical cash withdrawal from a bank machine (ATM) or bank branch
cash deposit income physical cash deposit via bank machine (ATM) or bank branch

Lifestyle

label direction description
nightlife expense pubs and cocktail bars, night clubs, gentlemen clubs
uberlike and taxi both taxis, taxi-like services (ex. Uber, Taxify, Lyft), carpooling services (ex. BlaBlaCar) and car rentals
tobacco expense indicates products boght in specialized tobacco shops (only for Spain)
gambling both online gambling and betting, lottery tickets, city casinos, and other forms of gambling; it can also mark income transactions, ex. gambling gains
alcohol expense spirits and liquor stores, online alcohol shops
beauty expense cosmetics, pharmacy, perfume shops, barber and hair dresser, manicure and pedicure salons, basic hygiene expenses; does not cover: apparel
leisure expense gym, cinema, theater, hotels, plane tickets, book stores, games, online entertainment; does not cover: gambling
insurance expense mandatory or optional insurance of any type

Living

label direction description
rent expense rent for the flat or house; does not cover: receiving rent
utilities expense basic utilities like electricity, gas, water, heating, garbage collection; does not cover: TV, phone, internet, rent
phone expense mobile, landline
internet and tv expense internet and TV bills
fee expense bank and other financial fees; most often relatively small amount; does not cover: fines and tickets
grocery expense grocery stores, discount stores, supermarkets
eating out expense bars, restaurants, cafes, bistros, fast food restaurants; does not cover: pubs, cocktail bars, night clubs
children both 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
alimony both incoming and outgoing alimony transactions (children-related)
healthcare expense medication, doctor and dentist visits, medical diagnosis, hospital bills, treatment bills, rehabilitation bills; does not cover: beauty procedures, SPA, and similar
car expense fuel, parking, insurance, repairs, car accessories, road taxes, tickets and other car related expenses
public transport expense public transport tickets and fees
apparel expense clothes, shoes, handbags, etc
refurbishment expense construction, furniture, interior design and household appliances
return both money returned because of overpayment (ex. tax returns) or consumer goods returned at the store; also includes insurance compensation

Aggregated Values

Request

curl --get \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
  --data "periodMonths=6" \
  https://test.api.kontomatik.com/v1/aggregates.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/aggregates.xsd" status="200 OK">  
<owner externalId="123456">
    <target name="MBank">
      <accounts>
        <account>
          <iban>PL49114020040000350243107620</iban>
          <activeSinceAtLeast>2014-03-03</activeSinceAtLeast>
          <currencyName>PLN</currencyName>
          <owner>Jan Kowalski</owner>
          <!-- Additional aggregates when labeling is turned on -->
          <salaryAmountAverage>2300.00</salaryAmountAverage>
          <compensationAmountAverage>2300.00</compensationAmountAverage>
          <welfareAmountAverage>500.00</welfareAmountAverage>
          <loanAmountAverage>800.00</loanAmountAverage>
          <mortgageAmountAverage>0.00</mortgageAmountAverage>
          <leasingAmountAverage>0.00</leasingAmountAverage>
          <repaymentAmountAverage>650.00</repaymentAmountAverage>
          <loanCompaniesCount>3</loanCompaniesCount>
          <months>
            <month date="2014-03">
              <daysInMonth>31</daysInMonth>
              <withdrawalsCount>2</withdrawalsCount>
              <withdrawalsTotal>32.50</withdrawalsTotal>
              <depositsCount>2</depositsCount>
              <depositsTotal>32.50</depositsTotal>
              <balance>64.50</balance>
              <balanceAverage>24.50</balanceAverage>
              <positiveBalanceAverage>24.50</positiveBalanceAverage>
              <negativeBalanceAverage>-24.50</negativeBalanceAverage>
              <maxBalance>90.50</maxBalance>
              <minBalance>-90.50</minBalance>
              <!-- Aggregates specific to Poland -->
              <polishZusTransactionsCount>1</polishZusTransactionsCount>
              <polishZusTransactionsTotal>10000.00</polishZusTransactionsTotal>
              <polishUsTransactionsCount>1</polishUsTransactionsCount>
              <polishUsTransactionsTotal>10000.00</polishUsTransactionsTotal>
              <!-- Additional aggregates when labeling is turned on -->
              <salaryAmountTotal>2300.00</salaryAmountTotal>
              <compensationAmountTotal>2300.00</compensationAmountTotal>
              <welfareAmountTotal>500.00</welfareAmountTotal>
              <loanAmountTotal>600.00</loanAmountTotal>
              <mortgageAmountTotal>0.00</mortgageAmountTotal>
              <leasingAmountTotal>0.00</leasingAmountTotal>
              <repaymentAmountTotal>1200.00</repaymentAmountTotal>
              <loanCompaniesCount>2</loanCompaniesCount>
            </month>
            <!-- ...more months... -->
          </months>
        </account>
      </accounts>
    </target>
  </owner>
</reply>

Calculates and returns aggregates for end-user identified by ownerExternalId parameter passed when embedding the Kontomatik Sign-in widget.

Imported data is grouped by accounts and a monthly summary statistics is calculated (i.e. number of withdrawals, balance average) for each of the accounts.

The length of the period for which the aggregates are calculated is determined by the value of periodsMonth parameter.

This command does not import any data by itself, it just uses data imported by other commands for a given end-user (i.e. import accounts, import-transactions commands).

HTTP Request

GET /v1/aggregates.xml

Parameters

Parameter Default Description
apiKey obligatory API key.
ownerExternalId obligatory 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)
polishZusTransactionsTotal possibly none net value of all transactions from/to Polish Social Insurance Institution (ZUS)
polishUsTransactionsCount possibly none total number of transactions from/to Polish Internal Revenue Service
polishUsTransactionsTotal possibly none net value of all transactions from/to Polish Internal Revenue Service

Labeling Aggregates

When Transaction Labeling feature is turn on, additional aggregates will be provided.

Concerning <account>:

Data Availability Description
salaryAmountAverage when labeling on average amount of transactions labeled as salary
compensationAmountAverage when labeling on average amount of transactions labeled as compensation
welfareAmountAverage when labeling on average amount of transactions labeled as welfare
loanAmountAverage when labeling on average amount of transactions labeled as loan
mortgageAmountAverage when labeling on average amount of transactions labeled as mortgage
leasingAmountAverage when labeling on average amount of transactions labeled as leasing
repaymentAmountAverage when labeling on average amount of transactions labeled as repayment
loanCompaniesCount when labeling on a total count of every loan company recognized on this account

Concerning <month>:

Data Availability Description
salaryAmountTotal when labeling on total amount of transactions labeled as salary in a given month
compensationAmountTotal when labeling on total amount of transactions labeled as compensation in a given month
welfareAmountTotal when labeling on total amount of transactions labeled as welfare in a given month
mortgageAmountTotal when labeling on total amount of transactions labeled as mortgage in a given month
loanAmountTotal when labeling on total amount of transactions labeled as loan in a given month
leasingAmountTotal when labeling on total amount of transactions labeled as leasing in a given month
repaymentAmountTotal when labeling on total amount of transactions labeled as repayment in a given month
loanCompaniesCount when labeling on a total count of every loan company recognized in a given month

Legacy API

Financial Health Indicator

Request

curl --get \
  --data "apiKey=YOUR_LONG_API_KEY_HERE" \
  --data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
  https://test.api.kontomatik.com/v1/indicator.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/owner_rating.xsd" status="200 OK">
  <indicator>
    <value>87</value>
    <distribution>
      <period>
        <days>7</days>
        <startAt>YYYY-MM-DD HH:MM:SS</startAt>
        <endAt>YYYY-MM-DD HH:MM:SS</endAt>
      </period>
      <average>49.07</average>
      <median>51.00</median>
    </distribution>
  </indicator>
</reply>

Financial Health Indicator (FHI) is a single 0-100 number aiming to roughly assess end-user bank accounts’ trustworthiness (the more, the better).

FHI is solely based on end-user’s banking data. Presently it does not take into account any other factors.

Among other things, we take into account average monthly income, total balance, bank accounts reliability (how old and rich in data the accounts are), the sum of loans granted by other lenders, etc.

Details of the algorithm are proprietary and evolving.

This command does not import any data by itself, it just uses data imported by other commands for a given end-user (i.e. import accounts, import transactions commands).

It’s essential to wait for the import commands to finish before requesting GET /v1/indicator.xml, otherwise the algorithm will work on partial data and produce unreliable results.

This request also returns a distribution of FHI values based on all previous data stored in our service. This may work as a base for your threshold and will change as we adjust our FHI algorithms.

HTTP Request

GET /v1/indicator.xml

Parameters

Parameter Default Description
apiKey obligatory API key.
ownerExternalId obligatory Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in widget.

Data returned

FHI value is store in “value” tag of “indicator” tag. Indicator distribution data is being wrapped in “distribution” tag.

Data Availability Description
value guaranteed FHI value.
distribution guaranteed Container for distribution data.

Distribution data:

Data Availability Description
period guaranteed Container for “day”, “startAt” and “endAt” fields.
days guaranteed Describes how many days are being taken into account for counting distribution. It’s usually 7.
startAt guaranteed Start date of distribution counting period. It’s in YYYY-MM-DD HH:MM:SS format.
endAt guaranteed End date of distribution counting period. It’s in YYYY-MM-DD HH:MM:SS format.
average guaranteed Average value of all FHI values.
median guaranteed Median of all FHI values.

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:

For the other credentials you must use “Test123”.

In exceptional cases:

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:

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.

code