Step 1: Authorize User's Accounts Consent
User's Accounts Consent follows OAuth 2.0 Authorization Code Grant flow.
Your application initiates the flow by directing your user browser to the authorization endpoint. Initiation is carried out by making a
- The bank authenticates your user and identifies whether the user grants or denies your access request
- If 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
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
- 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 a refresh token. Issued token expires after 90 days.
Your user onboarding
Before your first call to account information services API your user should authorize you to access user's personal data.
Issued token might become invalid in following cases:
- it can be revoked by your user or
- it can expire 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
Your application initiate
GET /api/v1/accountsrequest with valid access token.
- The bank server validates access token and returns consented accounts list.
Add new account
Your application can provide to your customer option to select one or more accounts from consented accounts list instead of typing IBAN to your application.
In case of your customer types its IBAN in your application just omit Step 2 and make a call in Step 3 with typed IBAN.
Step 3: Get Account Information and Balances
Your application requests detailed account information by
POST /api/v1/accounts/informationrequest with valid access token.
- The bank server validates access token and returns account's detail and balances.
Step 4: Get Account Transactions History
Your application requests account transaction history by
POST /api/v1/accounts/transactionsrequest with valid access token.
- The bank server validates access token and returns a page with account's transactions.
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 - a minimum of 10 records (except on the last page where there are no further records) and a maximum of 100 records.
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 new authorisation code grant using an existing consent.