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.

The default web-form layout:

Example: web-form layout for wealthAPI’s partner finanzfluss.de

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?

The first step typically is to create a new web-form. Here, you will distinguish two use cases

Use case: Import a bank connection

Lookup the bank via the GET /v1/banks api. The response for each bank will contain the attributes multibankingApiProvider (e.g. "WEALTH_API”) and slug (e.g. "TradeRepublic”).
Use the POST /v2/tppWebForms endpoint to create a new web-form to create a new web-form. At a minimum, the parameters bankSlug and multibankingProvider are required, leading to the following example request:
{ "bankSlug": "TradeRepublic", "multibankingProvider": "WEALTH_API" }
do NOT provide a bankConnectionId for an initial import
You may optionally provide the following parameters
1. bankConnectionInterfaceType - for finAPI banks only. This will only import the requested interface, e.g. “XS2A” for a PSD2 interface.
2. redirectUrl - this allows to pre-define a redirect URL to use after the web-form flow finished. You may also provide this URL as a frontend parameter.
3. displayMode - use this to toggle light or dark mode of the web-form. This only has an effect if styling is configured for your mandator in both, light and dark mode. Please contact info@wealthapi.eu for more information on web-form styling.
The response object will contain a startWebFormFlowUrl. Redirect the user to this URL to start the web-form flow. Upon successful completion of the web-form flow, the user will be redirected to the given redirect URL.

Use case: update a bank connection

Updating a bank connection works in a very similar way to importing. The main difference is that you need to support the ID of the existing bank connection when creating a web-form. The minimal request to the POST /v2/tppWebForms will thus looks like:

{
   "bankConnectionId": 12345,
   "multibankingProvider": "WEALTH_API"
}

The optional parameters bankConnectionInterfaceType, redirectUrl and displayMode are supported as well.

Dynamic redirect URLs controlled by the frontend client

To have more control over the redirect URL, your frontend-client may overwrite the settings given in the POST /v2/tppWebForms request. To do so, append the following parameters to the startWebFormUrl:

redirectUrl - this overwrites the redirect URL given in the create web-form request
closeUrl - use this URL when the user closes the web-form, typically indicating an aborted flow

Knowing what was created or updated

Once the user is redirected back to your application, we will automatically attach the following query parameters to the redirect URL:

bankConnectionId (multiple) the ID(s) of the bank connection(s), e.g. 12345
bankConnectionType: One of WEALTH_API or FIN_API, depending which multibanking provider was used

An example redirect URL will look like
https://your-domain/some-page?bankConnectionId=12345&bankConnectionType=FIN_API

You may then use these parameters to retrieve the created or updated accounts belonging to these bank connections using the /v1/accounts endpoint with query parameters bankConnectionId and bankConnectionType.

What happens if I request an action that would require a web-form flow?

As bank-import flows can be complex, we generally recommend to use the web-form for all import and update operations. It is however possible to perform an update without requiring the web form as long as

all credentials are stored
the bank will not require a 2FA
You may use the /v1/accounts/manualSyncRequired endpoint to check if we expect the bank to require 2FA or not.

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.

{
  "code":401,
  "message":"Nicht authorisiert",
  "errors":[
    {
      "code":"WEB_FORM_REQUIRED",
      "message":"Bitte verwenden Sie den TPP-Web-Form Prozess um Bankverbindungen zu importieren oder zu aktualisieren"
    }
  ]
}

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 as described before.

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.

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:

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.

Public Documentation

Using the wealthAPI PSD2 TPP web form