/
Read/Write Data API Specification - v3.1

Read/Write Data API Specification - v3.1


Version Control

VersionDateAuthorComments
3.0 OB R/W API TeamThis 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

  • Additional Supplementary Data section.

Errata:

  • Specification in some places incorrectly specifies that Error Codes in Authorisation flow must be aligned to OAuth Error codes. Now updated to refer to OIDC Error Codes.
  • Description for Content-Type header updated to reflect exception in mandatory application/json value.
  • Typos and grammar fixes.
3.1-draft2 OB R/W API Team

Draft2 Changes:

  • Expanded UK.OBIE.Resource.InvalidConsentStatus error code description to cover Confirmation of Funds for PISP error.
  • Updated example URLs to version 3.1.
3.1-draft3 OB R/W API Team

Draft3 Changes:

  • Namespaced Enumerations are moved to a separate page
    • Removed AdditionalRequestNotPermitted error code.
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

  • Removed text stating "OB Directory will provide and host the necessary certificates containing the corresponding public keys so that the signature may be verified."
  • Added a sub-section on key stores
  • Modified "Process for Signing a Payload"
    • Step 1:
      • changed the step to indicate key can be from any source - not just OB
    • Step 2:
      • correct kid definition to state that this is the key id (not certificate id
      • modified the structure of `iss` to match EIDAS certificate or lodged key structure
      • Added a new claim - http://openbanking.org.uk/tan to identify the trust anchor
      • Modified the crit claim to include the tan claim
  • Modified "Process for Verifying a Signature")
    • Step 2:
      • Changed the description of kid to state that it is used to retrieve a public key from the trust anchor
      • Stated that the `iss` must be verified
      • Added a step to verify http://openbanking.org.uk/tan .

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 RC1OB R/W API Team

RC1 Changes:

  • Added 503 as a status code in Basics / Status Codes. This was previously documented in Release Management document. The description is copied verbatim from that document.
  • In Basics / Message Signing / Process for signing a payload , fixed a typo. "Direcotyr" must read "Directory"
  • Updated Basics / Message Signing / Sample JOSE header to include the new tan claim 
  • Updated examples given in 'Resource URI Path Structure' section to have consistent participant-path-prefix, version and host name.
  • Fixed Resource URI Path Structure, where [resource-id] should follow [resource], changed
    [participant-path-prefix]/open-banking/[version]/[resource-group]/[resource]/[sub-resource]/[resource-id] to
    [participant-path-prefix]/open-banking/[version]/[resource-group]/[resource]/[resource-id]/[sub-resource].
  • Added examples in 'Resource URI Path Structure' section for [resource-id] and [resource-id]/[sub-resource]
3.1OB 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:

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

ActorAbbreviationTypeSpecializesDescription
Payment Service UserPSUPersonN/AA natural or legal person making use of a payment service as a payee, payer or both (PSD2 Article 4(10)).
Payment Service ProviderPSPLegal EntityN/A