Using your own eIDAS Certificates and TPP Credentials in finAPI Access PSD2

Audience

This Document applies to TPPs that are fully licensed by their national supervisory authority as AISP and/or PISP and must thus use their own Certificates and Client Credentials to access the ASPSP APIs.

Purpose of this document

This Document describes how fully licensed TPPs can use finAPI Access PSD2 to access ASPSP APIs using their own eIDAS TPP Certificates and Client Credentials, which are required by ASPSPs.

For the description of how eIDAS TPP Certificates can be obtained, please refer to the requirements of EBA-RTS, ETSI TS 119 495 V1.2.1 (2018-11) technical specification and the list of qualified trust service providers according to the eIDAS regulation.

Table of Contents

 

Summary

In order to use finAPI Access PSD2 services a client who is a fully licenced TPP must have at least one global QWAC and/or QSeal certificate. These certificates are required in order to access PSD2 APIs of ASPSPs (XS2A). Each Certificate (QWAC or QSeal) consists of a Private key, Certificate itself, a passphrase (optional) and valid from/until dates.

Some banks may also require a set of Bank API specific Client Credentials to authenticate a TPP. Each set of Client Credentials includes at least one of the following attributes: Сlient Id, Сlient Secret, API key. Additionally valid from/until dates can be provided.

Licenced TPPs can store their own TPP Certificates / Client Credentials in finAPI Access in order to have a quick and secure access to XS2A of ASPSPs. finAPI Access allows clients to easily manage their TPP certificates / client credentials for multiple ASPSPs: edit, delete, view existing and upload new TPP Certificates / Client Credentials.

Unlicensed Clients can use the built in finAPI TPP Certificates / Client Credentials.

Please note that bank-specific certificates are not supported.

Audit logs can be requested by standard support channel. There is no Web service for this purpose.

Security

From security perspective such data as QWAC and QSeal Certificates and Bank Credentials is sensible and must be protected.

HTTPS is used to ensure data is encrypted in transit from client to finAPI.

Within finAPI realm this data is treated with the highest level of security. Certificates and credentials are kept in the highly secure finAPI database and secured with double encryption. All access to the certificates and/or credentials is logged in audit logs.

Services

finAPI Access PSD2 supports the following services:

Certificate management services
  1. Submit a new Certificate

  2. Get Certificates list

  3. Get Certificate details

  4. Delete existing Certificate

Client credentials management services
  1. Submit new Client Credentials

  2. Get Client Credentials list

  3. Get Client Credentials details

  4. Update existing Client Credentials

  5. Delete existing Client Credentials

All services require the authentication of an admin /mandator client in finAPI.

 

Certificate management services

1. Submit a new Certificate

Using POST /tppAuthentication/certificates endpoint you can submit a Certificate to finAPI Access PSD2 database. The response of the server will contain "certificateId" of the created certificate, for example "93ea9700".

The service saves the Certificate encrypting Private key and passphrase using the same logic as used for user's Bank Credentials.

A Client is allowed to submit more than one Certificate. In this case the newest uploaded valid Certificate will be selected.

Expired Certificates ("valid until" date is in the past) can not be submitted, otherwise corresponding error will be returned.

The Certificates are checked for duplication by "PrivateKey" parameter. Duplicate certificates can not be uploaded to the database.

There is no service for updating uploaded Certificates. In case if Certificate is not valid anymore, please delete it using Delete existing Certificate service and then upload a new Certificate.

2. Get Certificates list

Using GET /tppAuthentication/certificates endpoint you can overview the list of all existing Client's Certificates in finAPI Access PSD2 database.

Only the Certificates belonging to the Client will be shown. It is not possible to filter the Certificates. The expired Certificates are also displayed.

The service does NOT return sensitive information like Private key or passphrase. Only Certificate id, type (QWAC or QsealC), label and validFrom/validUntil dates will be returned.

3. Get Certificate details

Using GET /tppAuthentication/certificates/{id} endpoint you can view the details of a specific Certificate. The search is done by Certificate id.

The service does NOT return sensitive information like Private key or passphrase. Only Certificate id, type (QWAC or QsealC), Certificate itself, label and validFrom/validUnti dates will be returned.

The service will return an error in case if:

  • Certificate is not found;

  • Client has no access to the Certificate (access token is provided for Client A, but the Certificate belongs to Client B).

4. Delete existing Certificate

Using DELETE /tppAuthentication/certificates/{id} endpoint you can delete existing Certificate. The search is done by Certificate id.

The Certificate will be deleted from finAPI Access PSD2 database.

The service will return an error in case if:

  • Certificate is not found;

  • Client has no access to the Certificate (access token is provided for Client A, but Certificate belongs to Client B).

TPP Credentials Services

1. Submit new TPP Credentials

Using POST /tppAuthentication/clientCredentials endpoint you can submit Client Credentials to finAPI Access PSD2 database.

Client Credentials can include Client ID, Client Secret, API key (at least one of the mentioned parameters must be provided). Clients receive Client Credentials themselves by registering at the Bank's web site/Developer portal. Client Credentials for a Bank group will be valid for all the Banks members of this group as they are linked to Bank's domain URL.

Response of the server will contain "credentialId" of created Client Credentials, for example "93ea9701".

The service saves Client Credentials encrypting Client ID, Client Secret and API key using the same logic as used for user's Bank Credentials.

The Client can set the terms of Client Credentials validity using parameters "validFrom" and "validUntil" in the request. If the parameter "validUntil" is null, the term of Client Credentials usage will be "indefinite" (no limit). Expired Client Credentials ("valid until" date is in the past) can not be submitted, otherwise corresponding error will be returned. If the parameter "validFrom" is null, it will be set to the date of Credentials submission to the database.

There is a service for updating uploaded Client Credentials. In case if Client Credentials are not valid anymore, please use Update existing Client Credentials.

2. Get Client Credentials list

Using GET /tppAuthentication/clientCredentials endpoint you can overview the list of all existing Client Credentials in finAPI Access PSD2 database.

Only Client Credentials belonging to the Client will be shown. The expired Client Credentials are also displayed.

The service does NOT return sensitive information like Client ID, Client Secret or API key. Only Certificate id, type (QWAC or QsealC), label and validFrom/validUntil dates will be returned.

It is possible to filter Client Credentials list using "search" parameter. FinAPI Access PSD2 will return only Client Credentials belonging to those Banks whose "name", "blz", or "bic" contain the given search string (the matching works case-insensitive). If the given search string consists of several terms (separated by a white space), then ALL of these terms must apply to a Bank in order for it to get included into the list.

3. Get Client Credentials details

Using GET /tppAuthentication/clientCredentials/{id} endpoint you can view the details of specific Client Credentials. The search is done by Client Credentials id.

The service does NOT return sensitive information like Client ID, Client Secret or API key. Only Client Credentials id, label, Bank URL and validFrom/validUntil dates will be returned.

The service will return an error in case if:

  • Client Credentials are not found;

  • Client has no access to the Credentials (access token is provided for Client A, but Credentials belong to Client B).

4. Update existing Client Credentials

Using PATCH /tppAuthentication/clientCredentials/{id} endpoint you can update existing Client Credentials.

A Client provides Client Credentials id.

The following attributes can be updated:

  • Client ID;

  • Client Secret;

  • API Key;

  • label;

  • Bank URL;

  • validFrom (date);

  • validUntil (date).

The service does NOT return sensitive information like Client ID, Client Secret or API key. Only Client Credentials id, label, Bank URL and validFrom/validUntil dates will be returned.

The service will return an error in case if:

  • Client Credentials are not found;

  • Client has no access to the Credentials (access token is provided for Client A, but the Credentials belong to Client B).

5. Delete existing Client Credentials

Using DELETE /tppAuthentication/clientCredentials/{id} endpoint you can delete existing Client Credentials. The search is done by Credentials id.

Client Credentials will be deleted from finAPI Access PSD2 database.

The service will return an error in case if:

  • Client Credentials are not found;

  • Client has no access to Client Credentials (access token is provided for Client A, but Certificate belongs to Client B).

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.

Term

Definition

Term

Definition

ASPSP

Account Servicing Payment Service Provider

Bank

A financial institution that accepts deposits from the public and creates credit.

Certificate

A data file that digitally binds a cryptographic key to an organization’s details or a package containing it and additionally a Private key and (optionally) a passphrase.

Client

A finAPI customer that has TTP certification

Credentials

A user's authentication information (typically a password, a token, or a Certificate).

Data at Rest

Data that is being stored in stable destination systems

Private key

A separate file that’s used in the encryption/decryption of data sent between the server and the connecting clients.

TPP

Third Party Payment Service Provider

XS2A

PSD2 compliant Access to Account Interface