Version Control

Overview

This specification describes the Account Information and Transaction API flows and payloads.

The API endpoints described here allow an Account Information Service Provider ('AISP') to: 

• Register an intent to retrieve account information by creating an "account access consent". This registers the data "permissions", expiration and historical period allowed for transactions / statements - that the customer (PSU) has consented to provide to the AISP; and 

• Subsequently, retrieve account and transaction data.

This specification should be read in conjunction with Read/Write Data API Specification  which provides a description of the elements that are common across all the Read/Write Data APIs.

Document Structure

This document consists of the following parts:

Overview: Provides an overview of the API and the key decisions and principles that contributed to the specification.

Basics: Identifies the resources, operations that are permitted on those resources, and various special cases.

Endpoints: Provides the list of endpoints for the API specification. The individual end-points are documented in separate pages along with the data model that they employ and usage examples.

Security & Access Control: Specifies the means for AISPs and PSUs to authenticate themselves and provide consent.

Data & Payloads: Documents data structures and data architecture that applies to all the end-points. End-point specific data structures are documented in separate pages along with the end-points that employ the data structure.

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Basics

Overview

The figure below provides a general outline of an account information request and flow using the Account Info APIs.

Open

Steps

Step 1: Request Account Information

• This flow begins with a PSU consenting to allow an AISP to access account information data. 

Step 2: Setup Account Access Consent

• The AISP connects to the ASPSP that services the PSU's account(s) and creates an account-access-consent resource. This informs the ASPSP that one of its PSUs is granting access to account and transaction information to an AISP. The ASPSP responds with an identifier for the resource (the ConsentId - which is the intent identifier). This step is carried out by making a POST request to /account-access-consents endpoint.

• The account-access-consent resource will include these fields below - which describe the data that the PSU has consented with the AISP:

  • Permissions - a list of data clusters that have been consented for access.

  • Expiration Date - an optional expiration for when the AISP will no longer have access to the PSU's data.

  • Transaction Validity Period - the From/To date range which specifies a historical period for transactions and statements which may be accessed by the AISP.

• An AISP may be a broker for data to other parties, and so it is valid for a PSU to have multiple account-access-consents for the same accounts, with different consent/authorisation parameters agreed. 

Step 3: Authorise Consent

• The AISP requests the PSU to authorise the consent. The ASPSP may carry this out by using a redirection flow or a decoupled flow.

  • In a redirection flow, the AISP redirects the PSU to the ASPSP.

    • The redirect includes the ConsentId generated in the previous step.

    • This allows the ASPSP to correlate the account-access-consent that was setup.

    • The ASPSP authenticates the PSU.

    • The ASPSP updates the state of the account-access-consent resource internally to indicate that the account access consent has been authorised.

    • Once the consent has been authorised, the PSU is redirected back to the AISP.

  • In a decoupled flow, the ASPSP requests the PSU to authorise consent on an authentication device that is separate from the consumption device on which the PSU is interacting with the AISP.

    • The decoupled flow is initiated by the AISP calling a back-channel authorisation request.

    • The request contains a 'hint' that identifies the PSU, paired with the consent to be authorised.

    • The ASPSP authenticates the PSU and updates the state of the account-access-consent resource internally to indicate that the account access consent has been authorised.

    • Once the consent has been authorised, the ASPSP can make a callback to the AISP to provide an access token.

• The principle we have agreed is that consent is managed between the PSU and the AISP - so the account-access-consent details must not be changed (with the ASPSP) in this step. The PSU will only be able to authorise or reject the account-access-consent details in its entirety.

• During authorisation, the PSU selects accounts that are authorised for the AISP request (in the ASPSP's banking interface).

Step 4: Request Data

• This is carried out by making a GET request the relevant resource.

• The unique AccountId(s) that are valid for the account-access-consent will be returned with a call to GET /accounts. This will always be the first call once an AISP has a valid access token.

Sequence Diagram

Open

Idempotency

The API endpoints for creating account-access-consent resources are not idempotent.

If a time-out error occurs - then we would expect an AISP to create a new account-access-consent resource - rather than try with the same resource.

Release Management

This section overviews the release management and versioning strategy for the Account and Transaction API.

Account Access Consent

The account-access-consent resource is referred to as an account-request resource in v1 and v2 of this specification. For clarity, it has been generalised to 'Consent' in the detail below.

POST

• An AISP must not create a Consent on a newer version, and use it on a previous version

  • E.g., A ConsentId for an account-access-consent created in v3, must not be used to access v2 endpoints.

GET

• An AISP must not access a Consent on an older version, via the Id for a Consent created in a newer version:

  • E.g., An account-access-consent created in v3 accessed via v2 account-request.

• An ASPSP must allow a Consent to be accessed in a newer version.

• An ASPSP must ensure Permissions set associated with a Consent are unchanged when accessed in a different version:

  • E.g., An account-request created in v2 will have the same details when accessed via v2 and v3 (as an account-access-consent).

• An ASPSP must ensure a Consent's fields are unchanged when accessed in a different version.

• An ASPSP may allow expired Consents to be accessed in a newer version.

• An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all (if not mandatory):

  • E.g., OBReadResponse1/Data/StatusUpdateDateTime introduced in v2 accessed with v1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records.

DELETE

• An AISP must not delete a Consent on an older version, via an Id for a Consent created in a newer version:

  • E.g., An account-access-consent is created in v3, and request DELETE on v2.

• An ASPSP must support deleting a Consent from a previous version via a newer version:

  • E.g., An account-request is created in v2, and request DELETE on v3.

Account Information Resources

GET

• An AISP may use a token that is bound to a Consent in a previous version, to access an endpoint of a newer version.

• An AISP may use an Id for a Consent created in a previous version to retrieve Account Information resources in a newer version:

  • E.g., AccountRequestId from v2 can be used as ConsentId in v3, to GET /accounts.

• An AISP must not use an Id for a Consent from a newer version to access Account Information resources in a previous version:

  • E.g., ConsentId for an account-access-consent created in v3, must not be used to access v2 Account Information endpoints.

• An AISP must not use an Id for a Consent from a previous version to access a resource introduced in a newer version (as the Consent will not have Permissions required to access the new resource).

• An ASPSP must allow an AISP to use an Id for a Consent from a previous version to access Account Information resource endpoints in a newer version:

  • E.g., AccountRequestId created in v2 must be allowed to access Account Information resource endpoints in v3.

• An ASPSP must reject the request to access a resource, for which a Consent's Permissions set does not permit.

• An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all:

  • E.g., OBReadResponse1/Data/StatusUpdateDateTime introduced in Version2 accessed with V1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records.

Endpoints

This section looks at the list of available API endpoints to access Account Information and Transaction data and optionality (definitions of mandatory, conditional or optional are defined in the Principles section).

Endpoint design considerations:

• Having resources that are finer grained (e.g., beneficiaries, direct-debits, standing-orders) means that we can, in the future, manage these resources (with unique identifiers).

• While balances is not a typical resource - we believe having an /accounts/{AccountId}/balances endpoint is simpler to understand than a URI to expand the /accounts resource .

• Some ASPSPs were uncomfortable implementing the bulk APIs (e.g., /accounts, /transactions, /beneficiaries etc.) so the bulk APIs have been specified as optional. However, the bulk endpoint for /accounts is mandatory to discover what accounts have been authorised for the account-access-consent.

We have specified the "mandatory" endpoints for the functioning of the Account Info APIs.

However, endpoints will not be "mandatory" if ASPSPs do not provide these resources via existing online channels e.g., direct debits, standing orders, statements.

Security & Access Control

Scopes

The access tokens required for accessing the Account Info APIs must have at least the following scope:

Scopes

Grants Types

AISPs must use a client credentials grant to obtain a token to access the account-access-consents resource. In the specification, this grant type is referred to as "Client Credentials".

AISPs must use an authorization code grant using a redirect or decoupled flow to obtain a token to access all other resources. In the specification, this grant type is referred to as "Authorization Code".

Consent Authorisation

The AISP must create an account-access-consent resource through a POST operation. This resource indicates the consent that the AISP claims it has been given by the PSU to retrieve account and transaction information. At this stage, the consent is not yet authorised as the ASPSP has not yet verified this claim with the PSU.

The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).

As part of the consent authorization flow:

• The ASPSP authenticates the PSU.

• The ASPSP plays back the consent (registered by the AISP) back to the PSU - to get consent authorisation. The PSU may accept or reject the consent in its entirety (but not selectively).

• The ASPSP presents the PSU with a list of accounts to which the consent will apply.

Once these steps are complete, the consent is considered to have been authorised by the PSU.

Consent Elements

The Account Access Consent resource consists of the following fields, which together form the elements of the consent provided by the PSU to the AISP:

• Permissions: The set of data clusters that the PSU has consented to allow the AISP to access.

• ExpirationDateTime: The date-time up to which the consent is valid.

• TransactionFromDateTime: The earliest point of the transaction / statement historical period that the PSU has consented to provide access to the AISP.

• TransactionToDateTime: The last point of the transaction / statement historical period that the PSU has consented to provide access to the AISP.

Permissions

Permissions codes will be used to limit the data that is returned in response to a resource request. 

When a permission is granted for a "Detail" permission code (e.g., ReadAccountsDetail) it implies that access is also granted to the corresponding "Basic" permission code (e.g., ReadAccountsBasic).

While it is duplication for a TPP to request a "Basic" permission code and the corresponding "Detail" permission code, it is not a malformed request, and the ASPSP must not reject solely on the basis of duplication.

The permissions array must contain at least ReadAccountsBasic or ReadAccountsDetail.

The following combinations of permissions are not allowed, and the ASPSP must reject these account-access-consents with a 400 response code:

• Account Access Consents with an empty Permissions array.

• Account Access Consents with a permission code that is not supported by the ASPSP (ASPSPs are expected to publish which API endpoints are supported).

• Account Access Consents with a Permissions array that contains ReadTransactionsBasic but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits.

• Account Access Consents with a Permissions array that contains ReadTransactionsDetail but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits.

• Account Access Consents with a Permissions array that contains ReadTransactionsCredits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail.

• Account Access Consents with a Permissions array that contains ReadTransactionsDebits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail.

Detail Permissions

The additional elements that are granted for "Detail" permissions are listed in this section.

All other fields (other than these fields listed) are available with the "Basic" Permission access.