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.
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
- 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
.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 support@kontomatik.com.
Importing data
In this section you will find basic information on how to import the end-user's financial data using our solutions:
Single access - the easiest way to get all financial data
Multiple access - for getting consent from user for continuous access to their account for 90 days
Advanced Import - for more complicated importing flows
Error handling - how to manage errors returned by different API endpoints
Best practices and other tips&tricks
Single access
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.
Multiple access (beta)
If you require continuous access to the end-user’s data, you can get it by using Multiple access service.
Important information before you integrate:
- The service is not enabled by default and requires signing an agreement with a separate fee than for standard account information service.
- The access is given for up to 90 days. The period can be shortened if either the bank or the user revoke the access earlier.
- Using Multiple access you can import up to 90 days of transactional history. If you require access further back, you need to ask the user for a Single access and then go through the Multiple access process separately.
- Using Multiple access you can import data up to 4 times in a 24 hour timeframe. This number can be lower if the user gave his account access to another company as well.
Availability:
- The service is in a beta phase so more errors than usual might occur.
- Only specific banks support this feature - visit this document , the targets using this feature will be marked “Yes” in the “Multiple access” column.
- Feature is not available for auto import flow (zero integration solution).
The feature works only for PSD2 API targets:
- if a target is working on a Fallback connection, you won’t be able to get a Multiple access from the user;
- if a bank is available in both PSD2 and Fallback versions, if you use the Fallback version for Single access, you won’t be able to use Multiple access for that bank;
- if you already have the API access, you can find out which targets enabled for you support this feature by fetching Catalog - targets with the feature will have
ReuseMultipleAccessAction
included.
How does it work?
Use The SignIn Widget similarly to how you would in a Single access mode, but add/set the accessMode parameter to either MIXED or MULTIPLE value as described in the Embedding the widget section.
When the end-user successfully logs in, apart from other parameters, you’ll also get a multipleAccessId that you also need to pass to your backend and save for the future.
You can perform an import right away.
If you want to access data again later, use reuse Multiple access command to get a new sessionId and sessionIdSignature and perform an import again, preferably using Default Import.
Which mode should I use?
- MULTIPLE - if you require Multiple access from the end user to their account.
- MIXED - for when you accept both Single and Multiple access mode - after the user logs in you will either get the “multipleAccessId” parameter or not.
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
Response (example)
<?xml version="1.0" encoding="utf-8"?>
<reply status="404 Not Found" user="multiple-access-user">
<exception name="InvalidMultipleAccessId">
<message>Multiple access token not found. It may have expired or provided ID is invalid.</message>
</exception>
</reply>
Command execution may fail due to causes beyond our control. Temporary unavailability of the bank and expired sessions are just two examples of what can go wrong.
Exception | Description |
---|---|
IOException | Network issue between Kontomatik and bank occurred. For example the bank failed to respond in a timely manner. What to do: retry command that failed up to 3 times, then give up and ask user to try again later. |
SessionExpired | The session with the online transaction system has expired. What to do: ask the user to try again (show the widget step) and to not use the bank manually at the same time as parallel sessions can kill each other. |
ConcurrentSessionsLimitExceed | User has not signed out and second session cannot be started until the abandoned one expires. What to do: ask the user to try again (show the widget step) in a few hours. |
ServiceTemporarilyUnavailable | Online transaction system is temporarily unavailable. What to do: ask the user to try again in a few minutes because his online banking is temporarily unavailable. |
ServiceMaintenance | Online transaction system under maintenance. What to do: ask the user to try again in a few hours because his online banking is undergoing planned maintenance. |
InvalidMultipleAccessId | Multiple access expired or provided multipleAccessId is otherwise invalid. What to do: make sure the multipleAccessId is correct and if it is, ask the user to grant Multiple access again via the SignIn Widget. |
MultipleAccessLimitExceeded | The number of imports allocated for 24 hours has been exceeded. What to do: wait until 24 hours pass from the first session creation of the last four successful Reuse Multiple access calls. |
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 (e.g. if client keeps polling a command that entered in a final state, after 60 seconds we return InvalidCommandId) |
InvalidOwnerExternalId | Invalid identifier of the data owner |
NotSignedIn | Only signed-in user can call the command |
AlreadySignedIn | You cannot sign-in twice in the same session - start a new session |
DefaultImportAlreadyExecuted | Default Import has been executed once in this session, subsequent execution failed. |
InvalidIban | Invalid bank account number (e.g. empty, incorrect syntax) |
InvalidTarget | Invalid target identifier |
InvalidSessionId | Invalid session identifier (e.g. client calls the production endpoint with a session created on the test environment) |
InvalidSessionIdSignature | One or both of sessionId and sessionIdSignature passed parameters were malformed |
InvalidSince | Invalid start date |
JobsQuotaExceeded | Your app has started too many imports simultaneously. What to do: wait for 10-15 seconds to allow some of the imports to finish and resubmit the command. If you get the same error, repeat the process until the command is accepted. |
Bugs in Kontomatik
The following should be considered bugs in the Kontomatik Service. Most likely, some edge case condition occured and our software was not prepared for this. Kontomatik should be improved to cover this case. You may want to excuse your user and redirect him to the other path.
In case of a SaaS deployment we will be automatically notified so you don't have to take any action. In case of self-hosting these errors should be reported to support@kontomatik.com, attaching the XML reply and logs of the application server.
There are two scenarios to consider:
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. |
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.
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. What to do: let the user try again entering 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. |
PSD2AuthProcessInterrupted | (beta) Indicates that the auth process has been abruptly stopped by an external factor or agent, very often the end user himself: closing the pop-up window, rejecting consents on the bank page or providing bad credentials are common causes of this error. |
InvalidCardNumber | The error happens during ImportCreditCardTransactions action when the credit card number provided by the user in the curl command is not found. |
LoginTimedOut | Process of authentication has timed out. What to do: let the user try again entering credentials. |
UnsupportedBrowser | The user is using an unsupported browser or outdated browser version. |
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.
What you want to achieve | param: 'maxImportDate' | param: forceSca |
---|---|---|
Getting more than 90 days of transactions (may lower conversion rate). | Date in YYYY-MM-DD format higher than 90 days. | True |
Getting transactions older than 90 days only from banks that don’t require additional SCA. From other banks that require SCA, you will get up to 90 days of history. | Date in YYYY-MM-DD format higher than 90 days. | False |
Getting transactions up to 90 days old. | Date in YYYY-MM-DD format lower than 90 days. | True/False |
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.
Make sure that both the WebView with iframe and the WebView which loads the banks page in the popup have these features enabled:
- Iframe WebView:
- Javascript
- Javascript can open windows automatically
- Multiple windows are supported
- Popup WebView:
- Javascript
- DOM Storage
When the widget is embedded in the native app and the user changes the font size in the system settings on their Android phone, the widget may become unusable. To make it usable but sacrificing the look of the UI, the client can set the dynamicHeight
embed the SignIn Widget parameter to true
in the widget.
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.
Advanced import flow
When using Single or Multiple access, after getting session parameters necessary to perform an import, instead of using Default Import command, you can instead use Advanced import commands that let you manually manage which information and when is imported.
For example, you don’t need each transaction from the end-user’s account, you just want to get KYC information and IBANs he has in his online banking. You can then go through your online process as usual.
There are some things you need to know before you consider using this type of importing flow:
It’s harder to integrate with and more error-prone as you manually have to manage each command as well as remember most of them cannot be performed simultaneously.
Getting all the data will be slower than when using Default Import, except for when you use it only to get some data.
If within a session you get some information at the start using Advanced Import commands, you can’t finish getting all of it by using Default Import - in most cases you will receive an error from our API.
Follow the tutorial for more information.
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 renderedCall 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:
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 lt lv ee. |
locale | en | Determines end-user interface language. Accepted values: cz en es et it pl pt ru lt lv. |
target | null | Pre-selects the bank. If omitted, the bank drop down list will be shown. Accepted values: check target name attribute in Catalog command response. |
ownerExternalId | null | Your own arbitrary identifier of the end user. For a lender, this might be your loan application id. If you are a bank, a credit application id might be appropriate. If you are a PFM vendor, this could be your end-user database id. Passing this param is highly recommended. It allows you to group all imported data and fetch them together, even if they span across multiple Kontomatik sessions. |
showFavicons | false | Set to true to show banks' favicons in a drop down list. Makes it easier for the end user to find a bank. Also it looks more appealing and professional. This is off by default because using bank logotypes can be a grey area in some jurisdictions. |
showScreenshots | true | By default, screenshot of bank's login page is displayed. Set the value to false if you do not wish the widget to display screenshots. |
showBetaQualityLabels | true/false | Option to toggle the visibility of beta quality labels for beta quality targets. Please note the default is true on the test environment and false on production. This is an exception that breaks the symmetry between test and production. |
showTargetMissingOption | true | By default, "My bank is not listed..." option is displayed on the bank selection list. Set the value to false if you do not want this option to show up on the list. |
showTargetMissingForm | true | Option to control whether the user who clicked on "My bank is not listed..." option is then redirected to a form prompting the user to enter the name and url address of the unsupported bank. Passing false enables you to handle this scenario however you prefer. |
showDefaultTarget | true | The widget displays a bank with a large market share as the default value of the bank selection list. If instead of a default target you prefer to display the message Select from list, set showDefaultTarget to false . |
dynamicHeight | false | If set to true, the <iframe> height will change based on the content of the element. This feature is currently in beta state. |
styles | null | Optional object defining the look and feel of the widget. For more information please refer to styling the widget section. |
PSD2 params (beta version, might change in the nearest future)
<!-- index.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: {
accessMode: `SINGLE`,
forceSca: true,
maxImportDate: '2019-01-01',
polishApiSpecific: {
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:
Parameter | Default | Description |
---|---|---|
accessMode | SINGLE | (beta) possible values: SINGLE, MULTIPLE, MIXED Filters the target catalog:
|
multipleAccessEmail | null | (Multiple access mode only) Pass on the end-user's email address to the Widget, can be changed by the user in the login process. The address is required for Kontomatik to provide Multiple access service to the user. |
polishApiSpecific | null | Object containing fields specific to PolishAPI standard. Read further for more information. |
maxImportDate | null | maxImportDate is the lower limit of the date range in which transactions imported can occur, whereas the current date is the upper limit. Meaning that the transactions will not exceed the range of maxImportDate;today. A date passed in the since parameter during importing commands will be trimmed to the date provided in the Widget. |
forceSca | false | In supported banks enables Strong Customer Authentication (SCA) by introducing extra steps which would be an additional consent and authentication of an end-user in the purpose of fetching higher than 90 days of the transaction history. The parameter supports true/false value depending on what effect we would like to achieve. |
The embedKontomatik()
function takes an additional (optional) parameter polishApiSpecific
inside psd2
parameter which contains an object with properties specific to PolishAPI standard:
Parameter | Default | Description |
---|---|---|
transactionsStatuses | ['DONE'] | It is possible to specify one or multiple dictionary values: ALL , DONE , PENDING , REJECTED , SCHEDULED , HOLD . Each value limits the scope of imported transactions. If more than one value is passed then the logical OR is applied. |
consentTimeLimit | 60min/90days single/Multiple access | (beta) Consent validity period. Format: ISO 8601 duration format (e.g. PT1H - 1 hour). This field is to be used only by AIS entities. |
Callbacks
Signin Widget provides a set of several callbacks, which are invoked when widget enters a new state or an important event takes place. It should be emphasized, that you only need to implement the onSuccess callback.
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. |
onSessionCreated | no | Invoked after the session has been successfuly created. Please see onSessionCreated callback description for more details |
onConsentsGiven | no | Invoked when the user gives consents necessary for the provision of the service. Please see onConsentsGiven callback description for more details |
onCredentialEntered | no | Called after user enters credential. Please see onCredentialEntered callback description for more details. |
onRedirect | no | Called after the user is redirected to the bank's page (only in PSD2 API). Please see onRedirect callback description for more details. |
onReset | no | Called after the user clicks "Try again" button. Please see onReset callback description for more details. |
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.
The options object contains the following properties:
Property | Available | Description |
---|---|---|
officialName | always | the full bank name |
multipleAccessId | only for Multiple access | (beta) An identifier of the Multiple access, used to extract sessionId for consecutive imports without the end-user login (in the background). accessMode param in the Widget has to be set to MULTIPLE or MIXED for this parameter to be generated. |
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 | after session creation | an identifier of the bank the end user has attempted to sign into |
sessionId | after session creation | an identifier of the session that has resulted in an error |
officialName | after session creation | 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 |
onSessionCreated callback
The onSessionCreated callback is called after the session has been successfuly created. The callback will be passed an object with the following properties:
Property | Description |
---|---|
sessionId | identifier of the Kontomatik session |
onConsentsGiven callback
The onConsentsGiven callback is called after the users selects all required consents and clicks the "Next" button.
onCredentialEntered callback
The onCredentialEntered callback is called when user entered credential and clicked the "next" button.
onRedirect callback
The onRedirect callback is called after the user is redirected to the bank's page. This takes place only during the PSD2 auth process.
onReset callback
The onReset callback is called after the user clicks the "Try again" button.
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.
Importing API reference
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>jankowalski@xgmail.com</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
Parameter | Default | Description |
---|---|---|
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, 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" \
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 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 |
---|---|---|
id (in path) | 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. |
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. |
Reuse Multiple access (command) (beta)
Creates a new session with a target for existing multipleAccessId, which can be used to import end-user’s data again. Closes all existing sessions for that user if any are still active.
New session for the same user can be created up to 4 times in a 24 hour period.
HTTP Request
POST /v1/command/reuse-multiple-access.xml
Request
curl \
--header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
--data "multipleAccessId=ffff....ffff" \
https://test.api.kontomatik.com/v1/command/reuse-multiple-access.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/reuse_multiple_access.xsd" status="201 Created" user="multiple-access-user" ownerExternalId="tgglv6mpgsacsiclc4ckj97acknt2rblqah5l9nj">
<session id="3868" signature="3be8d15144544faf3ecad099aa66468902a8a29515a8d72134d67b88c9b3ee52"/>
</reply>
Parameters
Parameter | Default | Description |
---|---|---|
multipleAccessId | obligatory | Parameter returned by the SignIn Widget after successful logging in within options object when the target was used in the Multiple access mode. |
Data returned
Description of <session>
element:
Attribute | Availability | Description |
---|---|---|
id | guaranteed | an identifier of the Kontomatik session |
signature | guaranteed | signature created for the sessionId to detect any attempt to tamper with its value |
The attributes are equivalent to sessionId and sessionIdSignature returned by onSuccess callback by the SignIn Widget. Other parameters that onSuccess would pass are not returned as they don’t change after the first session handled by the widget.
Get aggregated 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>jankowalski@xgmail.com</email>
<citizenship>PL</citizenship>
<nationality>polska</nationality>
<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>
<creditCards>
<creditCard>
<name>Lux Credit MasterCard</name>
<cardId>5390********6217</cardId>
<iban>PL09807410131232175240357841</iban>
<number>5390********6217</number>
<currencyBalance>-213.59</currencyBalance>
<currencyFundsAvailable>783.370</currencyFundsAvailable>
<currencyName>PLN</currencyName>
<owner>Jan Kowalski</owner>
<limit>1000.00</limit>
<interest>15.20</interest>
<dueDate>2014-06-01</dueDate>
<moneyTransactions>
<moneyTransaction>
<transactionOn>2020-12-05</transactionOn>
<bookedOn>2020-12-06</bookedOn>
<currencyAmount>-100.99</currencyAmount>
<currencyBalance>1000.00</currencyBalance>
<title>Credit Card Transaction 4814 POL Warsaw payu (R4nD)</title>
<party>Payu, POL Warszawa payu</party>
<partyIban>PL76103011623052268948576932</partyIban>
<kind>Credit Card transaction</kind>
<status>DONE</status>
<variableSymbol>6789</variableSymbol>
<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>
</owner>
</owners>
</creditCard>
<!-- ... more credit cards ... -->
</creditCards>
</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 |
---|---|---|
ownerExternalId (in query) | obligatory | Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in Widget. |
only (in query) | 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-owners, import-accounts, import-account-transactions, import-credit-cards and import-credit-card-transactions commands.
Furthermore, the <account>
tag contains a list of transactions associated(#import-accounts-command) with the given account.
For a detailed description of data structures encapsulated by the <owners>
, <accounts>
, <creditCards>
, 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.
Parameter | Default | Description |
---|---|---|
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.".
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 country="pl" name="KontoBankApi" institution="Kontobank" officialName="KontoBank" officialUrl="https://bank.kontomatik.com" beta="true" psd2="true">
<supportedAccountTypes>
<supportedAccountType name="Individual"/>
</supportedAccountTypes>
<commands>
<command name="ImportCreditCardTransactionsCommand"/>
<command name="ImportAccountTransactionsCommand"/>
<command name="ReuseMultipleAccessCommand"/>
<command name="ImportCreditCardsCommand"/>
<command name="DefaultImportCommand"/>
<command name="EnterCredentialCommand"/>
<command name="ImportOwnersDetailsCommand"/>
<command name="ImportAccountsCommand"/>
</commands>
<credentialsMetadata>
<credentialMetadata kind="API_SETUP">
<name></name>
<supported>true</supported>
<asterisked>false</asterisked>
</credentialMetadata>
</credentialsMetadata>
</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 |
---|---|---|
country (in query) | 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 (in query) | 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 | Availability | Description |
---|---|---|
country | guaranteed | country where the bank is located |
name | guaranteed | an internal unique identifier for the following pair: bank and it's connection interface |
institution | guaranteed | a general identifier of the bank as an institution (Millennium and MillenniumApi target names will share the same institution field - here Millennium) |
officialName | guaranteed | full bank name |
officialUrl | guaranteed | bank web address |
loginName | possibly none | the place holder for first supported login parameter |
beta | possibly none | informing users that this target is either a new introduced target or it is still under development. The client may expect that there can be some flaws in performance. The beta parameter is removed once some time passes and when there has been some significant volume going through a target |
psd2 | possibly none | is a declaration, that in a session with a specific target, Kontomatik acts as AIS (account information services) under regulation of PSD2 directive |
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.
Advanced Import
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.
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>jan.kowalski@wachock-mail.pl</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.
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 |
---|---|---|
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.
Data | Availability | Description |
---|---|---|
kind | guaranteed | one of: OWNER, CO_OWNER, COMPANY. OWNER is the natural person shown as the main account owner, for example in the profile page. CO_OWNER is a co-owner of one of the bank accounts with full access to that specific bank account. COMPANY is the legal entity shown as the main account owner. If it's not possible to determine the main owner, all found persons will be marked as OWNER. |
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 |
possibly none | ||
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 \
--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
Parameter | Default | Description |
---|---|---|
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 | (deprecated, to be removed on 1/04/2022) 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. Please don't use this tag as it will be removed on 1/04/2022 and replaced with the |
owners | available except for exceptional circumstances | structured list of all owners represented as a separate owner tag with name , address and kind of each owner for the given account as supplied by the bank system. For a detailed description of the owner tag element see the relevant information in Data returned in owner tag. The information can originate either from account details or from outgoing transfers. The field is filled in more than 99% of cases. In rare circumstances it can be empty, e.g. all 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. We recommend using this tag instead of owner . For now, both tags will be returned. |
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. |
Data returned in owner
tag
Data | Availability | Description |
---|---|---|
name | available except for exceptional circumstances | name of the owner of the account as presented in the online transaction system |
address | possibly none | address of the owner, as presented by the 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 |
kind | possibly none | owner type, as presented in the online transactions' system (e.g. “OWNER/CO-OWNER/COMPANY”) |
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
Parameter | Default | Description |
---|---|---|
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 | possibly none | full account number of the other party of the transaction; guaranteed for transactions with a non-empty party attribute; always unavailable for certain transactions, e.g. card payments, bank fees and commissions |
party | possibly none | the name of the other party of the transaction; always unavailable for contra-entry type transactions |
title | possibly none | transaction title |
kind | possibly none | transaction type, as presented in the online transaction system (e.g. "INTEREST COMPOUNDING") |
status | possibly none | (beta) transaction status, can take one of the following values DONE, PENDING, REJECTED, SCHEDULED, HOLD |
labels | possibly none | list of transaction's labels. See Transaction labeling for more information |
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
Data | Availability | Description |
---|---|---|
variableSymbol | possibly none | identifier used for payments in Czech Republic (variabilní symbol) |
constantSymbol | possibly none | identifier used for payments in Czech Republic (konstantní symbol) |
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</cardId>
<iban>PL32114020040000320250132522</iban>
<number>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>
Parameter | Default | Description |
---|---|---|
sessionId | obligatory | Session identifier. |
sessionIdSignature | obligatory | Security parameter to prevent session enumeration. |
Data | Availability | Description |
---|---|---|
name | guaranteed | card name, as stated in the bank’s system |
cardId | guaranteed | For screen-scraper targets, the cardId value is equal to the card number; for PSD2 API targets, the cardId value is the IBAN number |
iban | guaranteed | the account number of the bank account linked to this credit card |
cardNumber | optional | 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. |
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 | (deprecated, to be removed on 1/04/2022) name of the credit card holder, as presented in the online transaction system |
owners | possibly none | structured list of all owners represented as a separate owner tag with name address and kind of each owner for the given credit card as supplied by the bank 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
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.
Parameter | Default | Description |
---|---|---|
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 |
cardId | obligatory | identifies the credit card for which the transactions should be fetched. Use the cardId value returned by the import-credit-cards command. |
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") |
Sign Out
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
Parameter | Default | Description |
---|---|---|
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.
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
Parameter | Default | Description |
---|---|---|
ownerExternalId (in query) | obligatory | Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in widget. |
Data returned
Critical:
Pick specific
<model>
byid
. 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
Parameter | Default | Description |
---|---|---|
ownerExternalId (in query) | obligatory | Your identifier for the end user, that you passed as one of the parameters to Kontomatik Sign-in widget. |
Data returned
It is critical to pick specific <model>
by id
.
Model id
stabilizes feature semantics. The same set of features will be present and feature semantics won't change. With the new model (new id
) everything is reset. Lending company must then re-check which features are predictive. New version of the model will offer a new set of features to pick from. Features present in the old version are not guaranteed to be present in the new version. Typically, new model replaces many features with more powerful alternatives.
Model retrainedAt
attribute describes the training dataset. The same model can be re-trained on the new dataset (the larger and more current one). Feature set and semantics stay the same. Lending company does not need to take any action when the model is retrained. The timestamp format is ISO 8601.
Every <feature />
contains the following structure:
Data | Availability | Description |
---|---|---|
id | guaranteed | Unique identifier of the feature. It is guaranteed to be stable across model retrains (but not across model versions). |
value | guaranteed | Decimal value of the feature in range <-∞, +∞> inclusive. Possible values are a number, -INF , INF , NaN (see xs:double). The value is standard deviation from the population. Using standard deviation instead of base units allows for the same treatment of all kinds of units like amounts, counters, or ratios. Standard deviations themselves are also normalized (scaled to the same distribution) across all features so they can be treated consistently. |
relevance | guaranteed | Decimal number representing how much the feature influenced the final score of the client; a positive value means that the feature worked in favor of the client repaying, while a negative value means the feature worked in favor of the client defaulting. Only numeric values are possible - NaN or INF are not allowed. Relevance "0" means the feature did not influence the outcome at all. |
How to use features in existing scoring model?
Kontomatik publishes hundreds of features that can be potentially predictive in your context (your customers and your scoring model).
You are not expected to understand semantics of individual features published by Kontomatik. Please do not attempt to apply domain expert knowledge to manually assess and combine Kontomatik features into your scoring model.
The correct approach is to test all features on your real world loans using your existing scoring model.
Once predictive and independent features have been identified, apply them to your scoring model along your own input features.
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 |
overdraft recovery | income | transactions that helped to have the non-negative account balance again |
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; often combined with return |
loan company | both | transactions to and from non-bank lending companies |
bank | both | transactions to and from banks |
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 more general than salary |
pension | income | payments of retirement money received from the state |
extra pay | income | transfer of money from a company to an individual which is more than a regular salary, such as overtime payments, discretionary bonuses, reimbursements for work travel expenses etc. |
regular wage | income | another recurring revenue |
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 | expense | transactions indicating a mortgage repayment |
leasing | expense | transactions indicating a leasing repayment |
repayment | expense | repayment of a debt, such as loan installment or credit card 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 |
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, 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, e.g. tax return |
krus | both | transfers suggesting that it is a corporate transfer (one of social insurance types, only for Poland) |
vat | both | transfers describing VAT transactions (one of tax types, only for Poland) |
zus | both | transfers suggesting that it is a corporate transfer (one of social insurance types, only for Poland) |
pit | both | transfers describing PIT transactions (one of tax types, only for Poland) |
unemployment benefit | income | government support for the unemployed |
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 (e.g. Uber, Taxify, Lyft), carpooling services (e.g. BlaBlaCar) and car rentals (e.g. Panek) |
tobacco | expense | indicates products bought 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, e.g. gambling gains |
alcohol | expense | spirits and liquor stores, online alcohol shops |
beauty | expense | cosmetics, pharmacy, perfume shops, barber and hairdresser, manicure and pedicure salons, basic hygiene expenses; does not cover: apparel spendings |
culture | expense | events, concerts, museums, cinema, theaters, festivals, escape rooms, zoo visits, and similar; does not cover: does not cover transport and traveling |
insurance | both | mandatory or optional insurance of any type, both expense and income transactions (e.g. overpayment return or insurance indemnity) |
life insurance | both | life insurance fee outgoing transfers, both expense and income transactions (e.g. overpayment return or life insurance indemnity) |
payment processor | both | payment typically involving online card payment or a payment processor like PayPal, PayU, DotPay, Allegro, DialCom24 etc. |
express transfer | both | transactions with titles, which indicate that it was an express transfer. BLIK online and phone payments work like express transfers. |
food with delivery | expense | home food delivery (e.g. Pyszne.pl or Uber Eats) |
charity | both | transfers describing charity transactions |
education | both | education related outbound transactions (courses, university fee, academic, school trips), but also incoming transactions like grants or scholarships; does not cover: books |
postal service | expense | outcoming postal transactions (e.g. Inpost, Poczta Polska, DHL, DPD) |
university | both | outgoing transactions that are expenditure on higher education and incoming transactions like scholarships |
accountancy | expense | payments for accounting services |
Living
label | direction | description |
---|---|---|
rent | both | payment of rent for house, apartment, student housing etc; also receiving money for renting out to someone |
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 and SPA |
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 (e.g. tax returns) or consumer goods returned at the store |
e commerce | expense | buying stuff online, for example Amazon, AliExpress, Allegro |
electronics | expense | consumer electronics, all physical and online stores, which have selling electronics as their primary business, for example MediaMarkt; also includes repair services and gadget shops; does not cover: electricity bills. |
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> <!-- deprecated -->
<owners>
<owner>
<name>Jan Kowalski</name>
<address>Kwiatowa 8/97 Warszawa PL</address>
<kind>OWNER</kind>
</owner>
</owners>
<!-- 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 |
---|---|---|
ownerExternalId (in query) | obligatory | Your identifier for the end-user, that you passed as one of the parameters to Kontomatik Sign-in widget. |
periodMonths (in query) | 13 | 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 and consist of booked transactions.
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 |
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
commandId
s.When all command statuses have turned to
successful
calldata
command passingownerExternalId
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:
Field | Description |
---|---|
keyId | A calculated ID of the public RSA key of Kontomatik |
algorithm | Algorithm used to calculate the signature. Currently only SHA256withRSA is supported. |
headers | Comma separated list of headers considered in the signature. For now, the list is empty. |
signature | Signature after Base64 encoding |
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
To test Kontomatik tools and API, you can create a test session manually or automatically. You’ll find descriptions of each in their respective sections below.
There are some notes that may concern both methods:
After you first sign your agreement with Kontomatik, you’ll get a test account and later on a production one. Endpoint addresses and client IDs for them are different as well as you’ll have to generate separate API keys for each and whitelist your servers IPs. You can switch between both IDs in Insight in the top left of the website.
Your testing client ID may have enabled more features than your contract includes. This is for you to test capabilities of the services you might have not wanted, but may test to extend your contract in the future. Please remember that some features might not be available on your production account.
We provide a mock bank called “KontoBank”. Depending on the country, you’ll see in the Widget a screen-scraping version, API version or both.
KontoBank includes up to 10 accounts per country with different data. In this document you’ll find the list of available accounts with some characteristics about them.
Labeling and scoring, if you have them enabled, work on the mock data as they would on real data imported from a production connection.
KontoBank works only in the testing environment. In production, you’ll have to use a real account that will not be provided by Kontomatik.
Connections to banks work exactly as they would on production, which means you can use your real credentials in presented targets. In case you do, please consider compliance and data protection aspects.
Differences between the testing and production environments in terms of how they work mainly involve configuration of available targets and services.
Create a test session manually
To create a test session manually, you’ll have to start by embedding the SignIn Widget on your website using your test server client ID.
For most countries you’ll have two targets available:
KontoBank - resembling a login process based on screen-scraping;
KontoBank (API) - a version that includes a redirection page opened in a new window, resembling a PSD2 API flow.
The credentials for both are as follows:
Login: test1, test2, … - according to the list in this document;
Password*: Test123;
SMS OTP*: Test123;
*Exceptions may apply for some accounts, please consult this document.
After you log in, the handling of the session is identical as it would be for the production environment - considering different test IDs, API keys, endpoint addresses etc.
Create a test session automatically
For automated testing, you can create a session using the endpoint that will return necessary information to continue the flow with the Banking API.
Request
curl \
--header "X-Api-Key: YOUR_LONG_API_KEY_HERE" \
--data "login=test1" \
--data "country=pl" \
--data "ownerExternalId=END_USERS_OWNER_EXTERNAL_ID" \
https://test.api.kontomatik.com/v1/mock-session.xml
Response (example)
<?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/create_test_session.xsd" status="201 Created" user="user-test">
<session id="000000000" signature="ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"/>
<credentialsMetadata></credentialsMetadata>
</reply>
POST /v1/mock-session.xml
Parameter | Default | Description |
---|---|---|
login | obligatory | KontoBank account login to be used for testing. Possible values: test1, test2, … - according to the list in this document, |
country | obligatory | Code of the country for which the account is used. Use the country code from this document corresponding to the account you want to test against. |
ownerExternalId | optional | 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. |
As a response you’ll receive a sessionId and sessionIdSignature.
Deprecated method
The method described below is due for removal on 1/04/2022. It is shown solely as a reference for clients migrating to the new version.
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
Parameter | Default | Description |
---|---|---|
target | obligatory | internal name of the banking target, as supplied by the catalog command |
ownerExternalId | optional | associates all imported data with the user (i.e. application number) |
sessionIdSignature | optional | a boolean flag, true by default, to determine whether Kontomatik will create and return a signature for the sessionId identifier |
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 support@kontomatik.com; 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.