Accounts API Flow

Onboarding your user

Before your first call to account information services API your user should authorize you to access user's personal data.

1. Giving consent from your user to you to access his/her personal banking data

1.1 All consent details have to be defined in your application. Your application initiates the flow by making a POST /consent request. Giving consent is required for each account

We support Detailed Consent Model according to Berlin Group standard with following Consent Acces type accepted:

  • Accounts – with non-empty array of account reference (at least 1 IBAN provided);
  • Balances – with non-empty array of account reference (at least 1 IBAN provided);
  • Transactions - with non-empty array of account reference (at least 1 IBAN provided);

Either the PSU-ID or the PSU-Corporate-ID is mandatory, one of them is required for every POST /consent

From 30.06.2021.

We support Bank offered consent according to Berlin Group standard with the following Consent Access type accepted:

  • Accounts – with a non-empty array of account reference (at least 1 IBAN provided);
  • Balances – with a non-empty array of account reference (at least 1 IBAN provided);
  • Transactions - with a non-empty array of account reference (at least 1 IBAN provided);

Or

  • Accounts – with an empty array of account reference;
  • Balances – with an empty array of account reference;
  • Transactions - with an empty array of account reference;

Either the PSU-ID or the PSU-Corporate-ID is mandatory, one of them is required for every POST /consent and all other consent endpoints.


1.2 The bank sends back to your application a consent ID.
1.3 Your application directs your user browser to the authorization endpoint. Initiation is carried out by making a GET /oauth2/authorize request with consent ID included.
1.4 The bank authenticates your user and establishes whether the user grants or denies your access request. The Bank will perform SCA for the client based on RTS.

From 30.06.2021.

1.4.1 (Accounts provided in the consent) The bank authenticates your user and establishes whether the user grants or denies your access request for the accounts provided in the consent. The Bank will perform SCA for the client based on RTS.

1.4.2 (Accounts not provided in the consent) The bank authenticates your user and offers the users list of accounts for selection and the user grants or denies access request for the selected accounts.


1.5 Assuming your user grants access, the bank server redirects the user browser back to your application using the redirection URI provided during your application registration. The redirection URI includes an authorization code.
1.6 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 /oauth2/token request. 
1.7 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 it is valid, the bank server responds back with an access token and a refresh token. Issued refresh token expires after 90 days when new authorization has to be completed by the client.

After token revocation

An issued token can be revoked by your user or after a time period - 90 days for PSD2 AISP APIs by default. In this case, the bank server responds with HTTP 401 Unauthorized to your API call. In this case, you need to get the giving consent flow again.

2. Get Consented Accounts List

2.1 Your application initiate GET /accounts request with a valid access token.
2.2 The bank server validates access token and returns consented accounts list.

3. Get Account Balances

3.1 To provide your user with balance information about the account your application initiates GET /accounts/{accountId}/balances request with valid access token.
3.2 The bank server validates access token and returns account's detail and balances.

4. Get Account Transactions History

4.1 Your application requests account transaction history by GET /accounts/(accountId)/transactions with valid access token.
4.2 The bank server validates the 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  (for example 50 records).

5. Get Account Transactions History older than 90 days

If parameter "dateFrom" is used in the request and is older than 90 days from the current date, fresh OAuth2 token is required, so you have to complete Step 1 again, otherwise you receive unauthirized error.

6. 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 /oauth2/token. For more information see Section 6 Refreshing an Access Token in of the OAuth 2.0 specification.

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 authorization code grant using an existing consent