PROFOS eBanking PSD2 - API

API-Version: 1.01, valid since 2020-05-04

Abbreviations

ASPSP-Account Servicing Payment Service Provider
BGS-Berlin Group Specification/Standard
PSD2-Payment Services Directive 2
PSU-Payment Service User
SCA-Strong Customer Authentication (2 factor login)
TPP-Thrid Party Provider
PIS-Payment Initiation Service
AISP-Account Information Service Provider
QTSP-Qualified Trust Service Provider (issuer of eIDAS certificates)
XS2A-Access to account (PSD2 REST-API)

About

With PSD2 the European Union has published a new directive on payment services in the internal market (COMMISSION DELEGATED REGULATION (EU) 2018/389) Among others PSD2 contains regulations of new services to be operated by so called Third Party Payment Service Providers (TPP) on behalf of a Payment Service User (PSU). These new services are
- Payment Initiation Service (PIS) to be operated by a Payment Initiation Service Provider (PISP) TPP as defined by article 66 of PSD2
- Account Information Service (AIS) to be operated by an Account Information Service Provider (AISP) TPP as defined by article 67 of PSD2

The purpose of this document is to give a high-level overview of functionality and complexity of PROFOS eBanking, its expandability and the API(s) in use for technical-oriented audiences. Full technical documentation is provided via interface-descriptive files (*.yaml files) as well as via swagger instance. Note: PROFOS eBanking implemented the PSD2 specification of Berlin Group. This document does not include the description of the Berlin Group operational rules and implementation guidelines on account information and payment initiation. This standardized specification can be found here: https://www.berlin-group.org/nextgenpsd2-downloads
Interoperatibility Framework Version: 1.3.4

API

API-Documentation: Link

Swagger API-Documentation: Link

API-Endpoint (Base URL): https://test-ebanking.wienerprivatbank.cpb.services/banking-middleware/api-psd
Note: this Link will not work directly in a browser since the mandatory http headers are not set on the client side according to Berlin Group Specification

Additional information about the interface (implementation details) to Berlin Group Specification

- In accordance to PSD2, this API is only implementing features that are part of PROFOS eBanking.
- Strong Customer Authentication (SCA) is done via redirect approach only
- this interface only supports current caccounts ("Girokonten")
- this implementation only supports the REST-API definition
- this implementation only supports JSON-format
- QSEAL QWAC added as TPP-Signature-Certificate Header
- optional attributes are marked as "not supported" in API-documentation (as well as Swagger)

Support: Technical support (in german) is available by request - please contact us via official contact info (see imprint).

Availability

In accordance with Article 32(4) of the RTS, ASPSPs are required to publish data on the availability and performance of the dedicated interface and of each of the interfaces made available to the PSUs for directly accessing their accounts online, and to do so in a way that enables TPPs and PSUs to compare the availability and performance of the dedicated interface with each of the said PSU interfaces.

'Service level, availability and performance'

2.1. The ASPSP should define key performance indicators (KPIs) and service level targets, including for problem resolution, out of hours support, monitoring, contingency plans and maintenance for its dedicated interface, that are at least as stringent as those for the interface(s) made available to its own payment service users (PSUs) for directly accessing their payment accounts online.

2.2. The ASPSP should define at a minimum, the following KPIs of the availability of the dedicated interface: a. the uptime per day of all interfaces; and b. the downtime per day of all interfaces.

2.3. In addition to the KPIs on availability in Guideline 2.2, the ASPSP should define, at a minimum, the following KPIs for the performance of the dedicated interface: a. the daily average time (in milliseconds) taken, per request, for the ASPSP to provide the payment initiation service provider (PISP) with all the information requested in accordance with Article 66(4)(b) of PSD2 and Article 36(1)(b) of the RTS; b. the daily average time (in milliseconds) taken, per request, for the ASPSP to provide the account information service provider (AISP) with all the information requested in accordance with Article 36(1)(a) of the RTS; c. the daily average time (in milliseconds) taken, per request, for the ASPSP to provide the card-based payment instrument issuer (CBPII) or the PISP with a yes-no confirmation in accordance with Article 65(3) of PSD2 and Article 36(1)(c) of the RTS; d. the daily error response rate – calculated as the number of error messages concerning errors attributable to the ASPSP sent by the ASPSP to the PISPs, AISPs and CBPIIs in accordance with Article 36(2) of the RTS per day, divided by the number of requests received by the ASPSP from AISPs, PISPs and CBPIIs in the same day.

2.4. For the purpose of calculating the availability indicators set out in Guideline 2.2 for the dedicated interface, the ASPSP should: a. calculate the percentage uptime as 100% minus the percentage downtime; b. calculate the percentage downtime using the total number of seconds the dedicated interface was down in a 24-hour period, starting and ending at midnight; c. count the interface as down when five consecutive requests for access to information for the provision of payment initiation services, account information services or confirmation of availability of funds are not replied to within a total timeframe of 30 seconds, irrespective of whether these requests originate from one or multiple PISPs, AISPs or CBPIIs. In such a case, the ASPSP should calculate downtime from the moment it has received the first request in the series of five consecutive requests that were not replied to within 30 seconds, provided that there is no successful request in between those five requests to which a reply has been provided.

'Publication of statistics'

3.1 For the purpose of Article 32(4) of the RTS, the ASPSP should provide its competent authority with a plan for publication of daily statistics on a quarterly basis on the availability and performance of the dedicated interface as set out in Guidelines 2.2 and 2.3, and of each of the interfaces made available to its own PSUs for directly accessing their payment accounts online, together with information on where these statistics will be published and the date of first publication.

3.2 The publication referred to in Guideline 3.1 above should enable PISPs, AISPs, CBPIIs and PSUs to compare the availability and performance of the dedicated interface with the availability and performance of each of the interfaces made available by the ASPSP to its PSUs for directly accessing their payment accounts online on a daily basis.

API Statistics: Link

Contingency measures, fall-back

Contingency measures are available, as noted in Article 33 of regulation 2018/389. For this purpose, account servicing payment service providers shall ensure that the payment service providers referred to in Article 30(1) can be identified and can rely on the authentication procedures provided by the account servicing payment service provider to the payment service user.

In order to identify yourself as a third party provider a login using this URI is required: [ENVIRONMENT]/banking-middleware/api/tppLogin It is mandatory to perform the request using a valid eIDAS certificate. After verifying the certificate the fall-back mechanism responds with a session cookie that identifies the third party provider as well as the payment services user.

Description of the technical implementation and program flow:

Step 1)

For this call the disposerNumber and Password of the PSU is required. Additionally your eIDAS Certificate will be validated. A successful call will generate and send a mobile TAN to the PSU and return an Authorization Header that is needed for the second step.

Request-URL
POST [ENVIRONMENT]/api/tppLogin
Request Payload
{
"disposerNumber" : "123456789",
"password": "SuperSecretPassword"
}
Request HTTP Header
Content-Type: Application/Json
lang: de or en (no quotation marks)
TPP-Signature-Certificate: base64EncodedEidasCertificate
Response
HTTP Status 204 OK
Authorization: Bearer ...

Step 2)

In the second step the previously sent authorization header will be again validated. Afterwards the sent mTAN will be checked. If both validations succeed, then a Cooke will be generated with the name "ebanking-iam-auth-token". The cookie is transported in the header parameter

Request-URL
POST [ENVIRONMENT]/api/tppLogin/two-factor
Request Payload
{
"tan" : "tanValue"
}
Request HTTP Header
Content-Type: Application/Json
lang: de or en (no quotation marks)
Authorization: Bearer ... (previously obtained Authorization Header)

Response Header
HTTP Status 200 OK
Set-Cookie: Cookie to be set in client
Authorization: Bearer ...
Response Payload
{
"ebanking-iam-auth-token" : "Delicious Cookie"
}

With the cookie set in the client and opening our eBanking Application an automatic login will be performed.