Read/Write Data API Specification - v3.1
Version Control
Version | Date | Author | Comments |
---|---|---|---|
3.0 | OB R/W API Team | This is the baseline version. No change from RC3. | |
3.1-draft-1 | OB R/W API Team | This is the initial draft version for 3.1 Draft 1 Changes
Errata:
| |
3.1-draft2 | OB R/W API Team | Draft2 Changes:
| |
3.1-draft3 | OB R/W API Team | Draft3 Changes:
| |
3.1-draft4 | OB R/W API Team | Draft4 Changes: Modified the description for Basics / Message Signing to cater for EIDAS certificates and a move away from OB Issued Certificates
Modified Basics / Resource URI Path Structure to clarify that all APIs must have the same base. Removed FAPI reference in Basics / Headers Change CIBA target date in Security & Access Control / CIBA | |
3.1 RC1 | OB R/W API Team | RC1 Changes:
| |
3.1 | OB R/W API Team | Version 3.1 final release. No changes from Version 3.1 RC1. |
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:
- Account and Transaction API Specification - v3.1
- Payment Initiation API Specification - v3.1
- Confirmation of Funds API Specification - v3.1
- Event Notification API Specification - v3.1
- Namespaced Enumerations - v3.1
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).
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.
Known Issues
This document and its sub-pages must be read in conjunction with the Known Issues.
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/
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.
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.
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 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.
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). 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.
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.
Categorisation of Implementation Requirements
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.
Mandatory
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.
Conditional
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.
Optional
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.
Basics
Actors
Actor | Abbreviation | Type | Specializes | Description |
---|---|---|---|---|
Payment Service User | PSU | Person | N/A | A natural or legal person making use of a payment service as a payee, payer or both (PSD2 Article 4(10)). |
Payment Service Provider | PSP | Legal Entity | N/A |