Skip to content

Home

Jump to bottom
Miloš Sonták edited this page Jan 30, 2025 · 41 revisions

Product

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.

You can find more details on the Direct Account Access API

Enviroments

For testing and debugging your requests we recommend to use the Postman app. We have prepared collections of example requests to use in Postman, download them from the links below.

Sandbox

Production

How to start

Actors

  • User - Client KB - User who give access to his account via API in Komercni banka
  • Developer - Developer who create app
  • KB - Komercni banka

Process

Tip

  • the step number in the diagram corresponds to the description below
sequenceDiagram
    participant Developer as Developer
    participant API_Portal as API Portal
    participant KB_Client as KB Client
    participant App as Developer's App
    participant Client_Registration_API as Client Registration API
    participant Client_Browser as Client's Browser
    participant KB_Interface as KB's Interface
    participant OAuth2_API as OAuth2 API
    participant Adaa_API as ADAA API
    Developer->>+API_Portal: 1. Register on KB API portal
    Developer->>+API_Portal: 2. Create API keys
    API_Portal-->>Developer: apiKey
    Developer-->>Developer : Register qualified certificate
    App->>Client_Registration_API: 3. Register application
    Client_Registration_API-->>App: software statements (valid 12 months)
    KB_Client->>App : Register App to KB
    App->>Client_Browser: 4. Construct URL for App Registration
    Client_Browser->>KB_Interface: Redirect to KB
    KB_Interface->>KB_Client: 5.Client of KB registers app connection
    KB_Client-->>KB_Interface : Confirm connection
    KB_Interface->>Client_Browser: Redirect back with app registration info
    Client_Browser-->>App : Send data encryptedData to registrationBackUri
    App->>App: 6. Decrypt app registration info
    KB_Client->>App : Connect app to KB
    App->>Client_Browser: 7. Construct URL for Authorization code Token
    Client_Browser->>KB_Interface: Visit URL for auth code
    KB_Interface->>KB_Client: 8. Client of KB confirms app scopes inside KB's interface + Accounts selection
    KB_Client-->>KB_Interface : Confirm connection + Accounts selection  
    KB_Interface->>Client_Browser: Redirect back with auth code 
    Client_Browser-->>App : Send data auth_code to redirectUris   
    App->>OAuth2_API: 9. Obtain Refresh token (grant_type=authorization_code)
    OAuth2_API-->>App : refresh_token (valid 12 months)
    App->>OAuth2_API: 9. Obtain Access token (grant_type=refresh_token)
    OAuth2_API-->>App : access_token (valid 3 minutes)
    App->>Adaa_API : 10. /accounts  using access_token
    Adaa_API-->>App : List of accounts (accountId)
    App->>App : Store accountId
    App->>Adaa_API : 10. /balance  using access_token
Loading

1. Register on KB API portal

To use any of our API's you (the Developer) will need to be registred on our API portal. Though the API portal you will be able to subscribe to the API's you want to use and generate API keys.

2. Create API keys for the API's you will be using

  • Subcribe to an API (Client Registration, OAuth2, Account direct access API)
  • create an API key for it (apiKey) - How create API key (apiKey)

Each API needs its own API key. You can create multiple API keys for each API. You can also create multiple API keys for the same API.

3. Register your application via the Client Registration API

Create a Software statement for your application and register it via the Client Registration API. You will need to use the API key you created in the previous step.

4. Construct a URL to the Application Registration endpoint and visit it in the Client's browser

  • Construct a URL
  • Visit the constructed URL in the Client's browser.
  • Browser redirects to KB for an authorization of a Client of KB. (example page)

5. Client of KB registers an app connection inside KB's interface

  • Client of KB continues to login to KB. (example page)
  • Client of KB confirms authorization via an authorization app (KB Klíč). (example page)
  • KB redirects back to a callback url provided in the software statement and that way transfers control back to the app.

6. Decrypt the application registration information

You, the Developer, needs to process the information included in the callback URL.

You will need the client_id, client_secret in the next steps.

7. Construct a URL to get the Authorization code Token and visit it in the Client's browser

Using the client_id obtained in the previous step, construct a URL to get the authorization code token.

  • Construct a URL as described in the Tokens - Authorization code wiki page.
  • Visit the constructed URL in the Client's browser.
  • Browser redirects to KB for an authorization of a Client of KB.

8. Client of KB confirms app scopes and accounts inside KB's interface

  • Client of KB continues to login to KB. (example page)
  • Client of KB confirms scopes (example page)
  • Client of KB chooses accounts to be authorized with the API. (example page)
  • KB redirects back to a callback url provided in the request URL parameter and that way transfers control back to the app.

9. Obtain Refresh token and Access Token using the Authorization code

  • Get the Authorization code from the callback URL's parameters
  • Use the Authorization code , client_id and client_secret to get the Refresh token and Access Token

10. Call the ADAA API using the Access token provided

  • First, you will probably want to get the Client's Accounts available. The accountId is needed for other endpoints.

Account Balances
Transactions
Notification of changes to your account (webhook)
Account Statements - PDF

Recommendations for the user interface

  • Make a flow to create an Application Registration by the user (step 4) - each user needs only 1 application
  • Make a flow for Refresh token acquisition and renewal (step 7) - once every 12 months or sooner. Refresh token is valid for 12 months.
  • Check out our demo app
  • For more information about user interface requirements see Third-Party Application Frontend Guide

Errors codes handling

How report a bug

If you encounter any issues during implementation, please report them to our support team at [email protected]. To ensure efficient resolution:

Follow the guidelines outlined in our bug reporting documentation. Provide all requested information in the specified format Include relevant error codes and detailed descriptions.

Following these reporting guidelines helps us process and resolve issues more efficiently, ultimately improving the implementation experience for all developers.

Clone this wiki locally