The Berlin Group openFinance API Framework
Foundational course

Module 1: Architectural and Security Foundations

A robust understanding of the openFinance API Framework begins with its architectural principles and security model. These foundational elements are consistent across all services and are essential for building secure and interoperable solutions.

Guiding Principles: A RESTful, Resource-Oriented, and ISO 20022-Based Architecture

The framework is intentionally designed using modern, widely accepted industry standards to ensure ease of use, interoperability, and future-readiness.

RESTful APIs: The specifications define a set of RESTful APIs. This architectural style uses the standard methods of the Hypertext Transfer Protocol (HTTP/1.1 or higher) for communication and relies on JavaScript Object Notation (JSON) as its primary data format. This approach is familiar to the vast majority of software developers and aligns with modern web service design.

Resource-Oriented Approach: The API is designed around the concept of "resources." Financial concepts like payments, accounts, and consents are modelled as distinct resources, each with a unique identifier (URI) and a defined lifecycle. TPPs interact with these resources using standard HTTP verbs: POST to create a new resource (e.g., initiate a payment), GET to retrieve its state, PUT to update it, and DELETE to remove it. This resource-oriented design provides a logical and consistent structure for all interactions.

ISO 20022 Alignment: To ensure that all participants in the ecosystem have a common understanding of the data being exchanged, the framework's data model is based on the ISO 20022 dictionary. ISO 20022 is the global standard for financial messaging, providing a common semantic language for data elements. This alignment is critical for achieving true interoperability and simplifies the process for banks to map API data fields to their internal core systems.

Key Roles and Terminology

The framework documentation uses precise terminology to define the actors in the ecosystem:

• ASPSP (Account Servicing Payment Service Provider): This is the financial institution that provides and maintains a payment account for a PSU. In the context of open finance, this role expands to include institutions holding other financial products such as loans or investments.
• TPP (Third Party Provider): A TPP is an entity licensed under PSD2 to provide payment services. The main roles are Payment Initiation Service Provider (PISP), Account Information Service Provider (AISP), and Payment Instrument Issuing Service Provider (PIISP).
• PSU (Payment Service User): The PSU is the end customer, who can be a natural person (consumer) or a legal entity (corporate). The PSU owns the account and is the only party that can grant consent for a TPP to access their data or initiate payments on their behalf.
• Access Clients: The openFinance framework introduces the broader term "Access Client" to encompass not only regulated TPPs but also other entities, such as corporate customers who may use the APIs to access their own account data directly for treasury management purposes.

The Security Framework: A Multi-Layered Approach

Security is the paramount concern in open finance, and the Berlin Group framework implements a multi-layered, defense-in-depth security model mandated by the EBA RTS.

Transport Layer Security: All communication between the TPP and the ASPSP must be secured using Transport Layer Security (TLS) version 1.2 or higher. A critical requirement is the use of mutual TLS (mTLS), where both the client and the server must present a valid certificate to authenticate each other before a secure channel is established. This prevents man-in-the-middle attacks and ensures both parties are who they claim to be.

eIDAS Certificates: The foundation of trust and identity within the European financial ecosystem is the eIDAS regulation. TPPs are required to identify themselves using qualified certificates issued in accordance with this regulation. Specifically, they must use:

• Qualified Website Authentication Certificates (QWACs) for identification at the transport layer during the mTLS handshake.
• Qualified Electronic Seal Certificates (QSeals) for signing messages at the application layer to ensure data integrity and non-repudiation.

Application-Level Message Signing: As an additional security measure, the framework specifies a mechanism for the TPP to digitally sign parts of the HTTP request, typically the headers. This is done using JSON Web Signature (JWS) as defined in [RFC7515] (JSON Web Signature) and [ETSI TS 119 182-1] (JAdES profile of ETSI). This signature provides the ASPSP with cryptographic proof that the request has not been tampered with in transit and that it originated from the TPP holding the corresponding qualified certificate.

The framework's flexibility in supporting different Strong Customer Authentication (SCA) models was a pragmatic and crucial design choice that greatly contributed to its widespread adoption. Financial institutions across Europe had already invested heavily in their own unique and secure online authentication systems long before PSD2 was enacted. Mandating a single, rigid SCA method would have created a significant technical and financial barrier, likely leading to implementation delays and resistance. The Redirect SCA model, in particular, offered a path of least resistance. It cleverly allows an ASPSP to continue using its existing, trusted, and compliant authentication infrastructure. The TPP simply redirects the PSU to the ASPSP's familiar and secure environment, where the ASPSP handles the entire authentication process. The TPP never needs to handle the PSU's sensitive credentials. This approach dramatically lowered the implementation burden for ASPSPs, accelerating their ability to comply with PSD2 and contributing to the NextGenPSD2 framework becoming a European standard. It was a design that prioritised interoperability at the data exchange level while accommodating necessary diversity at the user authentication level.

Deep Dive: Strong Customer Authentication (SCA) Flows

PSD2 mandates the use of SCA for sensitive operations such as accessing account data or initiating a payment. The Berlin Group framework provides several standardised flows to accommodate the diverse authentication methods used by ASPSPs across Europe.

• Redirect SCA: This is the most widely implemented and flexible model. The PSU initiates an action in the TPP's application, and their browser is then redirected to the ASPSP's own secure online portal (website or mobile application). The PSU authenticates directly with their bank using their familiar credentials and methods. Once authentication is complete, the PSU is redirected back to the TPP's application with an authorisation code. This model is highly secure as the TPP never handles the PSU's credentials.
• Decoupled SCA: In this flow, the authentication takes place on a different device from the one where the PSU is using the TPP's service. For example, the PSU might start a payment on a desktop computer, which triggers a push notification to their registered banking app on their smartphone. The PSU approves the action in the mobile app. Meanwhile, the TPP's application on the desktop polls the ASPSP's API in the background to check for the status of the authentication process.
• Embedded SCA: This approach allows the SCA process to be conducted entirely within the TPP's user interface. The TPP collects the authentication data (e.g., a password and a one-time code) from the PSU and forwards it to the ASPSP via the API. This model is less common as it requires the ASPSP to expose more details about its specific SCA methods and places a greater security burden on the TPP.