Implementation of a new Open Banking Standard

The Open Banking Standard will continue to evolve over time to cater for potential regulatory changes/clarifications, agreed Open Banking roadmap requirements and approved changes (which may include adding new functionality, fixing defects, and errata). Where possible, Open Banking Ltd (OBL) will schedule new versions of the Standard so that all participants can plan ahead and build new APIs to this plan, this will therefore reduce development and support costs for all participants and increase adoption.

Types of release and version numbering

The version numbering above can apply to any individual component of the Standard. For example, the latest published API Specifications at a point in time could be v3.1.1, and the latest published Customer Experience Guidelines (CEG) could be v1.2.0.

Within each, component, individual resources or functionalities can also change version numbers independently. For example, the latest Account and Transaction API Specification can be v3.1.1 and, within this, the /transactions resource can be v3.2.0. In this case, this resource has introduced a minor breaking change. And this may require one or more sections/sub-sections of the CEG to be updated to v1.2.1 or v1.3.0.

The above version numbering approach enables Open Banking Ltd (OBL) to introduce changes to the Standard incrementally but at the same time reducing the need for ASPSPs and TPPs to make any unnecessary changes.

Introducing change

The following apply:

• It is up to ASPSPs to take their own position of which version of each component of the Standard they chose to implement in order to meet both regulatory and commercial requirements.
• As per RTS Article 30(3), ASPSPs must publish technical specification documentation for their dedicated interface, at least six months before 14 September 2019 or at least six months before the target date of the market of the dedicated interface. In practice, this means that ASPSPs should publish details of exactly which version/versions of each component are supported by their dedicated interface.
• As per RTS Article 30(4), ASPSPs must give TPPs at least three months’ notice of any change to the technical specifications. In practice, this means that ASPSPs must give such notice if they are planning to introduce any updates to any component of the Standard, regardless of whether these are major, minor or patch updates. Any change may be implemented in an emergency situation (e.g. in the case where there is a security issue) without such notice, and in such situations, ASPSPs must document emergency situations where changes are implemented and make the documentation available to competent authorities on request.
• As per RTS Article 30(5), ASPSPs must also make available a testing facility at least six months before 14 September 2019 or at least six months before the target date of the market launch of the dedicated interface. As per the Final EBA Guidelines (Consultation Feedback Ref 119), ASPSPs should ensure that any changes are made available in the testing facility as soon as possible to allow TPPs to test against the updated technical specifications, in the context of compliance with Article 30(5). In practice, this means that ASPSPs should consider the impact of proposed changes on their testing facility in order to ensure that the testing facility enables the same functionality as the dedicated interface, in the context of such changes. As such, ASPSPs should endeavour to make any changes to the testing facility available to TPPs at least three months before changes are implemented to ensure TPPs, can continue to effectively test.
• ASPSPs should maintain multiple live/active versions of each interface (e.g. one for each supported release).
• Where an ASPSP chooses to implement a new version of any component of the Standard they should implement each new major version within six months, and each new minor version within three months of the Standard being published by Open Banking Ltd (OBL).

Together with the requirements for ASPSPs to notify TPPs of any changes (see section 5.5) any TPP will, except in an emergency, always have at least three months’ notice before being required to update their systems. 

Considerations

Dual running and deprecation

ASPSPs should support a minimum of two API versions in a production context, providing both versions were previously supported by the ASPSP, for a period of time long enough to ensure that TPPs have had sufficient time to successfully test the new version and migrate their applications and customers. Where an ASPSP is using Open Banking Ltd (OBL)’s Managed Rollout process, Open Banking Ltd (OBL) will be able to confirm when sufficient TPPs have migrated from the previous version to enable the ASPSP to reasonably demonstrate ‘wide usage’ of this new version. For all other ASPSPs, Open Banking Ltd (OBL) recommends dual running for at least six months for a major version, and three months for a minor version. Where an ASPSP implements an API for the first time, they will only need to support this one version to start with.

The ability to support two API versions allows TPPs to maintain existing integrations with the older version, and benefit from features and enhancements offered by the new version. Over time, TPPs will migrate all their applications to consume the new API version. Once migrated, TPPs should not access resources via the old API version (including creating, reading, updating or deleting).

Dual running of APIs requires a pragmatic approach to ensure that ASPSPs expose and support both API versions and to ensure that TPPs use these to migrate applications as intended, without unnecessary conflict.

The deprecation of unsupported versions is at the ASPSP’s discretion – based on usage metrics. However, the Open Banking Ltd (OBL) may recommend that any specified version (major, minor, or patch) should be deprecated at any time, and this should be implemented within three months of notification by the Open Banking Ltd (OBL). This is to cater for critical defects, especially those relating to security. In exceptional circumstances it may be agreed by Open Banking Ltd (OBL) that support for a specified version is terminated earlier.

ASPSPs must not apply any measures to induce TPPs to adopt a new version of the APIs (e.g. rate limiting the older version while providing better performance on a newer version).

API credentials, consent and authorisation

API Credentials associated to an API should be version agnostic. Therefore, a TPP accessing v1.0, v1.1 or v2.0 should be able to use the same API Credentials across all available API endpoints.

It in the domain of the TPPs to manage PSUs consent and ASPSPs to manage PSU authentication in compliance with relevant regulations.

If there is a non-breaking change (e.g. an additional field is added to a permission/cluster) then this should be managed between the TPP and PSU and between the ASPSP and PSU respectively. Any long lived access or refresh tokens could then remain unaffected.

In the event of a breaking change (e.g. where a permission/cluster is added, removed or changed), then the PSU may be required to re-consent with the TPP and to re-authenticate with the ASPSP.

Backward and Forward Compatibility

The Open Banking Ltd (OBL) specifications will include details on which operations or resources are expected to be backward and forward-compatible across versions. It is expected that:

• A long-lived consent (e.g. for access to AISP resources) created using an older version of the APIs can be used for read operations in newer versions of the API.
• A short-lived consent (e.g. for a short lived payment initiation request) can only be used within the same version of the API for creating resources.

If an ASPSP is planning to release a new API version that does not follow the expectations above (e.g. does not support forward compatibility for AISP resources) this should be communicated to TPPs (e.g. via the Open Banking Ltd (OBL)’s ASPSP Calendar).

Breaking changes

New releases of the Open Banking Standard may introduce breaking changes when new functionality or fixes are introduced. This may include changes to the payload schema or the data contained within.

When implementing a new version, in-line with the guidance on Dual Running, ASPSPs should accept only new payload schemas for new consents and API calls.

Existing AISP and CBPII long-lived consents have no impact, if consent is given in an older version and the AISP is accessing the information using a latest version and should follow guidance as mentioned under section Backward and Forward compatibility above.

Existing PISP long-lived consents, e.g. sVRP (Sweeping) and cVRP (commercial) that are given on an older version are not forward compatible and are required to be migrated to a new version as and when a new version is being implemented and there are breaking changes introduced in the VRP consent without requiring the PSU to re-consent as it is a pure technical migration which is majorly payload and data structure changes. 

If the ASPSPs and TPPs do not move on a single version then the ASPSP has to support multiple versions of the Standards to enable the PISP to make payment from the same old version that the consent was given.  And hence the migration strategy to migrate all the consents from an older version on to a latest version of the Standards that the ASPSP is supporting. This does not mean that any of the data values in the existing consent provided by the PSU are changing.

Payload value matching and validation should be done at the data value level, as including payload schemas in validation routines may introduce additional challenges if existing fields are updated or new fields are introduced. The condition of making sure that the payment initiation is from the payment instruction setup by the VRP consent still applies.

Migration strategies

Changes to payload schemas where the enumerations might have changed from ISO full code name to code value and require additional steps to migrate existing consents to a new format. Approaches to migration will vary based on each ASPSP’s implementation and OBL will provide additional guidance and appropriate technical options within the Standard where a new release contains such changes.

TPPs should validate with individual ASPSPs of what migration strategy they support.