PSD2 APIs

Overview PSD2

Welcome to the PSD2 API of Bank Alpinum. These pages dedicated to PSD2 help you perform first steps to access bank accounts through our API. The API is providing access to accounts that are online enabled by a valid e-banking contract. For those accounts the API offers three services.

Account Information Service (AIS)
Get account informations, balance and transaction information
Payment Initiation Service (PIS)
Initiate or cancel a sepa credit transfer payment
Confirmation of the Availability of Funds service (FCS)
Get confirmation of the availability of funds

All three services can be used by licensed TPPs (Third Party Provider) possessing the specific certificate. Each service offered by a TPP needs to be instructed by the PSU (Payment System User).

These instructions are called consents. In order to establish a valid consent a consent request is created by the TPP. Once that consent is approved by the PSU the consent is valid and can be used to retrieve account information from the banking system. The following scheme shows the process for creating and validating a consent.

Getting Started with PSD2

Our XS2A API follow the specifications of the Berlin Group.
As of 30.09.2020 the test option (hereinafter referred to as "Sandbox") is available for all payment initiation, account information and payment service providers.

XS2A Interface

Access to sandbox:
https://xs2a-sandbox.bankalpinum.com
The test interface ("XS2A Sandbox") provides pure test data with random IBAN and random amounts.
Access to production:
https://xs2a.bankalpinum.com

TPP Certificate

For a TPP to gain access to the sandbox or production environment, you must have a valid QWAC certificate (Qualified Website Authentication Certificate). The certificates must be issued by one of the following certificate authorities:
A-Trust(Österreich), D-Trust(DE), CertEurope(FR), InfoCert(IT), BVTrust(DE)

If you have a certificate from another certificate authority, please contact us in order to include the certificate of the respective CA.

Please use that certificate to access both, the sandbox and the production environment.
An example API call in CURL would look like:

curl \
-X GET https://xs2a-sandbox.bankalpinum.com/v1/consents/{consent-id} \
--cert signed_cert.crt:password \
--key private.key

Consent process and test accounts

To gain access to account information, the TPP first sends a consent request to the bank. Before the request is forwarded to the PSD2 interfaces, the certificate of the TPP is checked for validity. If the certificate is valid the consent is created in the consent management system of the bank. Before that consent can be used for account information requests, the consent must be authorized by the PSU (Payment System User). To initiate this flow, the TPP receives a link in the response of the consent creation request. This link will be forwarded to the PSU. Afterwards, the PSU logs on to the bank's access identity system with his e-banking account, password, and a second factor (Short Message or CrontoSign). A consent user interface will be shown, and the PSU can confirm or deny the consent. After successful consent validation, the TPP can request the required account information using the validated consent-id.

In the sandbox environment the following contract (PSUID) can be used to validate a consent and to go through the whole consent flow:

Contract number: VT9999999 / password: Vt_9999999 / Second factor: mTan (Short Message)
For testing purposes, we can provide a fixed token number to use as second factor.
Please get in touch with us by email to receive the fixed token number.

The SCA (strong customer authentication) process will be executed in 4 steps:
1. Open the sca redirect link from the consent response body. The login screen from the e-banking system will appear
2. Input PSUID (VT9999999) and password
3. Input token from received short message. After valid input, the consent user interface will be shown
4. Approve or deny consent or payment initiation. Afterward you will be forwarded to the tpp application

In case of technical issues, please send an email to the indicated contact.

API endpoints

For information about the available endpoints, please see the API documentation tab.

Fallback mechanism

In the event of a failure, the emergency mechanism pursuant to Article 33 (4) DelVO (EU) 2018/389 shall come into effect: In the event of an unforeseen unavailability or a system failure of the XS2A interface pursuant to Article 33 (1) DelVO (EU) 2018/389, the use of the online banking access provided for our customer under the URL https://xs2a-fallback.bankalpinum.com/authen/login is permitted.

For identification purposes, the respective certificate must be sent with each request, which is also used when requesting the XS2A interface. This does not change the behavior of online banking; the same web pages are delivered.

We refer to the general conditions mentioned in Article 33 (5) DelVO (EU) 2018/389. The information required in Article 33 (5) e) DelVO (EU) 2018/389 should be sent to the e-mail addresses mentioned in section "contact".

API Documentation PSD2

The API documentation for PSD2 with all endpoints can be found here:
Open API Documentation

Frequently asked questions

Can I do requests from the API documentation directly?

A TPP requires an appropriate certificate to execute a request. These certificates cannot be stored in the documentation environment. For this reason, requests must be sent from a local program (e.g., CURL), including the certificates. However, the CURL statements can be generated via the API documentation.

My certificate is from another Certificate Authority. What can I do?

Please contact us. We can extend the list of trusted Certificate Authorities.

What types of payments are supported?

Currently the payment type SEPA CREDIT TRANSFER in currencies EUR and CHF is supported. More currencies could be added to the list of available currencies. The api currently supports single payments.

What types of consents are supported?

There are two type of consents:
Consent for Account information to retrieve account balance and account transactions
Consent for Funds Coverage Check. To do a fund coverage check, the TPP needs to establish a consent for FCS and have the PSU approve it.

Why there is no consent needed in advance for payment initiations?

The initiation of a single payment always requires the approval of this payment. The approval is done by logging in the PSU with PSUID, a password, and the 2nd factor. After that, the payment details are displayed, and the PSU can accept or deny the initiation of the payment. Due to this process, consent for payments in advance is not necessary.

What are the limitations of the sandbox?

Payment initiations can be performed. However, payments will not be processed and the status will remain "PDNG" (pending).

A fund coverage request (FCS) for a given account will only be executed correctly if the currency for the requested amount is the same as the account currency.

How does a TPP get onboarded for productive access?

The onboarding for the productive environment is an automatic process. It is performed based on your client certificate and will take place with the first productive request.

What authorization method should be set for use with a smartphone?

If the payment service user is supposed to execute the authorization process on the smartphone, the authentication method mTan (Short message) should be set on the e-banking contract. By delivering the message as a short message, the PSU can transfer the code directly to the login form.

How can I get in contact with you in case of bugs or issues?

Please see contact details in tab "Contact". We will try to get back to you as soon as possible.

Contact and Support

For general questions about the PSD2 services and payment services offered by Bank Alpinum, please get in contact via email to:

zv@bankalpinum.com

For technical questions about the PSD2 API, please get in contact via email to:

techsupp@sobaco.ch

KPI: PSD2 availability and response times

The regulatory required reports show the availability and response times of the PSD2 services.
After the end of each quarter the reports are produced and published on this page.

Data structure in file

The columns in the file have the following meaning:

Date: Day of KPI assessment, each day in period is listed
Uptime: % of day the system was available
Avg PIS: average response time in milliseconds of the PIS service
Avg AIS: average response time in milliseconds of the AIS service
Avg FCS: average response time in milliseconds of the FCS service

Example CSV file with column structure

Data files

kpi-alpinum-2021Q3.csv

kpi-alpinum-2021Q2.csv

kpi-alpinum-2021Q1.csv

kpi-alpinum-2020Q4.csv

Change Log PSD2

Changes for Service PSD2 planned or done:

Active: 12.08.2021

Maintenance release deployed with documentation of end points updated .

Active: 30.11.2020

PSD2 API with Finnova Integration. Ready to use by TPP.

Active: 30.09.2020

PSD2 API with a sandbox environment for integration and testing purposes.