Account Information Service Specification

1. Overview

Every IDP is an Account Information Service Provider (AISP) providing clients with access to account information as defined in the PSD2 context.

The Account Information Service follows the Basic Service Protocol and is a profile of Berlin Group’s NextGenPSD2 XS2A Framework (Section 6). This profile combines (a reduced feature set of) Berlin Group’s account information service with the client management framework.

2. Profile Definition

The following features from Berlin Group’s NextGenPSD2 XS2A Framework MUST be supported by IDPs:

Account types: Bank accounts and credit card accounts.
Account information:
- List of accounts (including card accounts) and, for each account, detailed account information.
- Account balances.
- List of transactions, optionally scoped using a start date and end date.
SCA Approach: only the OAuth 2.0 SCA Approach is used and adjusted to the specifics of the client management. For example, IDPs authenticate clients using the certificates registered by these clients with yes.
Consent
- Consent Models: The AIS supports “Bank Offered Consent” (accessible accounts determined by user) only and uses the authorization_details parameter as defined in RAR to convey the account information authorization request details instead of a dedicated consent resource.
- combinedServiceIndicator: not needed since the OAuth-based authorization as utilized by allows a client to request combined authorization for AIS, PIS and other services just by including the respective scope values or authorization details in an authorization request.
API Access Authorization: Access authorization is carried towards AIS endpoints by using OAuth Access Tokens

3. Architecture

The following diagram shows the overall architecture of the Account Information Service.

The Relying Party is a website or app wanting to access account information of its customers. It utilizes the account chooser of the platform to find the IDP of the bank the particular customer wants to use for signing the document(s).

In the architecture, the bank provides access authorization for APIs as well as several APIs for its customers. The Account Information Service is one of those APIs.

The reference architecture assumes that the bank’s authorization server (AS) provides authorization of the access to account information and the AIS relies on the access tokens issued by this AS for access authorization.

Since AS and AIS are typically provided by the same party, there is no need to specify the interface between them. However, it is assumed that the AIS obtains token data from the AS by using the OAuth 2.0 Token Introspection.

The platform manages the trust relationships among all participants. It provides all ASs with data needed to recognize and to authenticate Relying Parties.

The AIS uses the platform to report back any service delivery in order to facilitate billing of the service usage.

4. Message Flow

The following sequence diagram shows the message flow in the curse of an access to account information.

Figure 1. AIS Flow Overview.

5. Service Parameters

The Basic Service Protocol parameters as defined in the [IDP Specification].

Authorization Details Type	`account_information`
Resource Endpoints	The endpoints are obtained from the authorization details returned from the token endpoint.

Authorization Details Type

account_information

Resource Endpoints

The endpoints are obtained from the authorization details returned from the token endpoint.

Following NextGenPSD2 XS2A Framework, for the account access, current accounts and (credit) card accounts are separated on endpoints, since the data is usually separated in the bank backend.

The following is an example service configuration:

{
   "account_information":{ }
}

6. Authorization Process

6.1. Account Information Authorization Details

The RP will use a JSON structure to describe the details of the account information it wants to access. This JSON structure contains the following elements:

type REQUIRED String. MUST be set to account_information.
access REQUIRED JSON Object. Definition of the access requirements of the RP as defined in NextGenPSD2 XS2A Framework, Section 14.16. See below for details.
recurringIndicator REQUIRED boolean: as defined in NextGenPSD2 XS2A Framework, Section 6.3.1.1.
validUntil REQUIRED String (ISO Date): as defined in NextGenPSD2 XS2A Framework, Section 6.3.1.1.
frequencyPerDay REQUIRED Integer: as defined in NextGenPSD2 XS2A Framework, Section 6.3.1.1.

The access element contains up to four subelements further defining the kind of access the RP desires:

accounts OPTIONAL: Array of Account References (see below).
balances OPTIONAL: Array of Account References (see below).
transactions OPTIONAL: Array of Account References (see below).
additionalInformation OPTIONAL JSON Object: MUST contain the key ownerName containing an array of Account References (see below).

The rules defined in NextGenPSD2 XS2A Framework, Section 14.16 apply. When the array of Account References is empty, the RP requests access to all accounts.

A valid Account Reference within this specification contains one of the following keys or key pairs:

iban: as defined in Section 14.18 of NextGenPSD2 XS2A Framework.
maskedPan: as defined in Section 14.18 of NextGenPSD2 XS2A Framework. Note that the maskedPan may not be unique in all cases and thus refer to more than one account.
holderFamilyName and holderGivenName: The AS ensures that the name of an account holder of the debtor account matches the provided given name and family name. MUST NOT be used when AIS is used together with IDS or QES in the same flow.
holderSameName: MAY only be used when AIS is used together with either IDS or QES. Same check as above, but the first name and given name are taken from the IDS or QES flow performed at the same time. MUST NOT be used in conjunction with an IDS flow unless the given_name and family_name are requested as verified claims within the IDS flow.

Here are examples of valid authorization details objects:

Example 1. Account Information Authorization Details (Simple)

{
   "type": "account_information",
   "access": {
      "accounts": [],
      "balances": [],
      "transactions": []
   },
   "recurringIndicator": false,
   "validUntil": "2021-03-12",
   "frequencyPerDay": 1
}

Example 2. Account Information Authorization Details (Extended)

{
   "type": "account_information",
   "access": {
      "accounts": [
         {
            "iban": "DE2299000000184294456"
         }
      ],
      "balances": [
         {
            "iban": "DE2299000000184294456"
         }
      ],
      "transactions": [
         {
            "iban": "DE2299000000184294456"
         }
      ],
      "additionalInformation": {
         "ownerName": [
            {
               "iban": "DE2299000000184294456"
            }
         ]
      }
   },
   "recurringIndicator": true,
   "validUntil": "2022-07-07",
   "frequencyPerDay": 10
}

Example 3. Account Information Authorization Details (With Holder Name Restriction)

{
   "type": "account_information",
   "access": {
      "accounts": [
         {
            "holderFamilyName": "Mustermann",
            "holderGivenName": "Hartmut"
         }
      ],
      "balances": [
         {
            "holderFamilyName": "Mustermann",
            "holderGivenName": "Hartmut"
         }
      ],
      "transactions": [
         {
            "holderFamilyName": "Mustermann",
            "holderGivenName": "Hartmut"
         }
      ],
      "additionalInformation": {
         "ownerName": [
            {
               "holderFamilyName": "Mustermann",
               "holderGivenName": "Hartmut"
            }
         ]
      }
   },
   "recurringIndicator": true,
   "validUntil": "2022-07-07",
   "frequencyPerDay": 10
}

Example 4. Account Information Authorization Details (With Holder Name Restriction IDS/QES)

{
   "type": "account_information",
   "access": {
      "accounts": [
         {
            "holderSameName": true
         }
      ],
      "balances": [
         {
            "holderSameName": true
         }
      ],
      "transactions": [
         {
            "holderSameName": true
         }
      ],
      "additionalInformation": {
         "ownerName": [
            {
               "holderSameName": true
            }
         ]
      }
   },
   "recurringIndicator": true,
   "validUntil": "2022-07-07",
   "frequencyPerDay": 10
}

The AS advertises its support for the authorization of account information access by including the following values into the authorization_data_types_supported claim of its OAuth configuration (.well-known/oauth-authorization-server):

account_information

Example 5. OAuth Configuration

{
   ...
   "authorization_data_types_supported":[
      ...
      "account_information"
   ],
   ...
}

Every RP wanting to access account information must be authorized to request those authorization details type value in its RP configuration with the platform.

6.2. Preparation (Pushed Authorization Request)

The client first sends the authorization request parameters to the AS in a HTTP POST request according to PAR and RAR.

Example 6. Pushed Authorization Request

POST /as/par HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

response_type=code&
client_id=s6BhdRkqt3
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&code_challenge_method=S256
&code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U
&authorization_details=%7B%22type%22:%22account_information%22,%22
access%22:%7B%22accounts%22:%5B%7B%22iban%22:%22DE2299000000184294
456%22%7D%5D,%22balances%22:%5B%7B%22iban%22:%22DE2299000000184294
456%22%7D%5D,%22transactions%22:%5B%7B%22iban%22:%22DE229900000018
4294456%22%7D%5D,%22additionalInformation%22:%7B%22ownerName%22:%5
B%7B%22iban%22:%22DE2299000000184294456%22%7D%5D%7D%7D,%22recurrin
gIndicator%22:true,%22validUntil%22:%222022-07-07%22,%22frequencyP
erDay%22:10%7D

This request contains the account information authorization details in the authorization_details parameter.

the authorization_details MUST NOT contain multiple objects of type account_information, otherwise the AS MUST respond with an status code 400 and the error value invalid_request.

The client authenticates the request using mTLS.

The AS validates the authorization request, including the following checks:

The AS checks whether the provided authorization_details object follows the rules defined and referenced above. If this check fails, the AS terminates processing and sends an error response to the RP with the error code invalid_authorization_details.
The AS checks whether the RP is allowed to use the type value account_information by checking the allowed_authorization_data_types field of the respective RP record obtained from the platform. If this check fails, the AS terminates processing and sends an error response the the RP with the error code access_denied.

If all checks succeed, the AS returns a request URI as shown in the following example.

Example 7. Pushed Authorization Response

HTTP/1.1 201 Created
Cache-Control: no-cache, no-store
Content-Type: application/json

{
   "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2",
   "expires_in": 90
}

6.3. Authentication and Authorization (OAuth Frontend Part)

The client uses the request URI to start the authorization process with the AS by sending an authorization request through the user agent.

Example 8. Authorization Request

GET /authorize?request_uri=
    urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1

The AS will authenticate the user and ask for her consent (using the data conveyed in the authorization_details). This includes the selection of the accounts, the scope of access the user wants to grant to the RP, the duration of the access (validUntil), and the time frame of transactions accessible to the RP.

If the RP provides Account References in its request and the references can be matched to accounts of the logged in user, the IDP should indicate to the user that access to these accounts is likely required to complete the action at the RP.

If the user does not consent to access to any accounts or no (consented) accounts match the Account References given by the RP, the IDP should provide guidance to the user to sucessfully complete the transaction by granting access to accounts or by using a different online banking login. The IDP MUST NOT complete a transaction in which no access is given to the RP, but abort the transaction instead (error code access_denied).

After the user confirmed the transaction, the AS responds to the RP with an OAuth authorization response.

6.4. Authentication and Authorization (OAuth Backend Part)

The RP will redeem the authorization code provided in the authorization response for an access token.

The token response contains an authorization_details response parameter that is enriched with the data about the accounts (incl. card accounts) and the scope of access the user has granted to the RP. It further contains the account_information element with the following subelements:

txn: carries a unique identifier for the transaction defined by the AS.
accounts_href and card_accounts_href: provides the RP with the URLs at which it can retrieve the (card) account information; may be the same value for both types of accounts. The URLs MUST be https URLs, relative URLs are not allowed. The URLs do not need to be on the same host as the AS.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "example",
    "expires_in": 3600,
    "refresh_token": "tGzv3JokF0XG5Qx2TlKWIA",
    "authorization_details": [
        {
            "type": "account_information",
            "access": {
                "accounts": [
                    {
                        "iban": "DE2310010010123456789"
                    },
                    {
                        "maskedPan": "123456xxxxxx1234"
                    }
                ],
                "balances": [
                    {
                        "iban": "DE2310010010123456789"
                    }
                ],
                "transactions": [
                    {
                        "iban": "DE2310010010123456789"
                    },
                    {
                        "maskedPan": "123456xxxxxx1234"
                    }
                ]
            },
            "recurringIndicator": true,
            "validUntil": "2022-07-07",
            "frequencyPerDay": 10,
            "account_information": {
               "accounts_href": "https://ais.example-bank.com/ais/accounts",
               "card_accounts_href": "https://ais.example-bank.com/ais/cardAccounts",
               "txn": "9fe0d04d-7094-4f28-8c1b-6776d13814a4"
            }
        }
    ]
}

In case the recurringIndicator is set to true, the AS SHOULD issue a refresh token the RP can later use to obtain fresh access tokens.

7. Accessing Account Information

(Card) account information is requested and returned using the accounts_href and card_accounts_href endpoints according to the API defined in Section 6.6. of NextGenPSD2 XS2A Framework. Note that none of the request headers defined therein are supported or required, except for the Authorization header. The query parameter withBalance is supported.

All endpoints for account information access MUST only be accessible using the access token issued from the AS, using mTLS as the token binding method.

The element ownerName is contained if the owner name was requested using additionalInformation.

The following shows an example request and response for the accounts endpoint:

GET /ais/accounts
Host: ais.example-bank.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

HTTP/1.1 200 OK
Content-Type: application/json

{
   "accounts":[
      {
         "resourceId":"3dc3d5b3-7023-4848-9853-f5400a64e80f",
         "iban":"DE2310010010123456789",
         "currency":"EUR",
         "product":"Girokonto",
         "cashAccountType":"CACC",
         "name":"Main Account",
         "ownerName": "Hartmut Mustermann",
         "_links":{
            "balances":{
               "href":"/ais/accounts/3dc3d5b3-7023-4848-9853-f5400a64e80f/balances"
            },
            "transactions":{
               "href":"/ais/accounts/3dc3d5b3-7023-4848-9853-f5400a64e80f/transactions"
            }
         }
      }
   ]
}

The response body fields correspond to those defined in Berlin Group’s NextGenPSD2 XS2A Framework, Section 6.5.1.

8. Accessing Balances and Transactions

Using the links given in the request to the accounts endpoints, balances and transactions for a specific account can be retrieved.

8.1. Balances

Balances are requested and returned according to the API defined in Section 6.6. of NextGenPSD2 XS2A Framework. Note that none of the request headers defined therein are supported or required, except for the Authorization header.

8.2. Transactions

Transactions are requested and returned according to the API defined in Section 6.6. of NextGenPSD2 XS2A Framework. Note that none of the request headers defined therein are supported or required, except for:

withBalance to include the balance in the response,
dateFrom and dateTo to define the starting date and end date, respectively, of the list of transactions returned.

If not defined, dateTo defaults to the current date (in the time zone of the bank). If not defined, dateFrom defaults to 90 days before dateTo.

9. Billing Mediation

The service MUST report any access to account information to the Mediation Service.

Filing more than one mediation record per request might be necessary in certain cases. The account list and transactions can be retrieved together with account balances (using the withBalance parameter). In this case, two or more mediation records need to be created: One for the main operation (account information or transaction list) and one for each account’s balances contained in the response.

9.1. Account Information

Immediately before or after a response is sent to the RP from the account information endpoint, a mediation record MUST be posted to the mediation service.

The mediation record MUST contain the following data:

type is set to ais_accounts
issuer: set to the Issuer URL of the IDP
client_id: set to the client_id of the RP
additionalInformation: array of additional information elements that were delivered if they were delivered for at least one account, identified by their name; currently either an empty array or ["ownerName"].
transaction_id: set to the transaction identifier at the AS, same value as the txn claim returned in the token response
delivery_time: the time when the data was delivered to the RP
owner_id: the respective owner_id (see Platform API Documentation for details)
reference_id: OPTIONAL. String (1 to 100 characters restricted to a-z, A-Z, 0-9 and dashes ("-"), e.g., a uuid) generated by the AS as unique mediation record id to prevent multiple mediation records for the same event. Uniqueness is considered per AS (issuer element). If the field is provided in the mediation record, the mediation service checks whether a mediation record with the same reference_id for the the same issuer already exists and will refuse processing in that case.

9.2. Transactions

Immediately before or after a response is sent to the RP that contains transaction information, a mediation record MUST be posted to the mediation service.

The mediation record MUST contain the following data:

type is set to ais_transactions
issuer: set to the Issuer URL of the IDP
client_id: set to the client_id of the RP
accountType: set to either account or cardAccount, depending on the type of account accessed
dateFrom, dateTo: set to the respective values in the AIS transactions access request; or equivalent calculated from default access history duration if parameters where not given
recordCount: Number of transaction records delivered
transaction_id: set to the transaction identifier at the AS, same value as the txn claim returned in the token response
delivery_time: the time when the data was delivered to the RP
owner_id: the respective owner_id (see Platform API Documentation for details)
reference_id: OPTIONAL. String (1 to 100 characters restricted to a-z, A-Z, 0-9 and dashes ("-"), e.g., a uuid) generated by the AS as unique mediation record id to prevent multiple mediation records for the same event. Uniqueness is considered per AS (issuer element). If the field is provided in the mediation record, the mediation service checks whether a mediation record with the same reference_id for the the same issuer already exists and will refuse processing in that case.

9.3. Balances

Immediately before or after a response is sent to the RP that contains balance information, a mediation record MUST be posted to the mediation service. A separate mediation record MUST be created for each account for which balances are included in the response.

The mediation record MUST contain the following data:

type is set to ais_balances
issuer: set to the Issuer URL of the IDP
client_id: set to the client_id of the RP
accountType: set to either account or cardAccount, depending on the type of account for which the balances were retrieved
transaction_id: set to the transaction identifier at the AS, same value as the txn claim returned in the token response
delivery_time: the time when the data was delivered to the RP
owner_id: the respective owner_id (see Platform API Documentation for details)
reference_id: OPTIONAL. String (1 to 100 characters restricted to a-z, A-Z, 0-9 and dashes ("-"), e.g., a uuid) generated by the AS as unique mediation record id to prevent multiple mediation records for the same event. Uniqueness is considered per AS (issuer element). If the field is provided in the mediation record, the mediation service checks whether a mediation record with the same reference_id for the the same issuer already exists and will refuse processing in that case.

10. Changes

Version 1.3
- AIS endpoints now in enriched RAR object at token endpoint
- Introduced account constraints (holder and IBAN)
- Introduced transaction identifier
- Introduced account owner
Version 1.3 (beta)
- Adapted AIS to rich/pushed authorization requests mechanics
Version 1.2 (2019-08-28)
- Added billing mediation
- Reworked account holder information.
- Added credit card transactions.
- Added time period requests for transactions.
Version 1.1 (2019-09-04)
- Added sequence chart