Version Control

Release Note

This release note explains what's new in Read/Write Data API Specifications v2.0.0.

For clarity, the specifications have now been divided as follows:

Key Changes

Account and Transaction API Specification v2.0.0.

Supporting Open Data for standardised back-book products (Personal Current Accounts ‘PCA’ and Business Current Accounts ‘BCA’)

For PCA and BCA accounts, v1 of the read/write API specifications included a 'products' endpoint within the Account Information and Transaction API. This enabled a referential model, where a TPP could access the PSU's account and retrieve the product ID for on-sale accounts. This ID could then be used to reference the corresponding product information in the Open Data standard. Version 2 extends the capability of the ‘products’ endpoint within the Account Information and Transaction API so TPP’s can directly access key product data for PSU’s who have a back book product, in the event the back-book product is not available in the Open Data standard.

High level changes from v1.1 include:

• Restructure of the top level OBReadProduct2 as follows:

  • ProductName

  • ProductId

  • AccountId

  • SecondaryProductId

  • MarketingStateId

  • ProductType

• Extended ProductType enumeration:

  • Additional PCA object

  • Additional BCA object

Extension to PSD2 in-scope accounts (sterling)

Version 2.0.0 extends the Account and Transaction API to cover other PSD2 in-scope payment accounts (limited to GBP accounts) in addition to personal and business current accounts covered by v1. These additional payment accounts are as follows:

• Payments enabled flexible savings accounts

• Payments enabled deposit accounts

• Payments enabled loan accounts

• Payments enabled mortgage accounts

• e-money accounts

• Credit card accounts

• Charge card accounts

High level changes from v1.1 include:

• Additional resources and related permissions codes:

  • AccountRequests (authorisations for access to the account)

  • Statements (associated information for each statement on the account)

  • Offers (offers available on the account)

  • Party (name and address or logged in user or account owner)

  • ScheduledPayments (single one-off payment scheduled for a future date)

• Restructure of specifications into a sub-page for each resource.

• Added definition regarding optionality.

• Clarification for filtering that if a DateTime is specified in the filtering request with a timezone - the timezone component must be ignored by the ASPSP.

• Extended behaviour of the TransactionFromDateTimeand TransactionToDateTime to the statements resource.

Implementation Timelines

As per the CMA’s Notice of approval of changes to the Agreed Timetable and Project Plan (Retail Banking Market Investigation Order 2017) published on 22 November 2017, the implementation of this standard by ASPSPs will be split as follows:

• Relating to the amended CMA Order: each of the CMA9 to implement the following by end August 2018:

  • the products endpoint to cater for Open Data back-book products (using either one or both of the referential or direct access methods)

  • update of existing Account and Transaction v1.1 endpoints to v2 for PCA and BCA accounts only. 

• Relating to PSD2 scope overall: any ASPSP adopting the OB standard for any PSD2 in-scope payment account products, should implement the relevant endpoints for each of those products in line with RTS timelines (TBC 2019).

Overview

The Read/Write Data API Specification provides a description of the elements that are common across all the Read/Write Data APIs.

This specification should be read in conjunction with the individual Read/Write API Specifications for Payment Initiation, Account & Transaction Information & Confirmation of Funds.

Document Structure

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 begins with an introduction to how the APIs are used.

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

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

Design Principles

RESTful APIs

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 

   

Standards

The OBIE principles for developing API standards:

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

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

ISO 20022

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

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

Extensibility

It is intended that the API flows will be extended to cater for more complex use-cases in subsequent releases - and we have kept this in mind during the design.

Idempotency

Idempotency is difficult to implement consistently and leverage consistently. 

As a result, idempotency is used sparingly in the Open Banking API specifications; with a preference to allow TPPs to simply re-submit a request under failure conditions.

APIs have been defined to be idempotent, where not doing so would cause a poor PSU user-experience or increase false positive risk indicators.

Message Signing

Digital signatures will facilitate non-repudiation for Open Banking APIs. 

However, the solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is described in Basics / Message Signing.

Agnostic to Payment Schemes

The API will be designed so that it is agnostic to the underlying payment scheme that is responsible for carrying out the payment.

As a result, we will not design field lengths and payloads to only match the Faster Payments message, and will instead rely on the field lengths and definitions in ISO 20022. Due diligence has been carried out to ensure that the API has the necessary fields to function with Bacs payments - as per agreed scope.

We will provide further mapping guidance to ensure that differences are understood between the Open Banking Payment API standard, and FPS and Bacs schemes where applicable.

Status Codes

The API uses two status codes that serve two different purposes:

• The HTTP Status Code reflects the outcome of the API call (the HTTP operation on the resource). The Security Working Group has stated that granular error codes may expose threat vectors - so these are limited to the HTTP Status Codes.

• A Status field in some of the resource payloads reflects the status of resources.

Unique Identifiers (Id Fields)

A REST resource should have a unique identifier (e.g. a primary key) that may 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 these specifications do not have a primary key in the system of record, the Id field will be optional for some resources.

An ASPSP that chooses to populate optional ID fields must ensure that the values are unique and immutable.

Definition of Optionality

For endpoints and fields within each resource, the following definitions apply:

• 'Mandatory' endpoints or fields marked must be implemented by the ASPSP.

• 'Conditional' endpoints or fields must be implemented by the ASPSP if these are made available to the PSU in the ASPSP's existing Online Channel (subject to Note 1 below).

• 'Optional' endpoints may be implemented by the ASPSP.

'Online Channel' refers to the superset of the ASPSPs website interface or mobile application (i.e. any information provided to the PSU in either channel).

Notes

1. It is up to each ASPSP to make their own regulatory interpretation, based on eg PSD2, as to which of the ‘Conditional’ endpoints and fields must be implemented.

2. ASPSPs are free to decide whether to implement any of the ‘Optional’ endpoints and fields.

3. ASPSPs must make documentation available to TPPs as to which conditional and optional endpoints and fields are implemented for this specification. The method for providing this documentation will be covered in the implementation guidelines.

Basics

Actors

Character Encoding

The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - Section 8.1)

However, an ASPSP's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "Happy Birthday 🎂🎂!" may not be an acceptable Payment Reference). If the ASPSP rejects the message with a UTF-8 character that cannot be processed, the ASPSP must respond with an HTTP 400 (Bad Request) status code.

Date Formats

All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below:

All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

All dates in the JWT claims are expressed as a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

Resource URI Path Structure

The resources defined by these APIs may be addressed through a path structure consisting of the following parts:

• An optional ASPSP specific path prefix

• The constant string "open-banking"

• The version of the APIs expressed as /v[major-version].[minor-version]/

• The resource name

Examples:

/superbank/open-banking/v2.0/payments

/open-banking/v2.0/account-requests

/apis/open-banking/v2.1/accounts

Headers

Request Headers

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

Response Headers

Return & Error Codes

The following are the HTTP response codes for the different HTTP methods - across all Read/Write API endpoints.