Technical Manual for Implementing the "Account Direct Access" API
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Technical Manual for Implementing the “Account
Direct Access” API
15 October 2021
Version 1.4Technical Manual – Account Direct Access API
CHANGE LOG
Version Date of effectiveness Change description
1.4 15.10.2021 Extend SW statements validation to 12 months
1.3 15.6.2021 Add more detail to chapter 9
1.2 22.4.2021 Add parameter state to step 2
1.1 20.1.2020 Add notification chapter 9.
1.0 2.5.2020 Public document
TABLE OF CONTENTS
Change log .............................................................................................................................................. 1
Background.............................................................................................................................................. 2
Registration within the API portal ............................................................................................................ 2
Functionality description .......................................................................................................................... 3
1. Issuance of a software statement signed by the bank ..................................................................... 4
Bank’s recommendations: ................................................................................................................ 4
SW Statement parameters .................................................................................................................. 5
Bank’s recommendations: ................................................................................................................ 5
2. Registration of OAUTH2 agent – third party application .................................................................. 6
Definition of parameters of the form for called URI ......................................................................... 7
Example of a completed JSON form ............................................................................................... 8
Final request for registration of the OAUTH2 agent ........................................................................ 9
Result of successful registration ...................................................................................................... 9
Decrypted data structure for successful registration...................................................................... 10
3. Client’s consent to data downloads via third-party application and obtaining authorisation code . 11
Definition of parameters of the called URI ..................................................................................... 11
Final request for consent ............................................................................................................... 11
Result of successful consent process ............................................................................................ 11
4. Receive token ................................................................................................................................ 12
Definition of tokens: ....................................................................................................................... 12
5. Replace IBAN with an account identification number .................................................................... 13
Bank’s recommendations: .............................................................................................................. 13
6. Transaction history downloads ...................................................................................................... 14
Bank’s recommendations: .............................................................................................................. 14
7. Download account balance ............................................................................................................ 15
8. Download account statement......................................................................................................... 15
9. Notification of changes on the account .......................................................................................... 16
Register your endpoint to receive notifications .................................................................................. 16
STATUS OF REGISTRATION:.......................................................................................................... 17
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 1
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
.Your API to receive notifications ....................................................................................................... 18
BACKGROUND
• In connection with the relationship with KB, the Partner shall comply with the rules described in
the Code of Prudent Conduct.
• Before reading this Manual, we advise you to read the general description of the service. It also
specifies the requirements and actions that must be met or taken prior to the technical
connection to the Account Direct Access API.
REGISTRATION WITHIN THE API PORTAL
In order to actually connect to the service, it is necessary to register within the production API portal,
register an application (third party to consume the issued API) and generate an API key. For more
details, see the Production API Portal manual.
It is then necessary to subscribe the application to API:
• Account Direct Access
• OAUTH2
• Client registration
The swagger for the aforementioned service contains a detailed description of all attributes and should
be sufficient to understand the functionality. In general, the swagger documentation is written in English.
BANK’S RECOMMENDATIONS:
• Keep the API key secure;
• Access your API key remotely from your application;
• Generate a new API key for each new version of your application.
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 2
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API FUNCTIONALITY DESCRIPTION Komerční banka, a.s. registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 3 Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360
Technical Manual – Account Direct Access API
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
Software statement is based on the OAUTH2 standard in line with RFC 7591 for dynamic registration of
OAUTH2 agents. The statement is necessary for automatic registration of the application to ensure the
registration credibility and security. Once API is successfully called, you will receive a statement – signed
by the bank – in the form of a JWT token, by which a client’s application will register in the bank. The
statement is valid for 12 months. In case of new statement (due to expiration or lost) we highly
recommend remove old one (it is possible to have more valid token for one application, but this is not
desirable). JWT token must be securely implemented / saved in your application (or all installations
thereof). For detailed API description, see the swagger documentation.
BANK’S RECOMMENDATIONS:
• Komerční banka trusts certificates from ICA and postsignum. It is necessary to have a
qualified certificate
• 1. CA https://www.mujcertifikat.cz/request-for-certificate
• Postsignum https://www.postsignum.cz/kvalifikovane_certifikaty.html?l=en
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 4
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
SW STATEMENT PARAMETERS
Parameter name Mandatory Data type Validation Description
softwareName Y String 5 - 50 Software name - CZ
characters
softwareNameEn N String 5 - 50 Software name - EN
characters
softwareId Y String max 64 Software identification code,
characters any string (structure or
value itself is not validated)
softwareVersion Y String 1 - 30 Software version
characters
softwareUri N String - Software URL
redirectUris Y List - List of adresses, where the
auth. code can be sent
(specific adress is defined
in redirect_uri, see Client’s
consent to data downloads
via third-party application
and obtaining authorisation
code)
tokenEndpointAuthMethod N String - Fill „client_secret_post“
grantTypes N List - Fill „authorization_code“,
„refresh_token“
responseTypes N List - Fill „code“
registrationBackUri Y String - URL for sending registration
parameters (client_id,
client_secret), see
Registration of OAUTH2
agent – third party
application
contacts N List max 50 List of contact addresses (to
characters contact people responsible
for this client, typically email
addresses).
logoUri N String - URL that references a logo
for the client.
tosUri N String - URL that points to a human-
readable terms of service
document for the client.
policyUri N String - URL that points to a human-
readable privacy policy
document.
BANK’S RECOMMENDATIONS:
• Keep the software statement secure,
• Access the software statement remotely from your application.
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 5
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
• Don’t use localhost as a redirectUri (in production version of service), due to the possibility of
theft data by third party.
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://api.kb.cz/client-registration/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)
The process of registering application with the bank is subject to client’s consent to the operation. Web
service calls are used for this purpose (following the consent and application registration). 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 instance, and signs the operation. Registration parameters are sent
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 6
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
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 - registrationBackUri). 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“ | Application type:
„native”
• web
• native
clientName Y String 4 - 255 Name of registered OAUTH2 agent
characters
clientNameEn N String 4 - 255 English version of the name
characters
redirectUris Y List Not empty List of adresses, where the auth.
code can be sent (specific adress is
defined in redirect_uri, see Client’s
consent to data downloads via
third-party application and
obtaining authorisation code.
scope Y List 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
(AES/GCM/NoPadding) is
currently the only supported
algorithm.
softwareStatement Y String - Software statement signed by the
bank – in the form of a JWT token.
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 7
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
EXAMPLE OF A COMPLETED JSON FORM
{
"clientName": "Kifli",
"clientNameEn": "Kifli",
"applicationType": "web",
"redirectUris": [
"https://client.example.org/callback"
],
"scope": [
"adaa"
],
"encryptionKey": "djh5L0I/RShHK0tiUGVTaFZtWXEzdDZ3OXokQyZGKUo=",
"encryptionAlg": "AES-256",
"softwareStatement": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJLb21lcsSNbsOtIEJhbmthIFRFU1QiLCJpYXQi-
OjE2MTE1NjQ4ODksImV4cCI6MTYyNzI4OTY4OSwidmVuZG9yTmFtZSI6IkRhdGEgRXZvbHV0aW9uIHMuci5vLiIsInN-
vZnR3YXJlTmFtZSI6Ik5lamxlcMWhw60gcHJvZHVrdCIsInNvZnR3YXJlTmFtZUVuIjoiQmVzd-
CBwcm9kdWN0Iiwic29mdHdhcmVJZCI6ImY2NGJmMmU0NDdlNTQ1MjI4Yzc4ZTA3YjA4MWE4MmVlIiwic29mdHd-
hcmVWZXJzaW9uIjoiMS4wIiwic29mdHdhcmVVcmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm9yZyIsInJlZGly-
ZWN0VXJpcyI6WyJodHRwczovL2NsaWVudC5leGFtcGxlLm9yZy9jYWxsYmFjayI-
sImh0dHBzOi8vY2xpZW50LmV4YW1wbGUub3JnL2NhbGxiYWNrLWJhY2t1cCJdLCJ0b2tlbkVuZHBvaW50QXV0aE1ld-
GhvZCI6ImNsaWVudF9zZWNyZXRfcG9zdCIsImdyYW50VHlwZXMiOlsiYXV0aG9yaXphdGlvbl9jb2RlIl0sInJlc3BvbnN-
lVHlwZXMiOlsiY29kZSJdLCJyZWdpc3RyYXRpb25CYWNrVXJpIjoiaHR0cHM6Ly9jbGllbnQuZXhhbXBsZS5vcmcvYm-
Fja3VyaSIsImNvbnRhY3RzIjpbImVtYWlsOiBleGFtcGxlQGdvb2Rzb2Z0LmNvbSJdLCJsb2dvVXJpI-
joiaHR0cHM6Ly9jbGllbnQuZXhhbXBsZS5vcmcvbG9nby5wbmciLCJ0b3NVcmkiOiJodHRwczovL2Nsa-
WVudC5leGFtcGxlLm9yZy90b3MiLCJwb2xpY3lVcmkiOiJodHRwczovL2Nsa-
WVudC5leGFtcGxlLm9yZy9wb2xpY3kifQ.FkGHZIbwwcvkoXP-1bBoFyBfg4hWMn-
RWzN9U0a66SbE2h5dH0M2FK1KTXqza04pMRigFPPGNXDuG_qMpBBCtOAdQV726DnR5Oogkb-
cbaSDDd0udkA6p1feV91Iu_3km2bsZY_m_13zqGF86bH7iaqJG9nk_PaHne3dT5r31HVYnB7MrgmLwp-
GDlShIB17c6UU1x_eAq4bGjj8jE3_zatYqcoaJSLEicepv5OqhQ7LCBclB8NnJOMhgeqBUz055R88eR-
GrlZbxia6qi4NODR5SaVK53TAG3Ez5SgycZNpxGpGkQytVcrEsVSydl9he6d3wHckvzRiPiWf2Hmk4mOxHA"
}
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 8
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API 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. You can use optional parameter state (parameter state has the same function in OAuth2) https://api.kb.cz/client-registration/saml/register?registrationRequest=eyAKICAgImNsaWVudE5hbWUiO iJOZWpsZXBzaSBrbGllbnQiLAogICAiY2xpZW50TmFtZUVuIjoiQmVzdCBjbGllbnQiLAogICAiYXBwbGljYXRpb2 5UeXBlIjoid2ViIiwKICAgInJlZGlyZWN0VXJpcyI6WyAKICAgICAgImh0dHBzOi8vY2xpZW50LmV4YW1wbGUu b3JnL2NhbGxiYWNrIiwKICAgICAgImh0dHBzOi8vY2xpZW50LmV4YW1wbGUub3JnL2NhbGxiYWNrMiIKICA gXSwKICAgInNjb3BlIjpbIAogICAgICAiYWRhYSIKICAgXSwKICAgInNvZnR3YXJlU3RhdGVtZW50IjoiZXlKaGJHY 2lPaUpTVXpJMU5pSjkiCn0&state=Client123 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=VlciIsInNvZnR3YXJlTmFtZSI6Ik5lamxlcHNpIFByb2R1a3QiLCJzb2Z0d2FyZU5hbWVFb iI6IkJlc3QgUHJvZHVjdCIsInNvZnR3YXJlSWQiOiJmNjRiZjJlNDQ3ZTU0NTIyO Komerční banka, a.s. registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 9 Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360
Technical Manual – Account Direct Access API
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.
{
"application_type": "web",
"redirect_uris": [
"https://client.example.org/callback-backup",
"https://client.example.org/callback"
],
"client_name": "Nejlepší produkt",
"client_name#en-US": "Best product",
"logo_uri": "https://client.example.org/logo.png",
"policy_uri": "https://client.example.org/policy",
"tos_uri": "https://client.example.org/tos",
"contact": "example@goodsoft.com",
"contacts": [
"example@goodsoft.com"
],
"scopes": [
"adaa"
],
"scope": "adaa",
"response_types": [
"code"
],
"response_type": "code",
"grant_types": [
"authorization_code",
"refresh_token"
],
"subject_type": "public",
"token_endpoint_auth_method": "client_secret_post",
"require_auth_time": false,
"client_id": "Nejlepsiprodukt-5821",
"client_secret": "aVYVsR2hbf19Xg8COw2JLw",
"api_key": "NOT_PROVIDED",
"state": "Client123"
}
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 10
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
3. CLIENT’S CONSENT TO DATA DOWNLOADS VIA THIRD -PARTY
APPLICATION AND OBTAINING AUTHORISATION CODE
Objective Grant consent to download transaction history from the bank in the
application and obtain an authorisationCode
Type Call (SSL) HTTP POST (OAUTH2)
Called URI https://login.kb.cz/autfe/ssologin
Security HTTPS, SSL, OAUTH2
Requirements Registered application with the bank as an OAUTH2 agent
Request data client_id, redirect_uri, scope, response_type, state
Response data code, state
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 his 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 is returned to the specified
redirect_uri for the purpose of obtaining refresh and access tokens that are used to download client
data. State (optional parameter) serves as Cross-Site Request Forgery protection (see
https://tools.ietf.org/html/rfc6749#section-4.1.1).
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
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 11
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
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 [POST] 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. Endpoint is used for this purpose.
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. 3 minutes
Note: The token may be used repeatedly prior to its expiration.
refresh_token It is used to issue a new access token; it is used as a parameter to 12 months
call the OAUTH2 API service.
Note: The token may be used repeatedly prior to its expiration.
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 12
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
5. REPLACE IBAN WITH AN ACCOUNT IDENTIFICATION NUMBER
Objective Obtain accountID for the given IBAN
Type REST API
Called API [POST] https://api.kb.cz/open/api/adaa/v1/accounts/account-ids
Requirements Known 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.
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 13
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
6. TRANSACTION HISTORY DOWNLOADS
Objective Download transaction history
Type REST API
Called API [GET] https://api.kb.cz/open/api/adaa/v1/accounts/accountId/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.
BANK’S RECOMMENDATIONS:
• We recommend using the notification system, see chapter 9 - Notification of changes on the
account. If you are using automatic downloads at a exact time, please do not use the full half-
hours and hours (13:30:00, 14:00:00) to avoid peaks on the service. We recommend adding a
few seconds (13:00:50, 13:31:34).
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 14
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API 7. DOWNLOAD ACCOUNT BALANCE Objective Download account balance Type REST API Called API [GET] https://api.kb.cz/open/api/adaa/v1/accounts/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. 8. DOWNLOAD ACCOUNT STATEMENT Cíl Obtain statement metadata (include statementId) Typ REST API Volané API [GET] https://api.kb.cz/open/api/adaa/v1/statements Požadavky Valid access_token, account_id Request data account_id, access_token, dateFrom Response data Statement metadata (include statemen_iId – id of specific PDF file) The endpoint is used to download information about account statements (metadata). Metadata contains important parameter – statement_id – id of specific PDF file (for downloading specific PDF file; see endpoint below). For detailed API description, see the ADAA swagger documentation. Cíl Download account statement in PDF format Typ REST API Volané API [GET] https://api.kb.cz/open/api/adaa/v1/statements Požadavky Valid access_token, account_id, statement_id Request data account_id, access_token, statement_id Response data Statement in PDF format The endpoint is used to download specific statement / file in PDF format. For detailed API description, see the ADAA swagger documentation. Komerční banka, a.s. registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 15 Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360
Technical Manual – Account Direct Access API
9. NOTIFICATION OF CHANGES ON THE ACCOUNT
To receive notifications of account changes, you must complete the following steps:
1. register to receive notifications
o part of the registration is the transfer of the URL address of the above API (for
sending notifications)
2. implement on its side the API to which notifications will be sent
o KB will call this API if a change is detected on the account
o KB will only provide information on the number of changes, for specific data, it is
necessary to download the transaction history
You can have unlimited registrations for notifications.
REGISTER YOUR ENDPOINT TO RECEIVE NOTIFICATIONS
Objective Registration for receiving notifications
Type REST API service
Called API [POST],
https://api.kb.cz/open/api/adaa/v1/accounts/accountId/transactions/event-
subscriptions
Requirements Valid access_token, account_id,
Request data account_id, access_token, eventApiUrl (API address for receiving notifications,
see above), eventApiKey (API key for calling API for receiving notifications)
Response data Registration information:
• subscriptionId - assigned unique registration id
• eventApiUrl - API address for receiving notifications
• eventApiVersion - before creating the registration, a check call of the API
for subscription of notifications (is-alive method) is performed and if it is
successful, the version of the given API is saved
• status - the result of the call - according to the returned answer, the
relevant status is set:
o ACTIVE - API (for subscription of notifications) performed
successfully (returned 204)
o SUSPENDED - API call (for notifications) failed - API is
unavailable (returned 500) - in this case the call is made
automatically later (in several iterations within a total of 24 hours
after API failure; then the expiration of this time is considered
unavailable and registration set to STOPPED status)
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 16
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
o STOPPED - API call (for receiving notifications) failed (401, 403,
404 response returned)
• statusNarrative - the reason for the status, for example (Connection
Timeout: https://company.org/event-api/v1/subscriptions/71f415f4-412d-
4c55-af05-15d1e0389f8f/events)
Registration is a necessary part of receiving notifications. As part of the registration, an API URL is
passed to receive notifications. The output of the registration is a unique id (subscriptionId), which
identifies to which account the notifications relate.
If it is a requirement to register multiple accounts for subscription notifications, it is necessary (for each
account) to re-register (new subscriptionId).
STATUS OF REGISTRATION:
The registration (notification subscription) statuses are listed above (ACTIVE, SUSPENDED,
STOPPED). The statuses are set according to the detected availability / behavior of the API for receiving
notifications. From the SUSPENDED state, it is possible to automatically switch to ACTIVE, provided
that the call is successful (detected in several iterations, see above). The STOPPED state is final -
registration in this state can no longer be renewed and the only option is a new registration.
Objective Check of the registration status for receiving notifications
Type REST API service
Called API [GET], https://api.kb.cz/open/api/adaa/v1/accounts/accountId/transactions event-
subscriptions
Requirements Valid access_token, account_id, subscriptionId
Request data Account_id, access_token, subscriptionId
Response data Registration information (same scope as for the POST method, see above).
The endpoint is used to determine the status of registration / subscription of notifications. For example,
if there has been a long-term outage of the api for receiving notifications (and as a result, on the
registration side, the status changes, eg to STOPPED). Sending a notification will not work and the way
to find out the situation is to call this method (GET).
Objective Cancellation of registration - cancellation of subscription of notifications
Type REST API service
Called API [DELETE], https://api.kb.cz/open/api/adaa/v1/accounts/accountId/transactions
event-subscriptions
Requirements Valid access_token, account_id, subscriptionId
Request data Account_id, access_token, subscriptionId
Response data Confirmation of cancellation of registration.
The endpoint is used to delete the registration if the subscription of notifications (for a defined account)
is no longer required
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 17
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360Technical Manual – Account Direct Access API
.YOUR API TO RECEIVE NOTIFICATIONS
Objective Notification Subscription API
Type REST API service
Called API [POST], https://company.org/event-api/v1
Requirements The structure of the API corresponds to the example of github adaa-event-
api.yaml
Request data subscriptionId (id assigned within the registration for subscription of notifications),
eventCount (number of changes)
Response data Information on receipt of notification.
The endpoint is used to receive a notification when there is a change in the account (new event in the
transaction history). The API issues a notification to the recipient (third party). The main benefit of this
solution is that there is no need to regularly download the transaction history to identify the change. The
download can be performed only at the moment of obtaining the notification from KB.
You can see example https://github.com/komercka/adaa-eventapi-spring-boot-example
Komerční banka, a.s.
registered office: Na Příkopě 33, Praha 1, ZIP CODE 114 07, Company ID 45317054, registered in the 18
Commercial Register maintained by the Municipal Court in Prague, Section B, Insert 1360You can also read
