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:

This specification should be read in conjunction with the Customer Experience Guidelines and Management Information Requirements. Together these form the OBIE standard, which should enable any ASPSP which implements the specification to meet their obligations under both the CMA Order and PSD2/RTS. 

The key difference between the CMA Order and PSD2/RTS requirements relate to which product types are implemented, and the timing for implementation. For example, the CMA Order requires the CMA9 to implement the standard for PCA and BCA accounts earlier (in some cases) than the PSD2/RTS timelines. The timings are defined in the Open Banking Roadmap (https://www.openbanking.org.uk/wp-content/uploads/Open-Banking-Revised-Roadmap-July-2018.pdf).

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.

This document and its sub-pages must be read in conjunction with the Known Issues.

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/ 

   

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.

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

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

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

The approach for message signing is documented in Basics / Message Signing.

The applicability of signatures to individual requests and responses is documented on the page for each of the resources.

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

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). Granular Functional Error Codes are specified as part of API Error Response Structure, after consultation with Security and Fraud Working Group.

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

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.

Where a requirement is being implemented by either an ASPSP and/or a TPP, a different categorisation is applied. The functionality, endpoints and fields within each resource are categorised as 'Mandatory', 'Conditional' or 'Optional'.

ASPSPs must make documentation available to TPPs (e.g. on their developer portals) to which 'Conditional' / 'Optional' endpoints and fields are implemented for any given implementation of the specification.

Functionality, endpoints and fields marked as Mandatory are required in all cases for regulatory compliance and/or for the API to function and deliver essential customer outcomes.

For functionalities and endpoints: 

• An ASPSP must implement an endpoint that is marked Mandatory.

• An ASPSP must implement functionality that is marked Mandatory.

For fields:

• A TPP must specify the value of a Mandatory field.

• An ASPSP must process a Mandatory field when provided by the TPP in an API request.

• An ASPSP must include meaningful values for Mandatory fields in an API response.

Functionality, endpoints and fields marked as Conditional may be required in some cases for regulatory compliance (for example, if these are made available to the PSU in the ASPSP's existing Online Channel, or if ASPSPs (or a subset of ASPSPs) have been mandated by a regulatory requirement).

For functionalities and endpoints:

• An ASPSP must implement functionality and endpoints marked as Conditional if these are required for regulatory compliance.

For fields:

• All fields that are not marked as Mandatory are Conditional.

• A TPP may specify the value of a Conditional field.

• An ASPSP must process a Conditional field when provided by the TPP in an API request, and must respond with an error if it cannot support a particular value of a Conditional field.

• An ASPSP must include meaningful values for Conditional fields in an API response if these are required for regulatory compliance.

Functionality and endpoints marked as Optional are not necessarily required for regulatory compliance but may be implemented to enable desired customer outcomes.

For functionalities and endpoints:

• An ASPSP may implement an Optional endpoint.

• An ASPSP may implement Optional functionality.

For fields:

• There are no Optional fields.

• For any endpoints which are implemented by an ASPSP, the fields are either Mandatory or Conditional.

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.

An ASPSP must accept all valid ISO-8601 date formats including its permitted variations (e.g. variations in how the timezone is defined, dates with or with a seconds or milliseconds part etc.) in the requests.

All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. For Example:

All dates in the query string are represented in ISO 8601 date-time format and must not include the timezone. For example:

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 GMT until the date/time.

The path of the URI must follow the structure below (from the OB API Release Management document).

• [participant-path-prefix]/open-banking/[version]/[resource-group]/[resource]/[resource-id]/[sub-resource]

This consists of the following elements:

• [participant-path-prefix]
  An optional ASPSP specific path prefix.

• open-banking
  The constant string "open-banking".

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

• [resource-group]
  The resource-group identifies the group of endpoints, according to the PSD2 role used to access the API (as "aisp", "pisp" or "cbpii").

• [resource]/[resource-id]
  Details the resource.

• [sub-resource]
  Details the sub-resource.

An ASPSP must use the same participant-path-prefix and host name for all its resources.

Examples:

https://superbank.com/apis/open-banking/v3.1/pisp/domestic-payments
https://superbank.com/apis/open-banking/v3.1/aisp/account-access-consents
https://superbank.com/apis/open-banking/v3.1/aisp/accounts
https://superbank.com/apis/open-banking/v3.1/aisp/accounts/1234
https://superbank.com/apis/open-banking/v3.1/aisp/accounts/1234/transactions
https://superbank.com/apis/open-banking/v3.1/cbpii/funds-confirmation-consents

For brevity, the APIs are referred to by their resource names in these documents and in all examples.