Introduction

Overview

The Kontomatik PDF parsing API enables checking PDF statements against tampering attempts and parsing them to deliver clear banking data for credit scoring.

The common use case of this API is for assessing end-user creditworthiness. As such, the service requires user-uploaded PDF statements.

Please note that no end-user GUI for file upload is provided. You are expected to develop a user interface on your own.

Anti-tampering verification

Verification is done on every file upload via POST /v1/statement.xml. The following things are automatically checked against expected values:

• Digital signature. This is the most reliable method, but unfortunately at the moment only Santander signs the PDFs generated in their online banking system.
• Amounts consistency
  • Balances after transactions are consistent with transactions' amounts
  • The difference between initial and final balance equals to the sum of all transactions
• Metadata characteristic
  • Including but not limited to: producer, creator, paper size, format (PDF format version), title, subject, author, keywords etc.
• Fonts' family, color and size
• Bank logotype hash (the hash checking is equivalent to checking all image properties, metadata and picture)
• Header period is consistent with transaction dates
• Statement must include proper keywords

Clients can also use for verification the following values in the returned data:

• Owner (the parsed owner details should match the declared owner)
• Account number (the parsed IBAN number can also be used to check loan payout)
• Period (the parsed period should match the period requested by the client)

Supported targets

The PDF-parsing technology is currently available only in Poland. Coverage details are available here:

PDF-Parsing API - supported targets

API Conventions

• The character encoding for API requests and responses is UTF-8.
• XML element and attribute names use the camel case naming convention.
• Date and time parameters use YYYY-MM-DD and YYYY-MM-DD HH:MM:SS formats, respectively.
• 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 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 a test API we can whitelist a wildcard * IP address to make it easier for your developers.

Test environment

Start with the test environment to test and develop your credit scoring app. The test environment is fully-featured and unrestricted, returning real data. 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.

After you sign the initial agreement for access, you'll have to provide us with email addresses for Insight (Client Area online system). Once we create the test account for you, you'll have to generate an API key in Insight and start your implementation.

Production environment

The production API endpoint is:

https://api.kontomatik.com/

Once the agreement is signed, after we internally sort all documents, the production access will be created and you'll be able to configure it in Insight - including generating a production API key and whitelisting your production servers IP addresses.

Tutorial

We recommend you to get API access before reading further, if you haven't done so already.

For the purpose of this tutorial we assume that you are a lender (for example a bank or a lending company) and you need the data as input for your credit scoring engine.

Example flow:

• The lender informs the customer about the period for which the statements are requested for credit decision and how to properly export the statements.
• Customer signs in to his bank and manually exports/saves the PDF statement(s) on his desktop. Depending on the customer's bank, this is will be either a single PDF file or several of them, most likely one per month.
• Customer uploads PDF statements to the lender’s web application.
• Lender sends each PDF file to the Kontomatik Service using POST /v1/statement.xml with ownerExternalId parameter serving as the lender’s convenience id used to group data. This can be the lender’s internal credit-application-id. The ownerExternalId parameter will later be used to fetch all data associated with it. There is no need to specify the source bank. This will be recognized automatically.
• For each PDF upload to Kontomatik Service the lender checks the response.
• On error:
  • In case of verification error ask the customer to upload the correct PDF statement. See details in error handling.
  • In case of unexpected error submit a bug to the Kontomatik Team.
• On success:
  • Lender saves the returned customer-name and period.
• Once all PDF files are uploaded to the Kontomatik Service, the lender checks whether the customer-declared name matches the one from the statements and whether the periods cover the expected period.
  • On period mismatch, ask the customer to upload the missing statements (or to start over).
• Lender fetches all parsed data aggregated in one XML file using the GET /v1/data.xml call.
• Lender runs its credit scoring algorithm on the data.

API reference

Catalog

Request

curl --get \
  --header "X-Api-Key=YOUR_LONG_API_KEY_HERE" \
  --data "country=pl"
  https://test.api.kontomatik.com/v1/parser-catalog.xml

Response

<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://developer.kontomatik.com/schema/v1/get_parser_catalog.xsd" status="200 OK">
  <targets>
    <target name="Alior" officialName="Alior Bank"> </target>
    <target name="Bgz" officialName="BGŻ"> </target>
    <target name="Bos" officialName="BOŚ Bank"> </target>
    <target name="Bzwbk" officialName="BZWBK"> </target>
    <!-- other targets -->
  </targets>
</reply>

Returns the list of banks compatible with the PDF-parsing API (currently available only in Poland).

Parameters

Parse PDF statement

Test request

curl -H "X-Api-Key=<YOUR_API_KEY_FILE" \
     -F "pdfAsBase64=<YOUR_BASE64_ENCODED_PDF_FILE"
     https://test.api.kontomatik.com/v1/statement.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/statement.xsd" status="200 OK">
  <result>
    <statement id="12323423" isConsistent="true">
      <owners>
        <owner>
          <name>Jan Kowalski</name>
          <address>Krótka 8, Wąchock</address>
          <polishNip>1258882345</polishNip>
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <period>
        <startOn>2014-01-01</startOn>
        <endOn>2014-01-31</endOn>
      </period>
      <type>MONTHLY_STATEMENT</type>
      <target name="MBank">
        <accounts>
          <account>
            <name>eKONTO</name>
            <iban>PL32114020040000320250132522</iban>
            <owners>
              <owner>
                <name>Jan Kowalski</name>
                <address>Krótka 8, Wąchock</address>
                <kind>OWNER</kind>
              </owner>
              <!-- ... more owners ... -->
            </owners>
            <activeSinceAtLeast>2014-11-12</activeSinceAtLeast>
            <currencyBalance>1467.39</currencyBalance>
            <currencyName>PLN</currencyName>
            <moneyTransactions>
              <moneyTransaction>
                <transactionOn>2012-06-28</transactionOn>
                <bookedOn>2012-06-30</bookekOn>
                <currencyAmount>20.00</currencyAmount>
                <currencyBalance>1264.21</currencyBalance>
                <title>I return money for a beer</title>
                <party>Mark Brown</party>
                <partyIban>PL68249000050000400075212326</partyIban>
                <kind>OUTGOING EXTERNAL TRANSFER</kind>
              </moneyTransaction>
              <!-- ... more transactions ... -->
            </moneyTransactions>
          </account>
          <!-- ... more accounts ... -->
        </accounts>
      </target>
    </statement>
  </result>
</reply>

Returns data from the PDF statement or an error when the uploaded file is not a valid PDF document or seems to be counterfeited.

The command recognizes the source bank, parses the file, verifies authenticity and reads the owner, period, account(s) and transactions.

The command takes one PDF file. To aggregate multiple PDF files, call it several times with the same ownerExternalId parameter.

HTTP Request

POST /v1/statement.xml

Parameters

Data returned

Description of the <statement> element.

Description of the <owner> element.

Description of the <target> element.

Description of the <account> element.

Description of the account <owner> element.

Description of the <moneyTransaction> element.

Get aggregated data

HTTP Request

<reply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://developer.kontomatik.com/schema/v1/get_data.xsd" status="200 OK">
  <owner externalId="653643">
    <target name="MBank">
      <owners>
        <owner>
          <name>John Fitcha</name>
          <address>Kwiatowa 8/97 Warszawa  PL</address>
          <polishNip>1258882345</polishNip>  
          <kind>OWNER</kind>
        </owner>
        <!-- ... more owners ... -->
      </owners>
      <accounts>
        <account>
          <name>eKONTO</name>
          <iban>PL32114020040000320250132522</iban>
          <currencyBalance>1467.39</currencyBalance>
          <currencyName>PLN</currencyName>
          <owners>
            <owner>
              <name>Jan Kowalski</name>
              <address>Krótka 8, Wąchock</address>
              <kind>OWNER</kind>
            </owner>
            <!-- ... more owners ... -->
          </owners>
          <activeSinceAtLeast>2000-02-28</activeSinceAtLeast>
          <moneyTransactions>
            <moneyTransaction>
              <transactionOn>2012-06-28</transactionOn>
              <bookedOn>2012-06-30</bookekOn>
              <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>
            </moneyTransaction>
            <!-- ... more transactions ... -->
          </moneyTransactions>
        </account>
        <!-- ... more accounts ... -->
      </accounts>
    </target>
  </owner>
</reply>

GET /v1/data.xml?ownerExternalId=653643

Returns all imported and aggregated data associated with the user identified by an ownerExternalId.

The command returns a response with the same data fields as the Get aggregated data command in Banking API. The command returns a response with the same data fields as the command in Banking API.

Error handling

We can divide possible errors into three categories:

• Caused by incorrect API calls (given externalOwnerId parameter is invalid)
• Caused by a problem with the uploaded PDFs (the file is not a PDF document or is not a bank-statement PDF)
• Caused by bugs in our service (unexpected corner cases we must fix)

Errors caused by incorrect API calls

Command execution may fail when there is a problem with the given ownerExternalId.

Response

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

Errors caused by a problem with the uploaded PDF files

Bugs in Kontomatik

The following should be considered bugs in the Kontomatik Service. Most likely, some edge case condition occurred and our software was not prepared for this. Kontomatik should be improved to cover this case. The error should be reported to Kontomatik, attaching the XML reply and logs of the application server.

PDF Widget

Embedding the widget

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

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

// index.js
embedKontomatikPdf({
  client: 'YOUR_CLIENT_ID',    // replace it with your assigned client id
  divId: 'kontomatik',         // must match the div element id
  since: '2018-01-01',
  ownerExternalId: 'owner_id',
  onFinished: function({ target, periods, count }) {
    // End-user finished uploading the PDFs
    alert('It works!');
  }
});

Required params

The embedKontomatikPdf() function takes the following obligatory parameters:

Optional params

The embedKontomatikPdf() function takes the following optional parameters:

Callbacks

PDF 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 onFinished callback.

Callbacks are passed to embedKontomatikPdf() function as params.

Here is the brief summary of available callbacks:

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

onFinished callback

Once the files have been successfully parsed the onFinished callback is called.

onError callback

The onError callback is called when an error has occured during the end-user's interaction with the widget. It will be passed the following parameters:

The options object contains the following properties:

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

onUnsupportedTarget callback

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

onInitialized callback

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

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

onStarted callback

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

onTargetSelected callback

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

Removing the widget

removeKontomatikPdf();

If you dynamically reload the SignIn Widget on the frontend, the already registered callbacks will be attached to the previously created session. In order to manage this, before calling for embedKontomatik() again, please use the removeKontomatikPdf() function.

CSS styling the widget

embedKontomatikPdf({
  /*
  ... (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 embedKontomatikPdf() function.

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

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

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

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

Testing

To test the PDF Parsing service you can follow these few steps:

1. Embed the PDF Widget on your website or integrate with the statement.xml endpoint and prepare your own frontend to send the files.
2. Prepare documents to be tested:
   • real bank statements from your users - you can attempt to modify some of them to test negative scenarios;
   • use fake documents generated by Kontomatik - KontoBank statements.
3. Upload the documents using your chosen method.
4. Analyze the results and output.

For testing purposes please remember to use:

• your testing client ID (e.g. company-test) in the PDF Widget embedding function;
• the test environment address for endpoints in case of an API integration.

How to generate KontoBank statements

To generate a fake statement:

1. Go to https://bank.kontomatik.com/pdf/
2. Choose one of the mock accounts:
   • there are up to 10 existing mock accounts;
   • each account has different data, some can have multiple payment accounts available;
   • you’ll find the accounts descriptions in this document under the “Test accounts” tab.
3. Choose document type:
   • monthly statement - spans over one month only for just one account
   • account history - can include multiple accounts within a custom date range
4. (optional) Add errors:
   • this is to test negative parsing flow and learn to handle exceptions thrown by Kontomatik API;
   • you can choose multiple exceptions that will actually appear on the document;
   • Kontomatik API returns only one exception (first found).
5. Click “Generate PDF” and then save the file.