Who must use the wealthAPI PSD2 Web Form?

wealthAPI provides PSD2 relevant services via its partners. As a customer of wealthAPI services, regulatory requirements of the European PSD2 regulation (ZAG law in Germany) may apply to you (please consult your lawyer or national Regulator for Financial Services for advice if in doubt).

If you do not have the permission / licence by your national Financial Services Regulator to provide PSD2-relevant services, according to the German Regulator you must fulfill the minimum requirements to not process bank credentials or access banks directly. In order to allow wealthAPI customers without PSD2 licence to fulfill this minimum requirement, we have created the wealthAPI PSD2 Web Form. Please note, that additional regulatory requirements may apply to your business and that wealthAPI cannot provide legal advice.

What is the wealthAPI PSD2 Web Form?

As certain wealthAPI services require banking-related credentials, you may need to let the user enter credentials in wealthAPI PSD2 web form instead of in your application. The PSD2 web form is a special endpoint (web-page) hosted on wealthAPI’s servers. Please note that the wealthAPI PSD2 Web Form must be opened in a dedicated Web-Browser tab/window or via a redirect. Opening in an iFrame is not allowed by the German regulator. When opening the web-form from a mobile APP, using a web-view is a compliant option. The PSD2 Web Form is part of the wealthAPI “Banking APIs & Regulatory” module, which is the basis for any other PSD2 related services. You will have to use the PSD2 web form in case you do not have a permission / licence from your national Financial Services Regulator.

The following screenshot illustrates an example for the web-form. Depending on the context and your mandator’s configuration, the form may have a different appearance. Please contact us if you would like to have the web-form styled for your mandator.

Open

What are the use cases of the wealthAPI PSD2 Web Form?

Whether you need to use wealthAPI’s web form (and if yes, to what extent), depends on your regulatory permissions. Without a permission for Account information (AIS/KID), you will have to use the PSD2 Web Form for the following use cases:

• Import / Update Bank Connection (including automated batch updates)

• Edit Bank Connection (Editing the credentials)

wealthAPI manages the display of the PSD2 Web Form automatically based on your regulatory permissions. While no confirmation of a regulatory permission was filed to wealthAPI, we will assume that no Account Information (AIS/KID) license is present and thus the PSD2 Web Form will be enabled for your company. Please contact our support team at info@wealthAPI.eu for the necessary configurations.

How do I implement the Web Form Flow?

Whenever your application is calling a wealthAPI service requiring your user's banking credentials, and you do not have the regulatory permission to handle those credentials yourself, then the service will respond with HTTP error code 401 (unauthorized) error, containing an WEB_FORM_REQUIRED error message.

If the request was to add a new bank connection, the error message will look as illustrated below. You should respond to this message by creating a web-form using endpoint createTppWebForm (POST /api/v2/tppWebForms). After successful web-form creation, you may initiate the web-form flow by redirecting the user to the URL given in the web-form attribute startWebFormFlowUrl.

If the request was to update an existing bank connection, the error message will contain the web form start URL as well. In this case, the error message will look as illustrated below. A web form has automatically been created; and the start web form URL can be used to directly jump into the web-form process.

During an update, a web-form may be required because either credential or TAN input is required. The web-form remembers which input is required and takes the user to the requested step in the authentication process.

Note that an update will only update the interface that triggered the error; and it will also not attempt to synchronize depot positions. This is because a meaningful synchronization requires up-to-date transaction data; and this is not ensured when only part of the interfaces is up-to-date.

The respective web-form URL is defined by wealthAPI and may be subject to change.

Choosing what to import or update

With the introduction of the new XS2A interfaces, a bank connection may now have up to three different ways to connect. These are XS2A, FINTS_SERVER and WEB_SCRAPER. If you provide an interface, only this interface will be added or updated. Depots will not be imported, as we cannot know if all required reference accounts are available.

If you do not provide an interface, all interfaces will be added or updated and depots (if available) will be imported.

Redirecting to your application

Upon successful completion of the web form flow, the user will be redirected to your client application. The URL used for redirection is defined by adding the URL as parameter redirectUrl to the start web form flow URL. Note that the URL composed in the parameter must be URL encoded.

So, the web form start URL would look like 

https://wealthapi.eu/.../{token}?redirectUrl={yourUrlEncodedString}

Security Restrictions

To prevent misuse, the web form can be requested exactly once. Attempts to access a web-form twice will result in a “not found exception”.

Handling result data

It is important to remember the web-form token. Using the 

GET /v1/bankConnections/webFormFlow/{token} endpoint you may retrieve the bankConnection imported or updated during the web-form flow.

Wrapping up

If required, you might want to add some user identifier to the callbackUrl or redirectUrl to be able to resolve the user context in your application in order to get hold of an appropriate access token. For security reasons, you should never include an access token itself in the web form URL.

 A graphical illustration of the web form flow is given below:

Open

The web form flow, starting with a user requesting import or update of a bank connection.

Implications of PSD2 on automatic batch update

Banks may update for a period of at maximum three months, but banks may also choose shorter periods. On top, a bank may stop the import whenever its internal warning system decides to do so. As such, a bank connection needs to be updated manually after at least three months.

How can I test the Web Form Flow?

The web-form flow can be tested via the wealthAPI API Sandbox.