XS2A Adapter

1. Introduction and Goals

The main idea of the XS2A Adapter project is to have one unified interface for PSD2 directive which based on the Berlin Group Specification that covers the vast majority of banks that implemented the Berlin Group Specification on their own.

1.1. Requirements Overview

XS2A Adapter helps TPPs save time on connecting banks to their systems. XS2A Adapter suggests them to use one unified interface that fully compliant with Berlin Group Specification. All differences of implementation hidden inside a specified bank adapter.

Main features

Connect plenty of banks
Organize contributors community from the world
Simplify the connection process of the bank that compliant with the Berlin Group Specification
Support Account Information and Payment initiation services

1.2. Quality Goals

Table 1. Quality Goals
Nr.	Quality	Motivation
1	Understandability	The API should be clear enough for new clients to use XS2A Adapter, from the other hand the architecture should be not too complicated for contributors.
2	Interoperability	The application should provide a unified API that allows access to all covered banks.
3	Testability	The architecture should allow easy testing of all main building blocks.

1.3. Stakeholders

Table 2. Stakeholders
Name	Role	Contact
Denys Golubiev	Software Architect PSD2	dgo@adorsys.de
Francis Pouatcha	Software Architect PSD2, Sales	fpo@adorsys.de

2. Architecture Constraints

The few constraints on this project are reflected in the final solution. This section shows them and if applicable, their motivation.

2.1. Technical Constraints

Table 3. List of Technical Constraints
	Constraint	Background and / or motivation
Software and programming constraints
TC1	Implementation in Java	The application should support Java 8
TC2	Deployment	The application should have a possibility to be used as a library and a standalone application at the same time
TC3	Distribution	Library should be available as jar file on the maven central and as a docker image on the dockerHub

2.2. Organizational Constraints

Table 4. List of Organizational Constraints
	Constraint	Background and / or motivation
OC1	Team	Serhii Petrychenko, Snisarenko Artem, Oleksandr Berezkin
OC2	Time schedule	Release planned each month
OC3	IDE independent project setup	No need to continue the editor and IDE wars. The project must be compilable on the command line via standard build tools.
OC4	Configuration and version control	Public git repository with a complete commit history and a public master branch pushed to GitHub.
OC5	Testing	Use JUnit to prove functional correctness and integration tests and JaCoCo to ensure a high test coverage (at least 80%). Postman tests for covering end-to-end flows.
OC6	Published under an Open Source license	The source, including documentation, should be published as Open Source under the Apache 2 License.

2.3. Conventions

Table 5. List of Conventions
	Conventions	Background and / or motivation
C1	Architecture documentation	Structure based on the english arc42-Template in version 7.0
C2	Language	English. The project targets an international audience, so English should be used throughout the whole project.

3. System Scope and Context

This chapter describes the environment and context of XS2A Adapter: Who uses the system and on which other system does XS2A Adapter depend.

3.1. Business Context

TPP

A TPP wants to make AIS and PIS requests to different banks via XS2A Adapter.

ASPSPs

XS2A Adapter transforms request from TPP to a specific ASPSP request and sends it then transforms the response from ASPSP to a unified XS2A Adapter API response.

3.2. Technical Context

4. Solution Strategy

Implement XS2A Adapter in Java language with minimal external dependencies.
We use Maven automation build tool, so it can be used within automated builds
We have additional module that wraps XS2A Adapter into Spring Boot application and with the possibility to build a docker image

5. Building Block View

5.1. Whitebox XS2A Adapter Library

Table 6. Contained Building Blocks
Building block	Description
service-api	Payment initiation, account information, http client and validation interfaces
service-impl	Basic implementation of payment initiation and account information, implementation of http client
service-loader	Load payment initiation or account information service implementation for specific adapter
aspsp-registry	Registry of supported banks. Each record contains bank details and reference to the adapter
adapters	Collection of bank adapters supported by XS2A Adapter

5.1.1. Whitebox XS2A Adapter Standalone

Table 7. Contained Building Blocks
Building block	Description
service-api	Payment initiation, account information, http client and validation interfaces
service-impl	Basic implementation of payment initiation and account information, implementation of http client
service-loader	Load payment initiation or account information service implementation for specific adapter
aspsp-registry	Registry of supported banks. Each record contains bank details and reference to the adapter
adapters	Collection of bank adapters supported by XS2A Adapter
rest-api	ASPSP Registry REST API, OAuth REST API
rest2api-mapper	Mappers between rest and service layers
generated-rest-api	Generated REST API from Berlin Group yml specification
rest-impl	Implementation of REST API

5.1.2. ASPSP Registry (Blackbox)

Intent/Responsibility: ASPSP Registry provides API for searching supported banks. The list of supported banks stored in the CSV file.

Table 8. Interfaces
Interface (From-To)	Description
service-api → ASPSP search	Search ASPSP in the registry

Details are described in the Whitebox ASPSP Registry.

5.1.3. Service-loader (Blackbox)

Intent/Responsibility: Service-Loader looks up for specific service implementation of concrete bank adapter.

Table 9. Interfaces
Interface (From-To)	Description
service-loader → bank adapters	Loads service implementations from supported bank adapters
rest-impl → service-loader	Uses service-loader classes

Details are described in the Service-loader Whitebox.

5.1.4. Bank adapters (Blackbox)

Intent/Responsibility: Contains PIS & AIS service implementations for supported banks

Table 10. Interfaces
Interface (From-To)	Description
service-loader → bank adapters	Loads service implementations from supported bank adapters
bank adapters → banks	Makes HTTP requests to the banks

Details are described in the Bank adapters Whitebox.

5.2. Building Blocks - Level 2

5.2.1. Whitebox ASPSP Registry

Table 11. Contained Building Blocks
Building Block	Description
Service	Implementation of Search API. Contains methods for searching ASPSP by criteria
Lucene	The list of ASPSPs from CSV file loads into Lucene to speed up the search procedure

5.2.2. Whitebox Service-loader

Table 12. Contained Building Blocks
Building Block	Description
AIS	Load implementation of AIS from requested ASPSP
PIS	Load implementation of PIS from requested ASPSP

5.2.3. Whitebox Bank Adapters

Table 13. Contained Building Blocks
Building Block	Description
AIS	AIS implementation of exact ASPSP
PIS	PIS implementation of exact ASPSP
HTTP client	Uses for sending requests to the ASPSP

5.3. Level 3

5.3.1. Account Information Service (AIS) Interface (Blackbox).

Intent/Responsibility: Performs request/response normalisation and calls a bank AIS endpoint.

Table 14. AIS Interface
Method	Description
createConsent	This method creates a consent resource, defining access rights to dedicated accounts of a given PSU-ID.
getConsentInformation	Returns the content of an account information consent object.
deleteConsent	The TPP can delete an account information consent object if needed.
getConsentStatus	Reads the status of an account information consent resource.
getConsentAuthorisation	Returns a list of all authorisation sub-resources IDs which have been created.
startConsentAuthorisation	Creates an authorisation sub-resource and start the authorisation process of a consent. The message might in addition transmit authentication and authorisation related data.
updateConsentsPsuData	This method updates PSU data on the consents resource if needed. It may authorise a consent within the Embedded SCA Approach where needed.
getAccountList	Reads the identifiers of the available payment account together with booking balance information, depending on the consent granted.
readAccountDetails	Reads details about an account, with balances where required.
getTransactionList	Reads transaction reports or transaction lists of a given account addressed by "account-id", depending on the steering parameter "bookingStatus" together with balances.
getTransactionDetails	Reads transaction details from a given transaction addressed by "transactionId" on a given account addressed by "account-id".
getTransactionListAsString	The same as getTransactionDetails but returns mere String object.
getConsentScaStatus	This method returns the SCA status of a consent initiation’s authorisation sub-resource.
getBalances	Reads account data from a given account addressed by "account-id".
getCardAccountList	Reads a list of card accounts with additional information, e.g. balance information.
getCardAccountDetails	Reads details about a card account.
getCardAccountBalances	Reads balance data from a given card account addressed by "account-id".
getCardAccountTransactionList	Reads account data from a given card account addressed by "account-id".

5.3.2. Payment Initiation Service (PIS) Interface (Blackbox).

Intent/Responsibility: Performs request/response normalisation and calls a bank PIS endpoint.

Table 15. PIS Interface
Method	Description
initiatePayment	This method is used to initiate a payment at the ASPSP.
getSinglePaymentInformation	Returns the content of a payment object of a single payment initiation request.
getPeriodicPaymentInformation	Returns the content of a payment object of a periodic payment initiation request.
getPeriodicPain001PaymentInformation	Returns the content of a payment object of an XML format periodic payment initiation request.
getPaymentInformationAsString	Returns the content of a payment object as a mere string.
getPaymentInitiationScaStatus	This method returns the SCA status of a payment initiation’s authorisation sub-resource.
getPaymentInitiationStatus	Check the transaction status of a payment initiation.
getPaymentInitiationStatusAsString	The same as getPaymentInitiationStatus but returns mere String object.
getPaymentInitiationAuthorisation	Read a list of all authorisation subresources IDs which have been created.
startPaymentAuthorisation	Create an authorisation sub-resource and start the authorisation process. The message might in addition transmit authentication and authorisation related data.
updatePaymentPsuData	This methods updates PSU data on the authorisation resource if needed. It may authorise a payment within the Embedded SCA Approach where needed.

Non-XS2A Interfaces.

XS2A Adapter handles specific cases that are not specified or scarcely described in the PSD2 Berlin Group Specification.

OAuth2 Service.

Intent/Responsibility: This is API for supporting OAuth flow.

Table 16. OAuth2 Service Interface (with REST endpoints)
Method	Description
getAuthorizationRequestUri GET /oauth2/authorization-request-uri	Retrieves an authorization URL from a bank IDP Server and supplies necessary parameters for completing PSU authorization.
getToken POST /oauth2/token	Exchanges an authorization code for a bearer token.

Embedded Pre-Authorisation Service.

Intent/Responsibility: This is API for supporting embedded pre-authorisation flow.

This is a Crealogix specific solution which is used by DKB bank.

Table 17. Embedded Pre-Authorisation Service Interface (with REST endpoints)
Method	Description
getToken POST /v1/embedded-pre-auth/token	Exchanges user credentials for a bearer token.

XS2A Adapter Specific Interfaces.

For Adapter to address a request to a specific bank a bank adapter identifier is a must. To tackle the problem ASPSP Repository was introduced. It traverses through the Lucene Repository that persists all available bank (ASPSP) records.

ASPSP Read Only Repository Service.

Intent/Responsibility: Lookup for an appropriate adapter by incoming parameters.

Table 18. ASPSP Read Only Repository Interface (Library)
Method	Description
findById	Retrieves an ASPSP by provided ID.
findByBic	Retrieves all ASPSPs by provided BIC.
findByBankCode	Retrieves all ASPSPs by provided BLZ (Bank Code).
findByName	Retrieves all ASPSPs by provided Bank Name.
findAll	Retrieves all ASPSPs from the Repository.
findLike	Retrieves all ASPSPs by provided set of data (e.g. BIC and Bank Name).
findByIban	Retrieves an ASPSP by provided IBAN.

The REST Client of the ASPSP Repository is also available, however its interface is simplified.

Table 19. ASPSP Repository REST Interface (Standalone)
Method	Description
GET /v1/aspsp	Finds all ASPSPs by one of the next parameters BIC, BLZ (bank code), IBAN or Bank Name or by a set of listed parameters.
GET /v1/aspsp/{aspsp-id}	Finds an ASPSP by ID.

Additional details on the ASPSP Repository can be found here

6. Runtime View

6.1. Send request to ASPSP

TPP sends request to ASPSP via XS2A Adapter.

Sequence diagram: Interaction with Adapter

Scenario:

TPP makes call to ASPSP Registry to get the ID of supported bank adapter
ASPSP Registry returns the list of supported adapters. The result list is empty when searched bank is unsupported.
TPP chooses and stores the ASPSP ID
TPP makes call to a bank via XS2A Adapter with ASPSP ID in the request headers
XS2A Core gets bank adapter details from ASPSP Registry
ASPSP Registry returns bank adapter details
XS2A Core sends initial TPP request to the specific bank adapter
ASPSP Adapter converts request regarding bank needs
ASPSP Adapter sends converted request to the bank
ASPSP Adapter receives response from the bank
ASPSP Adapter converts bank response to the XS2A Adapter model
ASPSP Adapter sends converts response to XS2A Core
XS2A Core replies with the converted response to TPP

6.2 SCA OAuth2 Approach

6.2.1 Integrated

Integrated OAuth based authentication process in AIS context

6.2.2 Pre-step

OAuth based pre-step authentication process in AIS context

6.2.3 OAuth2 Consent

6.2.4 Embedded Pre-step

7. Deployment View

7.1. XS2A Adapter as a library

Table 20. Nodes description
Node/Artifact	Description
maven central repository	Global public cloud repository. All XS2A Adapter libraries are uploaded there
xs2a-adapter deployment	Deployment environment
release action	GitHub Action deploys artifacts to maven central and documentation to github pages
bank adapters	Set of bank adapters that could be used by client

7.2. XS2A Adapter as a standalone application

XS2A Adapter deployment (as a standalone app)

Table 21. Nodes description
Node/Artifact	Description
xs2a-adapter deployment	Container cluster management system
container registry	Container registry e.g. DokerHub, GitLab, etc
radapter user computer	User builds and publishes docker image to the registry

8. Cross-cutting Concepts.

8.1. XS2A Adapter Domain Model.

The main goal of the XS2A Adapter is to normalize a request/response to/from a bank to be compliant to the Berlin Group PSD2 specification.

8.1.1. XS2A Request/Response flow overview.

Request/response processing are mostly done in the specific adapter, but a request/response is passed through several layers until it reaches an adapter.

Table 22. XS2A Adapter Activity
Module	Description
TPP	Third Party Payment Service Provider, a client of the XS2A Adapter.
Adapter REST Interface	Receives requests and sends responses from/to a client, delegates a request to the ASPSP Registry or to the Adapter Service Loader.
Adapter ASPSP Registry	Retrieves an ASPSP information from a Lucene repository by a provided input.
Adapter Service Loader	Loads an appropriate XS2A Adapter and delegates a request to it.
Adapters	Collection of implemented bank adapters.
Adapter Service Implementation	Module with base service implementations to deal with a request.
X Adapter	A specific XS2A Adapter that performs the request/response normalization and calls an appropriate bank.
ASPSP	Account Servicing Payment Service Provider or simply the Bank

There is no main Request or Response models in XS2A Adapter. Almost each operation has its own request/response structure, these are models based on the Berlin Group specification. Full list and descriptions are available in the swagger file.

8.1.2. XS2A Adapter REST Interface.

Table 23. XS2A Adapter REST Interface
Class/Interface	Description
ConsentApi	Operations for creating. deleting, reading and authorising a consent.
AccountApi	Operations for retrieving account data, like balances, transactions, transaction details, etc.
ConsentController	Implements ConsentApi and AccountApi and delegates request processing to the Account Information Service.
Oauth2Api	Operations for constructing Authorizing URL and obtaining an Access Token.
OAuth2Controller	Implements Oauth2Api and delegates a request to the OAuth2 Service.
PaymentApi	Operations for the payment initiation, authorisation, and reading a payment information.
AspspSearchApi	Operations for retrieving an ASPSP information.
AspspSearchController	Implements AspspSearchApi and delegates a request to the Aspsp Search Service.
EmbeddedPreAuthorisationApi	Operation for retrieving an Access Token.
EmbeddedPreAuthorisationController	Implements EmbeddedPreAuthorisationApi and delegates a request to the Pre-Authorisation Service.

The full description of the XS2A Adapter REST API can be found on the Swagger page.

Berlin Group Specification provides comprehensive documentation on the PSD2 XS2A Interface.

8.1.3. XS2A Adapter ASPSP Registry.

Adapter ASPSP Registry is sufficiently described in Whitebox ASPSP Registry

8.1.4. XS2A Adapter Service Loader.

Adapter Service Loader responsibility is to provide an appropriate XS2A Adapter to deal with a request/response routine. The structure is the next:

Table 24. XS2A Adapter Service Loader
Class/Interface	Description
AdapterServiceLoader	The class resolves which particular adapter should be called.
AccountInformationServiceImpl	The class calls Service Loader to get a particular adapter then passes the request to the specific Account Information service.
PaymentInitiationServiceImpl	The class calls Service Loader to get a particular adapter then passes the request to the specific Payment Initiation service.
AccountInformationService	The interface determines operations for retrieving account information, consent creation, PSU authentication and authorisation. Based on PSD2 Berlin Group specification.
PaymentInitiationService	The interface determines operations for payment initiation, PSU authentication and authorisation. Based on PSD2 Berlin Group specification.

8.1.5. XS2A Adapter Service Implementation.

All base service implementations are located in the Adapter Service Implementation module:

Table 25. XS2A Adapter Service Implementation
Class/Interface	Description
BaseAccountInformationService	The class provides the base request/response normalization for account information retrieval and calls a real bank.
RequestBuilderImpl	The class encapsulates all request related data like body, headers, query parameters, etc.
BasePaymentInitiationService	The class provides the base request/response normalization for payment initiation and calls a real bank.
AbstractAdapterServiceProvider	The abstract class encapsulates common for all service providers operations.
AccountInformationService	The interface determines operations for retrieving account information, consent creation, PSU authentication and authorisation. Based on PSD2 Berlin Group specification.
Builder	The interface determines operations for assembling request data.
Request	Marker interface, encapsulates Builder interface.
Response	Wrapper for a bank response. Contains a body, headers and HTTP status code.
PaymentInitiationService	The interface determines the operations for payment initiation, PSU authentication and authorisation. Based on PSD2 Berlin Group specification.
AccountInformationServiceProvider	The interface determines operations for account information service provider.
PaymentInitiationServiceProvider	The interface determines operations for payment initiation service provider.
AdapterServiceProvider	The interface determines common operations for any service provider.

The full list of the AIS operations is put down here and PIS operations are here

8.1.6. X-Adapter.

Normalization of a request/response takes place in a particular X-Adapter:

Table 26. X Adapter
Class/Interface	Description
XAdapterServiceProvider	Child of a AbstractAdapterServiceProvider with a specific bank implementations.
XAccountInformationService	Child of a BaseAccountInformationService with a specific bank implementations.
XPaymentInitiationService	Child of a BasePaymentInitiationService with a specific bank implementations.

8.2. Inheritance of the base services.

Creating an adapter is achieved via extending base services: AIS, PIS, OAuth2, etc.

A concrete adapter is merely simple as all main operations are performed in the base Account Information and Payment Initiation services. Also, not all adapters need to extend a base service to add a specific change, a bank can have a perfectly valid BG interface, so a base service is enough for connecting to an ASPSP.

However, all adapters must extend AbstractAdapterServiceProvider that implements AccountInformationServiceProvider and PaymentInitiationServiceProvider for proper Service Loader work.

There are additional constrains on an adapter which listed here.

8.3. Http Client and Request/Response Interceptor.

XS2A Adapter provides its own HTTP Client implementations: ApacheHttpClient, WiremockHttpClient.

Table 27. XS2A Adapter HttpClient
Class/Interface	Description
HttpClient	Interface provides the list of operations for a client.
ResponseHandler	Functional Interface for operation of handling a bank response.
AbstractHttpClient	Abstract class provides base implementation or Get, Post, Put, and Delete operations.
ApacheHttpClient	Main implementation of the HttpClient that uses the Apache Components solution.
WiremockHttpClient	A client on top of the ApacheHttpClient, that palms off a recorded bank response instead of communicating to a real bank.

More details on WireMock will come below.

To be able to modify a specific aspect of a request an Interceptor interface was introduced. With an interceptor a client can pre- or post-handle a call to a bank.

Table 28. XS2A Adapter Interceptor
Class/Interface	Description
Interceptor	Interface provides the list of operations with default postHandle() implementation.
adorsys.AdorsysSigningHeadersInterceptor	Signs a request to banks that use the Adorsys solutions.
adorsys.OauthHeaderInterceptor	Adds a specified OAuth header to a request to banks that uses the Adorsys solutions.
consors.PsuIdHeaderInterceptor	Clears PSU-ID header if it contains mere quotes ("") for Consors.
deutschebank.PsuIdHeaderInterceptor	Normalize PSU-ID header if necessary for a specific Deutsche Bank branches.
deutschebank.PsuIdTypeHeaderInterceptor	Adds a defined value of PSU-ID-Type header based on a specific Deutsche Bank branch.
verlag.PsuIdTypeHeaderInterceptor	Removes a PSU-ID-Type header if it contains an empty value for banks that use Verlag solutions.
ing.IngClientAuthentication	Signs a request to ING
adapter.impl.http.RequestSigningInterceptor	Base singing request interceptor.
adapter.impl.http.wiremock.WiremockStubDifferenceDetectingInterceptor	Detects differences between a performed request and recorded wiremock stubs.

8.4. WireMock.

For convenient testing of a client solution XS2A Adapter introduced a WireMock mode. In this configuration the adapter itself doesn’t communicate with a real bank but returns a request/response record (also called a stub).

Figure 1. XS2A Flow in WireMock mode

A comprehensive description about XS2A Adapter WireMock mode can be found here.

8.5. XS2A Adapter Exceptions.

XS2A Adapter developed its own set of exceptions that can occur in specific situations. All of them are subtypes of RuntimeException.

Figure 2. XS2A Adapter Exceptions

Table 29. XS2A Adapter Exceptions
Exception	Description	HTTP Status
AccessTokenException	Will occur if obtaining an access token failed. Used in specific OAuth approaches like DKB Embedded Pre-Step.	400..500*
AdapterNotFoundException	Thrown if XS2A Adapter Service Loader failed to find an adapter.	400
AspspRegistrationException	Thrown if ASPSP registry services failed to complete an operation.	400
AspspRegistrationNotFoundException	Thrown if no adapter found in the Registry by provided parameters (IBAN, BIC, Bank Code, etc.)	400
BadRequestException	Thrown if malformed request received, used in specific cases like missing scope for OAuth or wrong body of PSU Update Data operations.	400
ErrorResponseException	Common wrapper for a bank exception, most bank errors are folded into this class.	400..500*
HttpRequestSigningException	Thrown if XS2A Adapter failed to sign a request.	500
IbanException	Thrown if ASPSP Registry failed to process an IBAN.	400
NotAcceptableException	Thrown if JSON Response Handler received not a JSON formatted data.	406
OAuthException	Thrown if bank returned 401 or 403 for consent creation operation. This exception is specific for Sparda and Adorsys adapters.	403
PsuPasswordEncodingException	Thrown if PsuPasswordEncryptionService failed to complete an operation.	500
RequestValidationException	Thrown if a request failed a validation.	400
RequestAuthorizationValidationException	A subtype of RequestValidationException, thrown if AUTHORIZATION header is missing.	401
UncheckedSSLHandshakeException	Thrown if SSL Handshake Error occurred while establishing connection with a bank server.	500
Xs2aAdapterException	General exception, thrown if no other suitable exception exists.	500

* HTTP Status depends on the status from the bank response

8.6. XS2A Adapter configuration properties.

XS2A Adapter expects to have adapter.config.properties with configuration key-value pairs for some adapters.

Those properties are parsed by AdapterConfig service, which uses java.util.Properties under the hood.

Figure 3. AdapterConfig

AdapterConfig interface provides reading properties operations and loading a new properties file, mostly for test purposes.

Additional details on the XS2A Adapter properties are here.

8.7. XS2A Adapter Pkcs12KeyStore.

In order to interact with the Banks' XS2A Interfaces, a user will need to have an eIDAS certificate. XS2A Adapter expects a user to supply a valid PKCS #12 Key Store file (.p12) with a certificate as a JVM parameter (standalone) or as a parameter in the Pkcs12KeyStore constructor (library).

Description of the KeyStore and how to create it is already put down in here

8.8. XS2A Adapter Request Signing.

XS2A Adapter can sign the request for a user, if an adapter applied RequestSigningInterceptor and has a QSEAL certificate in a key store. In some specific cases (like ING) an adapter will have its own signing service.

XS2A Adapter Request Signing Infrastructure

Figure 4. XS2A Adapter Signing Infrastructure

Table 30. XS2A Adapter Interceptor
Class/Interface	Description
Interceptor	Interface provides the list of operations with default postHandle() implementation.
RequestSigningInterceptor	Adds signing data to the headers and delegates signing to the service.
RequestSigningService	Provides Digest, Signature and TPP Signature Certificate values.
Digest	Model for a Digest header.
DigestBuilder	Calculates digest.
Signature	Model for a Signature header.
Builder	Calculates signature.

Swagger-UI Swagger UI allows anyone to visualize and interact with the API’s resources without having any of the implementation logic in place.

10. Quality Requirements.

10.1. Quality Tree.

10.2. Quality Scenarios.

Understandability / Clear for users.

XS2A Adapter should be easy and low cost to deploy, set up, and launch in a user environment.

Understandability / Clear for contributors.

A potential contributor should be provided with necessary documentation and manuals for extending, improving an old adapter, or creating a new one.

Interoperability / Open and completely understood interface.

XS2A Adapter API must be open to the public, clear in details and low time and cost for utilizing as a library or a standalone application.

Testability / Coverage

XS2A Adapter test coverage should be above 80%.

Testability / Independent from a bank accessibility.

XS2A Adapter should provide a clear way to be tested (e.g. integration or system tests) as a part of a user solution without actual communication with a bank, which can be achieved via using WireMock mode.

Error transparent / Exceptions from ASPSPs must be passed

Original errors and exceptions from an ASPSP should be passed to an end-user (TPP) or at least logged for later tackling.

Validations clear / Adapter validation remarks should be clear

XS2A Adapter Validation Error must contain enough description for a user to determine and fix a cause.

Data mask / Sensitive information must be concealed

Data that can be considered as a user sensitive must be masked via HttpLogSanitizer.

11. Risks and Technical Debts.

Changes in bank APIs.

Unfortunately, there is no way to follow after bank API updates automatically to be up to the latest interface versions. Some banks do email notifications though, but it’s still required a manual checking.

Undocumented bugs.

Some bank XS2A implementations contain bugs (e.g. Unicredit mandatory Creditor Address field for payment initiation). All caught bugs are addressed to banks for fixing, that takes time for implementing from an ASPSP side, meanwhile XS2A Adapter amends the behavior if possible. We cannot guarantee that all glitches are covered but do everything possible to keep track of those and implement intermediate fixes.

Specific behavior.

Some banks have specific requirements that are not contradicting the BG specification but also not intuitive (Deutsche Bank predefined mandatory PSU-ID-Type values). XS2A Adapter covers some of those edge cases but not all. For example, a user will want to explicitly request a list of transactions in XML from Sparkasse and Fiducia banks as they are supporting responses in that format only.

Deviation behavior of production environment.

XS2A Adapter is tested against bank sandboxes. Those are expected to resemble a production environment and in most cases they are. However, there are some cases where behavior is not matching. As usual XS2A Adapter covers such specific instances as those are encountered (e.g. Verlag banks in the sandbox anticipate Access header to be plain/text only, in production - they accept only application/json). There is a possibility that not all mismatches are covered and documented.

Updating BG specification.

Berlin Group specification is evolving with time, even though the API is mostly constant, models can be volatile. XS2A Adapter tends to be inline with the latest specification version and migrating to a newer Adapter release can potentially break a user implementation. It’s advised checking Adapter release notes and Swagger before migrating.

Maintenance activities.

Banks sometimes perform maintenance activities on their side, XS2A Adapter is not designed to cover such edge cases, neither keep track of them, and will just pass a 5xx error from the ASPSP side. Some banks inform their users about maintenance works by email.

12. Glossary

Table 31. Glossary
Term	Definition
XS2A	Access to Account, a name of an interface, defined by Berlin Group to comply banks to the requirements of PSD2.
PSD2	Payment Service Directive 2, a European law for payments services.
TPP	Third Party Payment Service Provider, a system that acts on behalf of PSU on its data hold by ASPSP.
ASPSP	Account Servicing Payment Service Provider, a banking system that holds account data of PSU and performs corresponding operations over it.
AIS	Account Information Service is an online service which provides consolidated information on payment accounts held by a payment service user with payment service providers.
PIS	Payment Initiation Service is an online service which accesses a user’s payment account to initiate the transfer of funds on their behalf with the user’s consent and authentication.
SCA	Strong Customer Authentication is a requirement of the second Payment Services Directive (PSD2), which aims to add extra layers of security to electronic payments.
OAuth	Open Authorization is an open standard for authorization. OAuth provides client applications a 'secure delegated access' to server resources on behalf of a resource owner.
API	Application Programming Interface is a set of programming code that enables data transmission between one software product and another.
IDE	Integrated Development Environment is a software application that provides comprehensive facilities to computer programmers for software development.
REST	Representational State Transfer, is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other.
HTTP/HTTPS	HyperText Transfer Protocol is the communications protocol used to connect to Web servers on the Internet or on a local network (intranet). HTTPS (HTTP Secure) is the encrypted version of HTTP.
CSV	Comma-Separated Values file is a delimited text file that uses a comma to separate values.
URL	Uniform Resource Locator, colloquially termed a web address, is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it.
YAML	Yet Another Markup Language is a human friendly data serialization standard for all programming languages.
IDP Server	Identity Provider Server is a system entity that creates, maintains, and manages identity information for principals and also provides authentication services to relying applications within a federation or distributed network.
PSU	Payment Service User means a natural or legal person, including the Client, making use of Payment Services in the capacity of either Payer or Payee, or both.
BIC	Bank Identifier Code is the same as the bank’s SWIFT address.
BLZ or Bank Code	Bankleitzahl (DE) or Bank Code is a code assigned by a central bank, a bank supervisory body, or a Bankers Association in a country to all its licensed member banks or financial institutions.
Bank Name	ASPSP or a bank legal name.
IBAN	International Bank Account Number is an internationally agreed system of identifying bank accounts across national borders to facilitate the communication and processing of cross border transactions with a reduced risk of transcription errors.
BG	Stands for Berlin Group.
QSEAL	Qualified Electronic Seal Certificate is a qualified digital certificate under the trust services defined in the eIDAS Regulation.