Audience of this document

This Document applies to TPPs that are fully licensed by their national supervisory authority as AISP and/or PISP and would like to access XS2A of ASPSPs.

Purpose of this document

This Document describes the steps that should be done initially and the information required from TPPs in order to get access to XS2A APIs of Banks.

Table of Contents

Summary

As a TPP, you can access the APIs either for testing purposes (e.g. to build your integration in a sandbox environment) or to get access to the production systems of the banks. In any case the majority of banks requires a TPP to be registered manually on their developer portal and create a TPP application there. The process differs from bank to bank due to selected security methods. Also the flow for a sandbox may be simplified and differ from actual production flow due to testing purposes.

This document accumulates general information about the most common ways of registering your TPP application with an ASPSP/bank API.

Please note that in order to use an XS2A API of any ASPSP, a Client MUST have at least one global eIDAS QWAC and / or QSeal Certificate.

finAPI performs all registration and authentication activities for finAPI customers who use the finAPI PSD2 Licence to access ASPSP APIs.

Developer Portals

Common structure and capabilities

Developer portal is a website of an ASPSP, where software developers of TPPs can:

• browse the API catalog;

• read about APIs solution;

• find out how to use the APIs and download related documentation;

• find how to interact with sandbox and production environments of APIs;

• access security policy information for APIs;

• contact the support team, etc.

You can find the link to the developer portal of a bank on the official bank site by searching "PSD2", "XS2A", "API", "Developer Portal". Please see the examples of PSD2 developer portals:

https://developer.unicredit.eu

https://api-dashboard.raiffeisen.at

https://developer.ing.com

Usually developer portals contain a "Get started" page which explains the process of registration with the developer portal, creating TPP application, getting client credentials and/or access tokens, links to production and sandbox environments and other information required in order to connect to XS2A successfully. The flow differs from bank to bank due to the following factors: selected SCA approach and methods, additional security checks (for example OAuth2 pre-step), etc. Please see the example of "Get started" page:

https://developer.ing.com/openbanking/get-started.

Also, a developer portal can contain links to specification files or Swagger (for example https://www.banking.co.at/psd2#tab1), Postman collections, testing data (for example accounts, PSU IDs), FAQ section and other useful information.

Some banks may not have a developer portal. Please follow the instructions of the Bank on their official website in this case. Getting in contact with support team may be required in order to receive necessary documents and environment access. Some Banks may ask for additional information about the company as VAT number, licence number, certificates, etc.

Registration on developer portal

Registration can be required in order to gain the full access to a developer portal. As a rule the following details must be provided: name and surname, email, company, country. Additionally the following details may be asked to be added: VAT number, license number, etc. All these information are needed for further validation at production environment.

Some Banks (for example UniCredit) may require to upload a valid eIDAS Certificate to gain access to related documentation and application registration.

ING Bank allows to login with GitHub account.

Some developer portals do not require registration and application creation (for example https://psd2.developer.commerzbank.com/). This means that only QWAC and/or QSeal are required in order to reach XS2A.

Creating an application

After being signed in to the developer portal, creation of an application may be required to receive client credentials for communication with the API in addition to the eIDAS certificate.

Commonly you have to provide a name of the application, application description, platform. Additionally you may be asked to fill in redirect URL (if Redirect SCA is selected by the Bank), application type, programming language, upload application or company logo, etc.

If a Bank has branches in different countries, users may be asked to which bank they would like to connect. Note that standard SCA approach and other characteristics may differ for branches in different countries. Banks require a TPP to subscribe to the APIs that the TPP wants to use (AISP, PISP).

Some Banks require to enable and configure OAuth2 to proceed and / or upload eIDAS Certificates.

After Application creation Client ID and Client Secret (in some cases API key) are generated.

Client Secret is usually shown only once. These Credentials will be required further in order to gain an access token and execute requests to the endpoints.

All sensitive data (QWAC, QSeal, Client ID, Client Secret, API Key) can later be easily and securely managed and stored in finAPI Access PSD2.

In some cases a TPP has to wait for the bank's approval after the application creation or developer portal registration.

QWAC and QSeal

The eIDAS Certificates referred to in this document are SSL Certificates with dedicated protection profiles that allows them to be used in the PSD2 context. To achieve the PSD2 security requirements, banks and PSD2 service providers will use Qualified Certificates for Websites and Qualified Certificates for Electronic Seals. Those certificates will be issued by Qualified Trust Service Providers (QTSPs) based on the new technical standard, ETSI TS 119 495. Qualified Certificates enable identification and verification of the payment institution by a third party. Identification will be based on the legal name of an organization, registration number and its main role(s) in the payments space.

There are two types of such Certificates:

• QWAC (Qualified Website Authentication Certificate): used as Client Certificates in MA-TLS;

• QSeal (Qualified Certificate for Seals): used to sign requests using http-signature.

All PSD2 APIs require at least one type of Certificates: QWAC to access the API or QSeal for http-signature, i.e. message signing.

A QWAC can open a secure channel between the Bank and the TPP, enabling a TPP to identify itself to the bank and to create a trustable channel. Instead, a QSeal assures the authenticity and integrity of the transmitted data, getting a legal evidence of the transaction, that can be used as a proof.

Client Credentials

Client ID and Client Secret are usually used if an ASPSP requires the OAuth2 process.

OAuth2 can be integrated in two ways according to Berlin Group specification:

1. an authentication of a PSU in a pre-step, translating this authentication into an Access Token to be used at the XS2A interface afterwards;

2. an integration as an OAuth2 SCA Approach to be used for authorisation of payment initiations and consents.

In current section we talk about using OAuth2 process as a pre-step.

After registering your application, you will receive a Client ID and a Client Secret in your application details on the developer portal. The Client ID is considered public information, and is used to build login URLs.

Some ASPSPs generate an API Key after successful application creation. API Key is a unique string of alphanumeric characters transmitted as part of an API request that authenticate the source of the API request.

After you have received Client ID and Client Secret and / or API Key, you need to retrieve an Access Token to successfully call your selected API. The process is complex and varies for different Banks and will be done by finAPI Access PSD2.

The easy way: the finAPI PSD2 licence

finAPI takes over all TPP registration, Certificate application and TPP authentication activities for customers using the finAPI PSD2 lincence.

Terms and Definitions

This Document makes reference to various defined terms which have a specific meaning in the context of this Document. In this Document, a defined term is indicated with a capital letter.