Registering with an ASPSP to gain TPP API access
Audience
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 interfaces of the Account Servicing Payment Service Providers (ASPSPs, i.e. banks).
Purpose
This document describes the steps that should be done initially and the information required from TPPs to get access to the XS2A APIs of banks.
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 require 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 the 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 license to access ASPSP APIs.
Developer Portals
Common structure and capabilities
A developer portal is a website of an ASPSP, where TPPs can:
browse the API catalog;
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", and "Developer Portal". Please see the examples of PSD2 developer portals:
https://developer.unicredit.eu
https://api-dashboard.raiffeisen.at
Usually, developer portals contain a "Get started" page which explains the process of registration with the developer portal, creating a TPP application, and getting client credentials and/or access tokens. It provides links to production and sandbox environments and other information required 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 on the "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 sections, 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 the support team may be required to receive necessary documents and environment access. Some banks may ask for additional information about the company as VAT number, license number, certificates, etc.
Registration on the developer portal
Registration can be required to gain full access to a developer portal. As a rule, the following details must be provided: name and surname, email, company, and country. Additionally, the following details may be asked to be added: VAT number, license number, etc. These details are needed for further validation in the production environment.
Some banks may require uploading a valid eIDAS Certificate to gain access to related documentation and application registration.
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, the 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 the name, description, and platform of the application. Additionally, you may be asked to fill in the redirect URL (in case of Redirect SCA), application type, programming language, upload application or company logo, etc.
If a bank has branches in different countries, users may be asked which bank they would like to connect to. Note that the 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, Client Secret and, in some cases, API key is generated.
Client Secret is usually shown only once. These Credentials will be required further 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, refer to the TPP Certificates and TPP Credentials services.
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 allow 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, its 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. A QSeal certificate assures the authenticity and integrity of the transmitted data, getting legal evidence of the transaction, that can be used as 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 specifications:
Authentication of a PSU in a pre-step, translating this authentication into an Access Token to be used at the XS2A interface afterward;
Integration as an OAuth2 SCA Approach to be used for authorization of payment initiations and consents.
In the current section, we talk about using the 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. The API Key is a unique string of alphanumeric characters transmitted as part of an API request that authenticates the source of the API request.
After you have received the 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.
The easy way: the finAPI PSD2 license
finAPI takes over all TPP registration, Certificate application, and TPP authentication activities for customers using the finAPI PSD2 license.