Account Direct Access | Komerční banka

KB API

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

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

Run in Postman

GitHub

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

VOTE NOW