Flow description

 

a) Final Api Consumer (FAC):

b) Third Party Provider (TPP): 

 

Step 1: Authorize User's Accounts Consent

 

Authorizing access to client's personal banking data follows OAuth 2.0 Authorization Code Grant flow.

  1. This substep depends on the Application usage type.
    1. Final consumer: in case you are using Premium API as a Final consumer, you can avoid this substep and continue with number 2.
    2. TPP: in case you are using Premium API as a TPP, you have to create a consent with a specific consentId by making a POST.../v1/consents request. ConsentId will be used in an authorization call in the substep number 2. You have to paste the consentId to the scope parameter after value and colon (e.g. PREMIUM_AIS:2d5d8c-1d5fd8d-2x36d5-2d1g5g). Please note that it is not possible to test the functionality of consents in a Sandbox environment, therefore read the documentation regarding its usage carefully.

E.g.:

POST https://api.tatrabanka.sk/premium/production/v1/consents

POST /premium/production/v1/consents HTTP/1.1

X-Request-ID: 84848458

Authorization: Basic xxxxxxxxx

User-Agent: PostmanRuntime/7.26.10

Accept: */*

Cache-Control: no-cache

Host: api.tatrabanka.sk

Accept-Encoding: gzip, deflate, br

Connection: keep-alive

Content-Length: 0

Note: Please note that Basic Authorization value consists of:

  • prefix Basic
  • whitespace
  • base64Encoded(clientId:secret)  values with colon in between, without quotation
  1. Your application initiates the flow by directing user browser to the authorization endpoint. Initiation is carried out by making a GET.../auth/oauth/v2/authorize request (using /premium/sandbox or /premium/production as base URL).

E.g.: In case of /premium/production link looks like: https://api.tatrabanka.sk/premium/production/auth/oauth/v2/authorize?client_id=xxxxxx&response_type=code&redirect_uri=https://developer.tatrabanka.sk/resources/oauthCallback.html&scope=PREMIUM_AIS&state=1234zyxff&code_challenge=msKUBMZgeTwu-4qvYv3xd5C6LSXmjrW78f9A3PwnY_k&code_challenge_method=S256

  1. The bank authenticates user and establishes whether the user grants or denies your access request.
  2. Assuming user grants access, the bank server redirects the user browser to the result screen where the authorization code is displayed, or back to your application using the redirection URI provided during your application registration. In the latter case, the redirection URI includes an authorization code.
  3. Your application requests an access token from the bank server's token endpoint by including the authorization code received in the previous step. The authorization code exchange is carried out by making a POST.../auth/oauth/v2/token request.

E.g.:

POST https://api.tatrabanka.sk/premium/production/auth/oauth/v2/token

POST /premium/production/auth/oauth/v2/token HTTP/1.1

Authorization: Basic xxxxxxxxx

Content-Type: application/x-www-form-urlencoded

Accept: */*

Cache-Control: no-cache

Host: api.tatrabanka.sk

Accept-Encoding: gzip, deflate, br

Connection: keep-alive

Content-Length: 316

code=cccccccccc&grant_type=authorization_code&scope=PREMIUM_AIS&code_verifier=JxBi5JEhjkkHXJmV~7JxosJtvU6eHHzRAiDXZcObJVeYM7-78P2Dk-I4g2kOiHD-L45VmUCN4A7f75toyW7bcUMqvqUDr9IsdLi4~7IuChC7cAsRbZQpryA25T-2SPV6&redirect_uri=https%3A%2F%2Fdeveloper.tatrabanka.sk%2Fresources%2FoauthCallback.html

 

  1. The bank server authenticates your application, validates the authorization code, and ensures that the redirection URI received matches the URI used to redirect your application in step 3. If valid, the bank server responds back with the access token and refresh token. Issued access token and refresh token expire after 90 days, due to required legislative 90 day re-authorization that is needed.

 

After token revocation

Issued token can be revoked by your user or after time period e.g. 90 days. In this case the bank server responses with HTTP 401 Unauthorized to your API call.

Step 2: Get Consented Accounts List

  1. Your application can initiate GET /v1/accounts request with valid access token.
  2. The bank server validates access token and returns consented accounts list.
  3. Record the accountId parameter, it is used as input for the other API methods

Step 3: Get Account Information and Balances

  1. To provide your user with detail information about account your application initiates GET /v1/accounts/{account-id} request with valid access token.
  2. The bank server validates access token and returns account's detail and balances.

Step 4: Get Account Transactions History

  1. Your application requests account transaction history by GET /v1/accounts/{account-id}/transactions with valid access token.
  2. The bank server validates access token and returns a page with account's transactions.

Pagination

Your application can provide a paginated response for transactions history that returns multiple transaction records. For a paginated responses, please ensure that the number of transaction records on a page (value of pageSize request parameter) are within reasonable limits.

Step 5: Refresh Expired Access Token

When an access token obtained through an authorization code grant expires, your application should attempt to get a new access and refresh token by calling POST /auth/oauth/v2/token. For more information see Section 6 Refreshing an Access Token in of the OAuth 2.0 specification. If your application fails to get an access token using a refresh token, your application would have to get your client to initiate a fresh authorisation code grant using an existing consent