Version Control

Overview

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

...

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:

...

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

Basics

Overview

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

Steps

Step 1: Request Account Information

...

• 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

participant PSU
participant AISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
   
note over PSU, ASPSP Resource Server
    Step 1: Request account information
end note
PSU -> AISP: Get account/transaction information
  
note over PSU, ASPSP Resource Server
    Step 2: Setup account access consent
end note
AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
AISP -> ASPSP Authorisation Server: Initiate Client Credentials Grant
ASPSP Authorisation Server -> AISP: access-token
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: POST /account-access-consents
state over ASPSP Resource Server: Consent Status: AwaitingAuthorisation
ASPSP Resource Server -> AISP: HTTP 201 (Created), ConsentId
  
note over PSU, ASPSP Resource Server
Step 3: Authorise consent
end note
alt Redirection (Using Authorization Code Grant)
        AISP -> PSU: HTTP 302 (Found), Redirect (ConsentId)
        PSU -> ASPSP Authorisation Server: Follow redirect (ConsentId)
        PSU <-> ASPSP Authorisation Server: authenticate
        PSU <-> ASPSP Authorisation Server: SCA if required
        PSU <-> ASPSP Authorisation Server: select accounts
        state over ASPSP Resource Server: Consent Status: Authorised
        ASPSP Authorisation Server -> PSU: HTTP 302 (Found), Redirect (authorization-code)
        PSU -> AISP: Follow redirect (authorization-code)
        AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
        AISP -> ASPSP Authorisation Server: Exchange authorization-code for access token
        ASPSP Authorisation Server -> AISP: access-token
    else Decoupled (Using CIBA)
        AISP -> ASPSP Authorisation Server: POST /bc-authorize (login_hint_token)
        ASPSP Authorisation Server -> AISP: OK
        
        PSU -> ASPSP Authorisation Server: Authorise (Consent Id)
        PSU <-> ASPSP Authorisation Server: authenticate
        PSU <-> ASPSP Authorisation Server: SCA if required
        PSU <-> ASPSP Authorisation Server: select accounts
        state over ASPSP Resource Server: Consent Status: Authorised

        alt Using callback
                ASPSP Authorisation Server -> AISP: Callback (authorization-code)
                AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
                AISP -> ASPSP Authorisation Server: Exchange authorization-code for access token
                ASPSP Authorisation Server -> AISP: access-token
        else Using polling
                AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
                AISP -> ASPSP Authorisation Server: Poll at /token using auth-req-id
                ASPSP Authorisation Server -> AISP: access-token
        end alt
end alt


   
note over PSU, ASPSP Resource Server
Step 4: Request data
end note
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: GET /accounts
ASPSP Resource Server -> AISP: HTTP 200 (OK), List of accounts containing AccountId(s)
   
   
AISP -> ASPSP Resource Server: GET /accounts/{AccountId}/transactions
ASPSP Resource Server -> AISP: HTTP 200 (OK), List of transactions
option footer=bar

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 doesn't 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).

...

Security & Access Control

Scopes

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

accounts 

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 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.

...

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. 

...

Detail Permissions

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

...

In addition the ReadStatementsDetail is required to access the statement file download via: /accounts/{AccountId}/statements/{StatementId}/file

...

Example behaviour of the Permissions for the ReadAccountsBasic and ReadAccountsDetail codes is as follows:

Reversing Entries

It is expected that transactions will be returned in the payload irrespective of whether they are reversing entries as long as the PSU has provided consent for that type of transaction.

...

If the PSU has provided permission for ReadTransactionsDebits, the ASPSP must include all debits including credit reversals.

Expiration Date Time

The ExpirationDateTime is an optional field which specifies the expiration for AISP access to the PSU's data.

...

The ExpirationDateTime applies to all Permissions (data clusters) being consented.

Transaction To/From Date Time

The TransactionToDateTime and the TransactionFromDateTime specify the period for consented transaction and/or statement history. Both the fields are optional and one may be specified without the other.

...

The AISP must be restricted to accessing statements which are completely within this period when accessing the statements resource.

Account Access Consent Status

The Account Access Consent resource may have one of the following status codes after authorisation has taken place:

Consent Re-authentication

Account Access Consents are long-lived consents.

...

An ASPSP may allow the PSU to change the selected accounts during consent re-authentication.

Consent Revocation

A PSU may revoke consent for accessing account information at any point in time.

...

• The AISP must cease to access the APIs at that point
• The AISP must call the DELETE operation on the account-access-consent resource (before confirming consent revocation with the PSU) to indicate to the ASPSP that the PSU has revoked consent

Changes to Selected Account(s)

The PSU must select the accounts to which the consent should be applied at the point of consent authorisation.

...

In such a situation, only the affected account is removed from the list of selected accounts. The ASPSP must not revoke authorisation to other accounts.

Risk Scoring Information

Information for risk scoring and assessment will come via:

...

No fields for business logic security concerns have been identified for the Account Info APIs.

Data Model

Using Meta to identify Available Transaction Period

For Accounts & Transaction APIs, the Meta section in API responses may contain two additional fields to indicate the date range for which data has been returned.

...

  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }

Mapping to Schemes & Standards

The Account Info API resources, where possible, have been borrowed from the ISO 20022 camt.052 XML standard. However - has been adapted for APIs based as per our design principles. 

...

• The camt.052 header section and trailer sections have been removed - as these are not required for a RESTful API
• Resources have been identified, and payload structures have been designed for these resources - rather than a full message (i.e., camt.052) that encompasses all resources in a report format. This has meant we've designed separate endpoints and payloads to cover:
  • accounts
  • balances
  • beneficiaries
  • direct-debits
  • offers
  • party
  • products
  • standing-orders
  • statements
  • transactions
  • scheduled-payments
• New payloads have been designed for beneficiaries, direct-debits, standing-orders, and products resources - as these are not in the ISO 20022 standard (or the camt.052 message)
• A DateTime element has been used instead of a complex choice element of Date and DateTime (across all API endpoints). Where time elements do not exist in ASPSP systems - the expectation is the time portion of the DateTime element will be defaulted to 00:00:00+00:00
• Variations for the accounts structure include: 
  • Standardised inline with the Payment API account structures
  • Contains elements to identify an account Nickname, SecondaryIdentification
• Variations for the balances structure include:
  • Adding a Type into the CreditLine section - to allow for multiple credit line types affecting the available balance
  • DateTime element has been specified instead of a complex choice of Date and DateTime

• Variations for the transactions structure include:

  • Renaming "entry" to "transaction" for consistency - as this is the language used in the CMA Order, and PSD2

  • DateTime elements used instead of a complex choice of Date and DateTime

  • Flattening of the structure for BankTransactionCode and ProprietaryBankTransactionCode

  • Additional information for an AddressLine, MerchantDetails, and a running Balance

Resources

Each of the Account and Transaction API resources are documented in sub-pages of this specification. Each resource is documented with:

• Endpoints
  • The API endpoints available for the resource
• Data Model
  • Resource definition
  • UML diagram
  • Permissions as they relate to accessing the resource
  • Data dictionary - whcih defines fields, re-usable classes, mandatory (1..1) or conditional (0..1) as defined in the Design Principles section, and enumerations
• Usage Examples

Enumerations

Static Enumerations

Namespaced Enumerations

The enumerated values specified by Open Banking are documented in Developer Zone and will be prefixed by UK.OBIE 

Swagger Specification

The Swagger Specification for Account Information APIs can be downloaded from the following links:

...