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

The API endpoints described here allow an AISP to: 

• Register an intent to retrieve account information by creating an "account request". This registers the data "permissions", expiration and transaction history timeframe the customer (PSU) has consented to provide to the AISP; and 

• Subsequently retrieve account and transaction data

This document consists of the following parts:

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

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

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

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

Data Model: Describes the data model for the API payloads.

Usage Examples: Examples for normal flows, and alternate flows.

The API adheres to RESTful API concepts where possible and sensible to do so.

However, the priority is to have an API that is simple to understand and easy to use. In instances where following RESTful principles would be convoluted and complex, the principles have not been followed.

References:

• The highest level Data Description Language used is the JSON Schema : http://json-schema.org/

• Best Practice has also been taken from the Data Description Language for APIs; JSON API : http://jsonapi.org/

• The Interface Description Language used is the Swagger Specification version 2.0 (also known as Open API) : http://swagger.io/ and 

The OBIE principles for developing the new API standards:

• OBIE will adopt existing standards where relevant/appropriate to minimise re-inventing the wheel.

• The initial scope of these Standards is limited to current OBIE scope - i.e., meeting CMA remedies. However, the intention is that the scope of the Standards will extend to either include or align to initiatives to cover a wider scope (i.e., PSD2).

• The Standards currently being reviewed include ISO20022, and FAPI.

• OBIE will favour developer/user experience over and above adoption of existing Standards, in order to create a more future proof Standard.

• OBIE will work with other relevant bodies to align with, contribute to and/or adopt other Standards work, especially relating to creation of Standards around APIs and JSON payloads

The CMA Order requires the CMA9 Banks to be aligned with the Regulatory and Technical Standards (RTS) under PSD2.

A previous draft of the EBA RTS required that the interface "shall use ISO 20022 elements, components or approved message definitions". In keeping with that requirement, the API payloads are designed using the ISO 20022 message elements and components where available.

The principles we have applied to re-use of ISO message elements and components are:

• Where relevant - the API payloads have been flattened so that they are more developer friendly. This has been a request from the developer community, and the stakeholders involved in the design workshop

• Only elements that are required for the functioning of the API endpoint will be included in the API payload. API endpoints are defined for specific use-cases (not to be generically extensible for all use-cases). Hence - only elements that are required for the account and transaction information scope are included in the Account Information API payloads for v1.0 (as this is the agreed scope for our v1.0 specification).

• We will modify ISO 20022 elements where the existing standard does not cater for an API context (such as filtering, pagination etc.). An example is having latitude and longitude in decimal format - as this is how developers will work with latitude and longitude; or using simple types (e.g., a single date-time field) instead of a complex type (e.g., a choice field with a nesting of date and time).

Version 1.0 of the API only caters to read access to account and transaction information for BCAs and PCAs.

However - where possible the APIs have been designed to be extensible - so they can in the future cover additional account types (e.g., card accounts) and operations (e.g., write access).

The Account Information and Transaction APIs will not be idempotent for v1.0.

The APIs will provide non-repudiation through digital signatures.

The specifications required to achieve this are described in Basics / Non-repudiation.

A REST resource should have a unique identifier (e.g. a primary key) that can be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

However, considering that:

• Some of the resources described in this specification do not have a primary key in the system of record.

• For v1.0 it is not neccessary to individually address resources,

a decision has been made that Id fields will be specified for all resources - but be optional for all resources, except for the account resource.

The account resource needs to be addressed individually and must have a mandatory, unique and non-mutable identifier.

The APIs specified in this document provide the ability for AISPs to access a PSU's account and transaction information for domestic PCA and BCA accounts.

This v1.0 specification does not cater for:

• Write operations (the ability to create) standing orders, direct debits and beneficiaries.

• Accounts other than PCAs and BCAs.

• Progressive or changing consent - if the consent between the AISP and PSU changes, then the existing account-request object is deleted and a new account-request is created with the new consent/authorisation details.

• The ability for the AISP to pre-specify the list of accounts that have been agreed with the PSU for consent/authorisation. At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time (e.g, customers adding or deleting accounts) affects the original agreed authorisation. 

• The ability for the AISP to specify and "hints" for the types of accounts that have been agreed with the PSU for consent/authorisation (e.g., product or customer channel types). At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time affects the original agreed authorisation. 

• Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are are not in the v1.0 specification.

• Non-functional requirements and specification of caching and throttling.

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

Open

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 Request

• The AISP connects to the ASPSP that services the PSU's account(s) and creates an account-request 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 AccountRequestId - which is the intent identifier).

• This step is carried out by making a POST request to /account-requests endpoint

• The setup payload will include these fields - 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 transaction history period which can be accessed by the AISP

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

Step 3: Authorise Consent

• The AISP redirects the PSU to the ASPSP. The redirect includes the AccountRequestId generated in the previous step. This allows the ASPSP to correlate the account-request that was setup. The ASPSP authenticates the PSU. The ASPSP updates the state of the account-request resource internally to indicate that the account request has been authorised.

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

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

• The PSU is redirected back to the AISP.

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-request will be returned with a call to GET /accounts. This will always be the first call once an AISP has a valid access token.

Open

The following headers SHOULD be inserted by the TPP in each API call:

(Reference: Section 6.3 - Financial API — Part 1: Read Only API Security Profile (Implementer’s Draft).)

Whether the PSU is present or not-present is identified via the x-fapi-customer-ip-address header. If the PSU IP address is supplied, it is inferred that the PSU is present during the interaction.

The implications to this are:

• ASPSPs will need to rely on AISPs assertion.

• As agreed at TDA (18/05) It will be up to the ASPSPs to interpret the 4-times customer not present rule - to be within the “spirit” of the RTS requirement.

• This is dependent on GDPR considerations on the AISP passing a PSU's IP address to an ASPSP.

The following are the HTTP response codes for the different HTTP methods - across all Account Info API endpoints.

An ASPSP MAY return other standard HTTP status codes (e.g. from gateways and other edge devices) as described in RFC 7231 - Section 6.

When a TPP tries to request a resource URL with an resource Id that does not exist, the ASPSP must respond with a 400 (Bad Request) rather than a 404 (Not Found).

E.g., if a TPP tries to GET /accounts/22289 where 22289 is not a valid AccountId, the ASPSP must respond with a 400.

When a TPP tries to request a resource URL that results in no business data being returned (e.g. a request to retrieve standing order on an account that does not have standing orders) the ASPSP must respond with a 200 (OK) and set the array to be empty.

If the TPP tries to access a URL for a resource that is not defined by these specifications (e.g. GET /card-accounts), the ASPSP may choose to respond with a 404 (Not Found).

If an ASPSP has not implemented an optional API, it must respond with a 404 (Not Found) for requests to that URL.

The table below illustrates some examples of expected behaviour:

When a TPP tries to access a resource that it does not have permission to access, the ASPSP must return a 403 (Forbidden).

The situation could arise when:

• The TPP uses an access token that is no longer valid

• The TPP uses an access token that does not have the approporiate scope to access the requested resource.

• The TPP does not have a consent authorisation for the AccountId
  E.g., an attempt to access GET /accounts/2001 or /accounts/2001/transactions when the PSU has not selected AccountId 2001 for authorisation.

• The TPP does not have a consent authorisation with the right Persmissions to access the requested resource.
  E.g., an attempt to access GET /standing-orders when the ReadStandingOrdersBasic permission was not included in the consent authorisation.

• The TPP attempted to access a resource with an Id that it does not have access to.
  E.g., an attempt to access GET /account-requests/1001 where an account-request resource with Id 1001 belongs to another TPP.
  
  

When a TPP tries to access a resource too frequently the ASPSP may return a 429 (Too Many Requests).  This is a Non Functional Requirement and is down to individual ASPSPs to decide throttling limits. 

This situation could arise when:

• The TPP has not implemented caching, it requests transactions for a PSU account, and constantly re-requests the same transactions 

• Similarly for any of the PSU information endpoints 

The following pre-conditions must be satisfied in order to use these APIs:

1. The TPP must have completed onboarding on the Open Banking Directory