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

API Conventions

• The character encoding for API requests and responses is UTF-8.
• XML reply status codes are consistent with the HTTP response status codes.
• XML element and attribute names use the camel case naming convention.
• Dates and times follow ISO 8601 format, for example "YYYY-MM-DD" or "YYYY-MM-DDThh:mm:ssZ".
• Currency amounts use the standard computer format with two decimal places, i.e. "0.99", "-20.00".
• The /v1/ prefix in all URLs stands for API version.

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.

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:

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

Kontomatik SignIn Widget:

• Takes care of handling bank credentials. Sensitive bank credentials will never pass through your servers greatly reducing your security risks.

• Makes your integration quick and easy.

• Supports many unusual login scenarios (masked passwords, hardware tokens, SMS codes, CAPTCHA-s, multiple login paths and scenarios per bank, etc).

• Supports all edge-cases of invalid credentials, blocked accounts, expired sessions, etc.

• Has excellent, battle-tested conversion rate thanks to massive usage by our client-base.

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:

• Reference the widget's JavaScript library

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

• Call the embedKontomatik JS function, specifying your identifier, div id, and callback function

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:

Optional params

The embedKontomatik() function takes the following optional parameters:

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

<!-- 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', divId: 'kontomatik',       // must match the div element id
  onSuccess: 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
    forceSca: true,
    maxImportDate:  '2019-01-01'
    polishApiSpecific: {
      accountNumbers: ['PL32114020040000320250132522'], // the end-user won't be asked to choose accounts
      transactionsStatuses: ['DONE'], // we will fetch all transactions defined by this dictionary value
      consentTimeLimit: '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:

The embedKontomatik() function takes an additional (optional) parameter polishApiSpecific inside psd2 parameter which contains an object with properties specific to PolishAPI standard:

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:

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:

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.

The options object contains the following properties:

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:

The options object contains the following properties:

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:

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:

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

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.

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.
• Highlight the benefits of the process (like no hassle to provide paper documents, instant loan approval, etc).
• 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.
• The widget is multi-step by itself.

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.

• 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

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

Getting more than 90 days of data

SCA (Strong Customer Authentication) is a part of the Regulatory Technical Standards imposed by some banks in Open Banking connections. Part of SCA is the enforcing limitation of historical data retrieval to a maximum of 90 days of historical transactions after the initial consent and authentication of an end-user.

Kontomatik provides the solution which would support retrieving more than 90 days of the transaction history in some banks. To enable these steps you need to include two parameters (“maxImportDate” and “forceSca”) in the SignIn Widget. Adding them to Widget integration will authorize fetching more than 90 days of transaction history and assent to show the user additional steps where he can introduce additional authentication details.

These parameters are not obligatory and are provided as a resource in the Widget integration for clients who require extended transaction history. To achieve a specific goal please see the table below.

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.

We have created a sample code example with a demonstration of how easy it is to embed our widget into a mobile application. You will find the example under the integration-examples section.

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.

• Provide feedback to the user regarding successful completion of the process.

Default import command

Request

curl \
--header "X-Api-Key: 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">
    <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" institution="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> <!-- deprecated -->
          <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>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
            <owner>
              <name>Adam Nowak</name>
              <kind>CO_OWNER</kind>
            </owner>
          </owners>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
      <!-- ... if target supports credit cards import -->
      <creditCards>
            <creditCard>
               <name>Karta Kredytowa W/Shell</name>
               <cardId>**************13</cardId>
               <iban>PL19025714369262645919804211</iban>
               <number>**************13</number>
               <currencyBalance>-79.00</currencyBalance>
               <currencyFundsAvailable>1321.02</currencyFundsAvailable>
               <currencyName>PLN</currencyName>
               <owners>
                 <owner>
                   <name>Jan Kowalski</name>
                   <address>Kwiatowa 8/97 Warszawa  PL</address>
                   <kind>OWNER</kind>
                 </owner>
               </owners>
               <moneyTransactions>
                  <moneyTransaction>
                     <transactionOn>2019-10-02</transactionOn>
                     <bookedOn>2019-10-03</bookedOn>
                     <currencyAmount>-100.99</currencyAmount>
                     <currencyBalance>1000.00</currencyBalance>
                     <title>Transakcja kartą kredytową;obciążenie 4814 POL Poznan Doladowania.payu (efwu)</title>
                     <party>Doladowania.payu, POL Poznan Doladowania.payu</party>
                     <partyIban>PL63249010440000420034376084</partyIban>
                     <kind>ZAPŁATA KARTĄ</kind>
                     <status>DONE</status>
                     <variableSymbol>6789</variableSymbol>
                  </moneyTransaction>
                  <!-- ... more transactions ... -->
               <moneyTransactions>
            </creditCard>
       <!-- ... more credit cards ... -->
      </creditCards>
    </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:

• account owner(s) personal data for KYC check
• bank accounts listing with balances and account numbers
• full account statements for the requested period
• credit cards listing
• credit card transactions 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

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, import-credit-cards, import-credit-card-transactions.

The primitive commands allow you to independently import owners and/or accounts/cards and/or transactions on the selected accounts/cards. 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 \
  --header "X-Api-Key: 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

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:

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.

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.

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.

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.

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.

• User visits your website and arrives to the step involving Kontomatik.

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

• Get catalog for a list of commands supported by the selected target.

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

• Optionally fetch 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.

• Optionally fetch 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.

• Optionally log 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.

Catalog

Request

curl --get \
  --header "X-Api-Key: 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="Bos" institution="Bos" officialName="BOŚ Bank" officialUrl="https://www.bosbank.pl/" loginName="Identyfikator" beta="true">
      <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

Data returned

Description of <target> element:

Description of <command> element:

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 \
  --header "X-Api-Key: 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">
  <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" institution="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

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

Import Accounts (command)

Request

curl \
  --header "X-Api-Key: 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">
</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" institution="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> <!-- deprecated -->
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <directDebit available="true"/>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
                <kind>OWNER</kind>
            </owner>
            <owner>
               <name>Adam Nowak</name>
               <address>Robocza 1 M.14 Warszawa PL</address>
            </owner>
          </owners>
        </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

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 returned in owner tag

Import Transactions (command)

Request

curl \
  --header "X-Api-Key: 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">
    <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" institution="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>
          <status>DONE</status>
          <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

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.

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.

Please see the XML example on the right pane.

Extra data for imports from Czech banks

Response with extra data

<?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" institution="Alior">
    <progress><value>97</value></progress>
    <result>
      <moneyTransactions>
        <moneyTransaction>
          <!-- ... standard tags ... -->
          <transactionOn>2012-06-28</transactionOn>
          <!-- ... other standard tags ... -->
          <!-- ... extra data - variableSymbol and constantSymbol:
          only for Czech bank accounts -->
          <variableSymbol>1234567890</variableSymbol>
          <constantSymbol>99999</constantSymbol>
        </moneyTransaction>
        <!-- ... more transactions ... -->
      </moneyTransactions>
    </result>
  </command>
</reply>

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.

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  https://test.api.kontomatik.com/v1/command/import-credit-cards.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="ImportCreditCardsCommand"/>
</reply>

Final response for this command status (scraper target example)

<?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>
          <cardId>1234 1234 1234 1234</cardId>
          <iban>PL32114020040000320250132522</iban>
          <number>1234 1234 1234 1234</number>
          <currencyBalance>-2467.39</currencyBalance>
          <currencyName>PLN</currencyName>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
            <owner>
               <name>Adam Nowak</name>
               <address>Robocza 1 M.14 Warszawa PL</address>
            </owner>
          </owners>
          <limit>5000.00</limit>
          <interest>20</interest>
          <dueDate>2013-10-26</dueDate>
        </creditCard>
       <!-- ... more credit cards ... -->
       </creditCards>
    </result>
  </command>
</reply>

Final response for this command status (PSD2 API target example)

<?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>
          <cardId>PL32114020040000320250132522</cardId>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>-2467.39</currencyBalance>
          <currencyName>PLN</currencyName>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
            <owner>
               <name>Adam Nowak</name>
               <address>Robocza 1 M.14 Warszawa PL</address>
            </owner>
          </owners>
          <limit>5000.00</limit>
          <interest>20</interest>
          <dueDate>2013-10-26</dueDate>
        </creditCard>
       <!-- ... more credit cards ... -->
       </creditCards>
    </result>
  </command>
</reply>

Import Credit Card Transactions (command)

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

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "sessionId=999999" \
  --data "sessionIdSignature=ffff....ffff" \
  --data "since=YYYY-MM-DD" \
  --data "cardId=2345***32" \
  https://test.api.kontomatik.com/v1/command/import-credit-card-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="ImportCreditCardTransactionsCommand"/>
</reply>

Final response 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_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>
          <labels>
            <label>internal</label>
          </labels>
        </moneyTransaction>
        <!-- ... more transactions ... -->
      </moneyTransactions>
    </result>
  </command>
</reply>

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.

Sign Out (command)

Request

curl \
  --header "X-Api-Key: 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

HTTP Response

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

Cancel command

Request

curl -X POST \
 --header "X-Api-Key: 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

Data

Request

curl --get \
 --header "X-Api-Key: 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" officialName="mBank" institution="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> <!-- deprecated -->
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Kwiatowa 8/97 Warszawa  PL</address>
              <kind>OWNER</kind>
            </owner>
          </owners>
          <owners>
            <owner>
              <name>Adam Nowak</name>
              <address>Robocza 1 M.14 Warszawa PL</address>
              <kind>CO-OWNER</kind>
            </owner>
          </owners>
          <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>
                <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

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

Request

curl -X DELETE \
 --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
 --data "ownerExternalId=222222" \
https://test.api.kontomatik.com/v1/owner.xml

Response

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

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 \
  --header "X-Api-Key: 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>
          <!-- 0..1 value representing estimated creditworthiness of an individual (the higher the better) -->
          <value>0.03282</value>
        </score>
        <scorePercentile>
          <!-- 0..1 value representing population percentile (the higher the better) -->
          <value>0.49824</value>
        </scorePercentile>
      </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>
          <!-- 0..1 value representing estimated creditworthiness of an individual (the higher the better) -->
          <value>0.9717</value>
        </score>
        <scorePercentile>
          <!-- 0..1 value representing population percentile (the higher the better) -->
          <value>0.81069</value>
        </scorePercentile>
        <scoreTier>
          <!-- rank of the client -->
          <value>TOP TIER CLIENT</value>
        </scoreTier>
      </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 (<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 or equal to - 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

Our example lender-specific score achieved Gini 0.56 (AUC 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

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.

Input Features

Request

  curl --get \
    --header "X-Api-Key: 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" relevance="0.8" />
        <feature id="59ab5c6f97" value="2.00355" relevance="0.3" />
        <feature id="03d10dbf0a" value="1.932" relevance="1.5" />
        <feature id="ec4207aaf2" value="NaN" relevance="0" />
        <feature id="b31711374c" value="-INF" relevance="-2" />
        <feature id="ddb0ebf93a" value="INF" relevance="5.3" />
        <!-- ...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" relevance="0.8" />
        <feature id="59ab5c6f97" value="2.00355" relevance="0.3" />
        <feature id="03d10dbf0a" value="1.932" relevance="1.5" />
        <feature id="ec4207aaf2" value="NaN" relevance="0" />
        <feature id="b31711374c" value="-INF" relevance="-2" />
        <feature id="ddb0ebf93a" value="INF" relevance="5.3" />
        <!-- ...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-specific historical repayment data.

HTTP Request

GET /v1/owner-features.xml

Parameters

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:

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

Compensation

Debt

State

Cash

Lifestyle

Living

Aggregated Values

Request

curl --get \
  --header "X-Api-Key: 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="https://developer.kontomatik.com/schema/v1/aggregates.xsd" status="200 OK" user="user-name" ownerExternalId="123456">
  <owner externalId="123456">
    <target name="MBank" officialName="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

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:

Labeling Aggregates

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

Concerning <account>:

Concerning <month>:

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

Kontomatik offers a zero-integration solution for manual risk-assessment.

To use Insight, developers just need to enable auto-import flag in the Widget and pass an ownerExternalId 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.

• Call Data command, passing the ownerExternalId parameter that identifies the user.

You're done!

Receive digitally signed responses

Request

curl -i --header "Accept-Signature: SHA256withRSA" https://test.api.kontomatik.com/isItWorking

Response

HTTP/2 200
date: Mon, 22 Jul 2019 08:33:49 GMT
content-type: text/plain; charset=utf-8
signature: keyId="/lFnNTJnq5TpDe/wETLXGfdoVN4=",algorithm="SHA256withRSA",headers="",signature="Ivoy+iAygdWCDCtr7GZZVRiozjsHaenwYrqcovMe5LBueiDgNsPzxi9respDKLaLmjFTH2s1BEsjOXfvJIvsX9Rba8xy0hoz/nfpm/RS47cSAJKux6Aq1Esl6efFzLJwPPvOpUccI3D9GHB+gdPBJOgWHrLHZaIcv4Oh2QdO7hVyqEOEP3+MwQo71uX+nPwbrvx39QX2t1dmUQyOFCDbf8+Ea5t4WKnm3kq8ybEriRPfKtOkFWK9juaHP6YjdGfUxGH6Z3vXSrLU+CPw5KeBylWQoOtYEm1osaI0PaPgMheT2ooeV/y4kfe2gBujh+HmlrGvsI1hdTe0VH1yA4fZBQ=="
cache-control: no-cache
x-frame-options: DENY
x-content-type-options: nosniff
strict-transport-security: max-age=31536000

Kontomatik can send digitally signed responses to prove authenticity and message integrity.

To elicit a signed response, an Http request must have an Accept-Signature header with value SHA256withRSA.

In the response you will receive a Signature header with the following values:

Kontomatik public RSA key is available here.

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.

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.

Here is the pseudocode version of the algorithm to create the keyId:

• store a byte array representation of the key modulus into variable n
• store a byte array representation of the key exponent into variable e
• store a byte array representation of string 'ssh-rsa' into variable tag
• init variable buffer to a byte buffer
• put integer tag.length into buffer
• put tag into buffer
• put integer e.length into buffer
• put e into buffer
• put integer n.length into buffer
• put n into buffer
• store the SHA1 hash of the bytes in buffer into variable result
• return Base64.encode(result)

Verify a digitally signed response

The following is an example how to verify a digitally signed response from Kontomatik.

Please go to a directory of your choice and store the Kontomatik public key in a file named kontomatik.pub.

$ curl https://get.kontomatik.com/keys/kontomatik.pub -o kontomatik.pub

Send a request to Kontomatik service and save the response body to a file. Use -D option to save the response headers into another file.

$ curl -s -H "Accept-Signature: SHA256withRSA" -D headers.txt -o response.txt https://test.api.kontomatik.com/isItWorking

Use the following to extract and decode signature value from the Signature response header:

$ sed -En 's/^signature: .*signature="([^"]*).*/\1/p' headers.txt | base64 --decode > signature.data

Now we can verify the response body using the signature data and public key of Kontomatik:

$ openssl dgst -sha256 -verify kontomatik.pub -signature signature.data response.txt

The output should be Verified OK.

Testing

Kontomatik provides mock responses for all commands in PSD2 API mock bank KontoBank and all screen scraper banks listed in our widget in the demo environment,

The methodology of providing these mock test responses for banks is to showcase the interaction between the widget and a bank and to provide you with a tool to analyze your integration performance in detail. Additionally, the PSD2 API KontoBank imitates the bank’s login process so you may experience how the PSD2 API flow looks like in our Banking API.

Create a test session manually

To create a mock session manually, select the target in the SignIn Widget and provide the following credentials:

• for testing screen scraping bank: enter test as first credential
• for testing KontoBank: enter test1 or test2 or ..., test10 as first credentials - there are 10 accounts you can choose from, returning different data.
• enter Test123 as second credential
• enter Test123 as third credential (if required)

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 or in case of KontoBank you are redirected to simulation of the bank login website. An HTTP request to the bank is neverteless made, to check connectivity.

It is also possible to mark "Test credentials" checkbox on the bank selection list; in this case you can use an arbitrary login string as the first credential. Please note this option is available only for selected clients.

Create a test session (command)

POST /v1/test-session.xml

To enable automatic testing, Kontomatik also provides a mechanism to obtain an already-authenticated mock session. This command bypasses the manual login flow described above.

Request

curl \
  --header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
  --data "target=pko" \
  --data "sessionIdSignature=true" \
  https://test.api.kontomatik.com/v1/test-session.xml

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 ownerExternalId parameter.

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.

Kontomatik-widget-android-poc is an example where we explore the general concept of displaying Kontomatik Widget in native mobile applications. The example focuses on the simplest and effective way of displaying Widget through the use of WebView, which is an embeddable browser that a native application can use to display content.

PSD2 Transition Period

New Targets

During transition period Kontomatik will steadily connect to banks in Europe via API interfaces. Kontomatik will return data under different targets depending on the type of connection - Screen Scraping or PSD2 API. Therefore we introduced a notion of institution, which is described more precisely in institution description.