KB API

Banking without borders. Obtain current data and information and control your accounts in your own application with KB API

Partner Service

ACCOUNT DIRECT
ACCESS SANDBOX

Download transaction history and account balance for your accounts conveniently and securely.

What does ADAA do?

The Account Direct Access API (ADAA) service provides secure access to information about:

  • Client’s transaction history
  • Bank account balance

Information about transaction history is provided in connection with current accounts of a client of Komerční banka.

Account balance information is provided in the following details:

  • Account balance
  • Available balance (including card transactions)
Prerequisites

In order to use Account Direct Access API (ADAA), you must have a certificate that is deemed credible by Komerční banka. To obtain such certificate, it is necessary to apply to:

We support any of the following certificate types:

  • Commercial certificate
  • Employee qualified certificate
  • Company qualified certificate
  • Company commercial technology certificate (server)

Account Direct Access API (ADAA) requires a certificate that must contain Organisation name and identification number (IČO). When applying for a certificate, the client must explicitly specify this.

Examples

Transactions in an instant

Online stores, clubs, and associations that collect membership fees – all these entities need to actively work with payments. With Account Direct Access API (ADAA), clients can obtain information about payments in real time and subsequently use such information in their processes – such as shipping of goods in online stores or reconciliation of invoices by accounting firms. 

Management of financial flows

Clients may use account balance information for active management of their financial flows. It is possible to monitor balances of individual accounts and subsequently, based on the results, initiate further actions – such as notification that a current account balance is below a specific limit.

Cost / Fees

The Account Direct Access API (ADAA) service is provided free of charge.

 

About ADAA

1. Client logs in an application with an already implemented support of the Account Direct Access API (ADAA) service. Client will subsequently work with the relevant data in such application as well. 

2. Client must consent to data downloads in the application. This consent is given through one of the available bank authentication methods:

              a. Security password
              b. File-based personal certificate
              c. Smartcard-based personal certificate
              d. KB Klíč

3. The consent is given for a specific period of time of no more than 12 months.

4. Once the consent is given, the relevant third-party application is ready to download data and process transaction history.

Requirements

In order to access the service, the following is necessary:

  • Valid qualified certificate issued by a certification authority that is deemed credible by KB (I.CA, PostSignum).
  • When using the service, we advise you to follow the rules of prudency in connection with data and system security; for our recommendations, see the API Security rules
Coming soon

We are continuously working on and improving the Account Direct Access API (ADAA) service. The following improvements are coming soon:

  • 2020
    • Notification of a new transaction
    • Transaction history – incrementally, from the last download
Access

In order to access the production version of Account Direct Access API (ADAA), it is necessary to have a certificate that contains name and identification number (IČO) of an organisation, for which the transaction history/account balance data are to be downloaded.

The application developer must register the application as follows:

1. Visit the API portal of Komerční banka, select the relevant service in the section for developers (in this case, select Account Direct Access API - ADAA), and click the service details.

2. In the service details, go to the Using API Step by Step section and select the following:

              a. Test your solution - sandbox for unlimited testing and experiments

3. In order to register your application for testing purposes, you must first register (or sign in if you already have a user account within the KB API portal). In order to register, you need the following:

              a. Email account
              b. Password

4. Once you register / sign in successfully, select “Add Application” and register your application. You only need the following information to register the application:

              a. Application name
              b. Application description

5. The developer then selects the “Sandbox Key” tab to generate an application key.

6. Once the key is generated, it is necessary to register 3 applications:

              a. Oauth2-Sandbox - (version 1)
              b. Oauth2-Software-statements-Sandbox - (version 1)
              c. Account-Direct-Access-API-Sandbox - (version 1)

7. The process is as follows:

              a. Select the “Subscriptions” tab;
              b. Select the specific application you wish to register;
              c. Confirm the registration process.

8. And we are all done!

Authentication

The service is secured in line with the OAuth 2 standard, thereby providing high level of security. Therefore, client’s consent is required to use the service.

Environment

Environment  

Description

Sandbox

https://openbanking.kbcloud.cz/

Production

https://api.kb.cz/open/apim/store

Limits

Limits are defined per API key – for calls per minute and calls per day; the limits are as follows:

 Calls per minute  

 Calls per day

60

 3600 x 24 (86,400)

Example of API calls
API Call Diagram

Functionality Description

It is then necessary to subscribe the application to API:

  • Account Direct Access API
  • OAUTH2
  • Client registration

The swagger for the aforementioned services contains detailed description of all attributes and should be sufficient to understand the functionality. In general, the swagger documentation is written in English.

1. Issuance of a software statement signed by the bank

Objective

Get SW statement signed by Komerční banka.

Type

REST API

Called API

[POST] https://api.kb.cz/open/api/client-registration/v1/software-statements

Security

API key

Requirements

Valid qualified certificate issued by a certification authority

Request data

Certificate

Response data

Signed statement in the form of a JWT token

The statement is valid for 6 months. 

URI parameter

Description

x-client-cert

Fill “valid-certificate” (sandbox accepts this value as a valid client certificate)

 

2. Registration of OAUTH2 agent – third-party application

Objective

Register with the bank a third-party application, as an OAUTH2 agent, to allow communication between the application and the bank.

Type

Call (SSL) HTTP POST (SAML)

Called URI

https://openbanking.kb.cz/client-api-management/saml/register

Security

HTTPS, SSL, Software statement

Requirements

Signed statement in the form of JWT tokens, RSA-256 encryption support, embedded browser support is a plus.

Request data

Statement in the form of a JWT token, redirect URI to receive the authorisation code. Encryption key, encryption algorithm (see the definition of parameters).

Response data

Encrypted registration data (clientId, clientSecret) as (encryptedData, salt)

 

Your application should support an embedded browser.
Registration URI must be opened upon client’s initiative, through which the client logs in with the bank, assigns a name to the application session, and signs the operation. Registration parameters are sent to the banking URI via HTTP POST in a parameter (registrationRequest) as a JSON form in the BASE64URL format; see an example below.

Following the operation completion and successful registration, registration data (client_id, client_secret) – encrypted with an encryption key (encryptionKey) and encryption algorithm (encryptionAlg) – will be returned to the browser at the selected address (as specified in your software statement in step 1 - redirectUris). The data will be returned in parameters (encryptedData, salt).  

Definition of parameters of the form for called URI

Parameter

Mandatory

Data type

Validation

Description

applicationType

Y

String

„web“ | „native”

Application type:

  • web
  • native

clientName

Y

String

4 - 255 characters

Name of registered OAUTH2 agent

clientNameEn

N

String

4 - 255 characters

English version of the name

redirectUris

Y

List<String>

Not empty

Redirect address, to which authorisation code from step 3 is to be returned.

scope

Y

List<String>

Not empty

Scope of authorisation – “adaa” value is used.

encryptionKey

Y

String

-

Encryption key used to encrypt client_id, client_secret.

encryptionAlg

Y

String

„AES-256“

Encryption algorithm; AES-256 is currently the only supported algorithm.

softwareStatement

Y

String

-

Software statement signed by the bank – in the form of a JWT token.

 

Example of a completed JSON form


   "clientName":"Nejlepsi Produkt",
   "clientNameEn":"Best Product",
   "applicationType":"web",
   "redirectUris":[ 
      "https://client.example.org/callback",
      "https://client.example.org/callback2"
   ],
   "scope":[ 
      "adaa"
   ],
   "softwareStatement":"eyJhbGciOiJSUzI1NiJ9"
}

 

Final request for registration of the OAUTH2 agent

The completed form is converted to the BASE64URL format and sent as a request in the registrationRequest parameter.

https://openbanking.kb.cz/client-apimanagement/saml/registerregistrationRequest=eyAKICAgImNsaWVudE5hbWUiOiJOZWpsZXBzaSBrbGllbnQiLAogI
CAiY2xpZW50TmFtZUVuIjoiQmVzdCBjbGllbnQiLAogICAiYXBwbGljYXRpb25UeXBlIjoid2ViIiwKICAgInJlZGlyZWN0VXJpcyI6WyAKICAgICAgIm
h0dHBzO
i8vY2xpZW50LmV4YW1wbGUub3JnL2NhbGxiYWNrIiwKICAgICAgImh0dHBzOi8vY2xpZW50LmV4YW1wbGUub3JnL2NhbGxiYWNrMiIKICAgXSwKICA
gInNjb3BlIjpbIAogICAgICAiYWRhYSIKICAgXSwKICAgInNvZnR3YXJlU3RhdGVtZW50IjoiZXlKaGJHY2lPaUpTVXpJMU5pSjkiCn0

 

Result of successful registration
In case the OAUTH2 agent is successfully registered, HTTP 302 redirect is returned to the registration redirectUri with salt and encryptedData parameters. The parameters are in the BASE64URL format and it is necessary to decode them from BASE64URL prior to decryption.

https://client.example.org/callback?salt=yMzQ1NiIsImVtYWlsOiBleGFtcGxlQGdvb2Rzb2Z0Lm&encryptedData=VlciIsInNvZnR3YXJlT
mFtZSI6Ik5lamxlcHNpIFByb2R1a3QiLCJzb2Z0d2FyZU5hbWVFbiI6IkJlc3QgUHJvZHVjdCIsInNvZnR3YXJlSWQiOiJmNjRiZjJlNDQ3ZTU0NTIyO

 

Decrypted data structure for successful registration

It results in JSON data registered in the bank for the given OAUTH2 agent. In order to complete further steps, it is necessary to securely save the client_id and client_secret values used for OAUTH2 agent’s identification.


   "client_id":"NejlepsiProdukt-7427",
   "client_secret":"6dBtcLp27Q0UXrvfoXOSug",
   "api_key":"NOT_PROVIDED",
   "application_type":"web",
   "redirect_uris":[ 
      "https://client.example.org/callback",
      "https://client.example.org/callback2"
   ],
   "client_name":"Nejlepsi Produkt",
   "client_name#en-US":"Best Product",
   "logo_uri":"https://client.example.org/logo.png",
   "contact":"example@goodsoft.com",
   "bin":"45317054"
}

 

and

URI parameter

Description

response_type

Type of return value, always fill „code“.

client_id

OAuth2 agent ID – TPP application name, always fill „kbSandboxUser”.

redirect_uri

Back URL for sending an authorization code (i.e. „https://mycompany.cz“).

scope

Authority scope, for ADAA always fill „adaa“.

Note: Unsupported parameters route to bad request.

KB OAUTH2 TEST login page:

3. Client’s consent to data downloads via third-party application and obtaining authorisation code

Cíl

Udělit souhlas k stahování transakční historie z banky do aplikace a získat authorisationCode.

Typ

Volání (SSL) HTTP POST (OAUTH2)

Volané URI

https://login.kb.cz/autfe/ssologin

Zabezpečení

HTTPS, SSL, OAUTH2

Požadavky

Zaregistrovaná aplikace v bance jako OAUTH2 agent.

Request data

client_id, redirect_uri, scope, response_type

Response data

authorisation_code

The approval process of transaction history downloads by a third-party application is subject to client’s consent to the operation. Bank web service calls are used for this purpose, through which the client gives its consent to access to its accounts. URI of the consent process (see the definition of parameters) must be opened upon client’s initiative, through which the client logs in with the bank and signs the operation. Following the operation completion, an authorization code (authorisation_code) is returned to the specified redirect_uri for the purpose of obtaining refresh and access tokens that are used to download client data.  

Definition of parameters of the called URI

URI parameter

Description

redirect_uri

URI address to redirect authorisation_code specified upon registration of the OAUTH2 agent (validation, whether they are identical).

client_id

OAUTH2 agent’s ID; assigned by the bank following the registration during the previous step.

scope

Scope of validity – “adaa” value is used.  

response_type

Response value type; “code” value is used.

 

Final request for consent

https://login.kb.cz/autfe/ssologin?scope=adaa&client_id=NejlepsiProdukt-7427&redirect_uri=https://client.example.org/callback&response_type=code


Result of successful consent process
In case the consent for TH downloads by an OAUTH2 agent is successfully granted, HTTP 302 redirect is returned to the registration redirectUri with code parameter that contains an authorisation code.

https://client.example.org/callback?code=ZnR3YXJlTmFtZSI6Ik5lamxlcHNp

 

4. Receive token

Objective

Receive authorisation code to exchange for an access and refresh token and allow transaction history downloads.

Type

REST API

Called API

https://api.kb.cz/open/api/oauth2/v1/access_token

Requirements

Consent given by a client, authorisation_code

Request data

client_id, client_secret, authorisation_code

Response data

refresh_token, access_token

After the receipt of an authorisation code issued on the basis of client’s consent to transaction history downloads, it must be exchanged for refresh and access tokens. This endpoint is used for this purpose. The endpoint is also used to obtain an access token with a refresh token. Using an access taken (access_token), it is possible to call upon all ADAA endpoints. For detailed API description, see the swagger documentation.

Definition of tokens:

Token

Description

Expiration

access_token

It is used as an authorisation parameter to call the ADAA API service.

Note: The token may be used repeatedly prior to its expiration.  

3 minutes

refresh_token

It is used to issue a new access token; it is used as a parameter to call the OAUTH2 API service.

Note: The token may be used repeatedly prior to its expiration.  

12 months

 

5. Replace IBAN with an account identification number

Objective

Obtain accountID for the given IBAN.

Type

REST API

Called API

https://api.kb.cz/open/api/adaa/v1/account-ids 

Requirements

Know an IBAN number and account currency.

Request data

IBAN, currency, access_token

Response data

account_id

 

For the purpose of enhanced security, it is not possible to send IBAN in the header in its open form; it is necessary to apply for the so-called identification number (i.e. encrypted IBAN). Transaction history or account information downloads are called using the identification number - accountId. For detailed API description, see the ADAA swagger documentation.  

Bank’s recommendations:

  • Keep the account_id in the application for later use. It is not necessary to call the endpoint again.

6. Transaction history downloads

Objective

Download transaction history.

Type

REST API

Called API

https://api.kb.cz/open/api/adaa/v1/transactions

Requirements

Valid access_token, account_id

Request data

account_id, access_token

Response data

Transaction history

The endpoint is used to download transaction history for the account in question. For detailed API description, see the ADAA swagger documentation.

7. Account balance downloads

Objective

Download account balance

Type

REST API

Called API

https://api.kb.cz/open/api/adaa/v1/balances

Requirements

Valid access_token, account_id

Request data

account_id, access_token

Response data

Account balance

The endpoint is used to download account balance for the account in question. For detailed API description, see the swagger documentation.

 

 

Will this API be useful for you?

116 people 
voted