...
| Note |
|---|
This |
...
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.
...
Table of Contents
| 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
Submit a new Certificate
Get Certificates list
Get Certificate details
Delete existing Certificate
Client credentials management services
Submit new Client Credentials
Get Client Credentials list
Get Client Credentials details
Update existing Client Credentials
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
...
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
...
page is now deprecated. We urge you to check out our new Access Public Documentation that we recently published instead, which covers all state-of-the-art information of our products. Note: due to overall restructuring for our new Access Public Documentation, there might not be a corresponding page with the exact same content like this deprecated page in our new documentation. However, we make sure to already cover all information you need, including this content, in our new documentation. |