(Remember: Web Form 2.0 has arrived!! We urge you to check out our documentation. It provides simpler integration and it is a UX-driven product. We are sure you will love it)
Who must use the finAPI PSD2 Web Form?
As a customer of finAPI 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 you do not have the permission / licence of 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 finAPI customers without Regulator PSD2 licence to fulfill this minimum requirement, we have created the finAPI PSD2 Web Form. Please note, that additional regulatory requirements may apply to your business and that finAPI cannot provide legal advice.
What is the finAPI PSD2 Web Form?
As certain finAPI Services require banking-related credentials, you may need to let the user enter credentials in finAPI's PSD2 web form instead of in your application. The PSD2 web form is a special endpoint hosted on the finAPI servers; Please note, that the finAPI PSD2 WebFrom will be opened in an external Webbrowser, opening in an iFrame is not allowed by the german regulator. The PSD2 Web Form will be part of the finAPI-PSD2-Licence-Product, which you have additionally to licence, if you don´t have a permission / licence of your national Financial Services Regulator.
It looks something like this (depending on the context in which you use the web form, it might have different appearances):
What are the use cases of the finAPI PSD2 Web Form?
Whether you need to use finAPI's web form (and if yes, to what extent), depends on your regulatory permissions, and what finAPI Services your application is using. Here is an overview of the different regulatory permissions and their implications on the usage of the finAPI web form:
|Your Regulatory permission||PSD2 Web Form required for|
|no regulatory permission||
|Account information (AIS/KID)||
|Payments + Account information||
no web form required for any finAPI service
finAPI manages the display of PSD2 Web Form automatically based on your regulatory permissions. Please contact our support team at email@example.com for the necessary configurations.
Please note: If you want to offer the possibility, to store the PIN in the finAPI-WebForm, you have to connect the editBankConnection-Service. With this Service the customer gets the possibility to change or delete the stored PIN.
How do I implement the Web Form Flow?
Please use this link to reach the new, improved Web Form 2.0. We strongly urge all our customers to use Web Form 2.0 for simpler integration and better UX. The below documentation is related to the existing (older) web form implementation.
Whenever your application is calling a finAPI service that requires your user's banking credentials, and you do not have the regulatory permission to handle those credentials itself, then the service will respond with HTTP code 451, and an error message which looks like this (example):
The 'message' field contains a value that is to be interpreted as a number. It depicts the ID of a web form instance that has been created by finAPI in the context of this service call. You will need this ID to query the result of the web form flow (more on that further below).
In addition to the JSON body, the response will also have included a Location header, which contains the URL to the web form to which you must direct your user. The general format is:
https://<finAPI Service domain>/webForm/<web form token>
Note that the included web form token is a one-time token, meaning that you will be able to open the URL just once. Further attempts will result in an error page. Also, note that the URL is valid for just 10 minutes. If a web form is opened but then not submitted within 10 minutes, the web form will expire. If a callbackUrl is set (see below) finAPI will trigger it as a result of the expiration.
You can open the URL for your user either as is, or optionally append the following additional parameters:
- a 'callbackUrl', to which finAPI will send a POST request when the web form flow is completed (user has entered all information that is needed and the service has executed). You can include encoded query parameters in the callbackUrl as well, they will be contained in the callback. Please note, the length of the callbackURL is limited to 1024 chars.
- a 'redirectUrl', to which the web form page will redirect the user after the web form flow is completed (and after the callback has been sent, if any was specified). You can include encoded query parameters in the redirectUrl as well, they will be contained in the redirect. If you don't pass a redirectUrl, the web form page will try to close itself on completion (if this fails, the user will be shown a message that he can close the page manually and return to your application).
For the above example, the complete URL to open in your user's browser (with an added callbackUrl and redirectUrl) would be:
After having opened the web form for your user, your application has to wait until the web form flow is completed and then get the result. This can be done in two ways, depending on whether you provided a callbackUrl or not:
A) In case you included a callbackUrl to the web form URL, your application will receive a POST request to the callbackUrl once the web form flow has completed, and can then get the result with the 'Get web form' REST service (see below).
B) In case you didn't include a callbackUrl in the web form, you'll have to poll the 'Get web form' service in regular interval to detect by yourself when the flow has completed. We recommend to poll the status every couple of seconds (at most once a second).
The endpoint to the 'Get web form' service is:
GET .../api/v1/webForms/<webFormId that was contained in the message field of the initial service response>
(For this example: GET ...api/v1/webForms/2934)
Querying a web form will give you the following result:
The 'token' is the generated, one-time web form token that finAPI included in the web form URL that was contained in the Location header of the initial service response.
The 'status' can be one of:
• "NOT_YET_OPENED" - means the web form URL has not been loaded yet (this should typically never occur, unless your application failed to load the web page for your user for some reason)
• "IN_PROGRESS" - means the web form page has been opened and the flow is in progress (web form is asking user for all the credentials that are required and executing the service)
• "COMPLETED" - means the web form has executed the service
• "ABORTED" - means that the user has aborted the web form flow (by clicking an abort button at some step during the process)
The 'serviceResponseCode' and 'serviceResponseBody' fields will be set as soon as the status is COMPLETED or ABORTED. They will contain the HTTP response code and the response body of the original REST service call, i.e. the one that returned with 451 in your initial call. The response body will be a stringified JSON object. For the exact contents, please refer to the documentation about the possible responses (including error responses) of the respective service.
Note that the 'Get web form' serivce is a user-related service, meaning that you have to pass an Authorization header with the user's access token, just as with any other of finAPI's user-related REST services. You might want to think about adding 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).
Here is a summarizing graphic of finAPI's web form flow:
Implications of PSD2 on finAPI's automatic batch update
In case that you do not have an AIS/KID license, finAPI's automatic batch updates for your users' bank connections might fail to run. This is the case when a user has not accepted the latest terms and conditions of finAPI*. When an automatic update is set up for a user, but he has not accepted the latest terms and conditions, then the update will be skipped for this user. It is recommended to set up Push Notifications for your users so that they will be informed about this and can accept the new terms and conditions, thus re-enabling the automatic updates. For more details on how to set up and handle such Push Notifications, please refer to this article:
*Accepting the terms and conditions is done by the user via the Web Form. When a user needs to accept new terms and contiditions, he should perform a manual update of his bank connection(s) via the web form.
How can I test the Web Form Flow using Swagger?
As of now, Swagger will not automatically open the web form for you. You'll have to enter the web form URL from the Location header into a separate tab of your browser yourself, and also have to call the GET /webForms service for yourself once the web form has triggered the callback and/or redirect.