Enhance your experience!

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 in the API call you have provided a callbacks.finalised or not:

...

In case you included a callbacks.finalised in the API call, your application will receive a POST request to the callbacks.finalised once the Web Form flow has completed. You can then get more details on the result with the “Get a web form” REST service (see below)

...

All “Payment Initiation Services” and “Account Information Services” endpoints provide callback parameters to enhance your integration and avoid polling.

The callbacks are meant to only notify you that the flow was finalised on our side. As such, the callbacks contain only minimal information. Use the “Get a web form”/”Get a task” call to fetch additional information about the executed flow. The payload will contain:

• abankConnectionId, paymentId or standingOrderId - if the Web Form is completed successfully. These ids can be used in Access to get more data on the bank connection or payment.

• (optionally) an errorCode - when the Web Form is completed with the status “COMPLETED_WITH_ERROR”. Use the data in this field to determine how you would like to navigate the end-user within your application for the next steps.

...

...

...

Read the API response carefully. The payload could carry -

...

bankConnectionId or paymentId - when the Web Form completed successfully. Use this in Access to get more data about the bank connection or the payment.

...

Payment Initiation Services (PIS)

To register for a callback for any of the PIS endpoints, you should pass the URL you want to receive the POST callback as value for the callbacks.finalised parameter. If a callback is registered, once a web form is finalised (successfully or not), a POST request will be sent with the body:

{
  "webFormId": "31c508d8-51da-11eb-ae93-0242ac130002",
  "status": "COMPLETED"
}

The possible values for the status are:

• COMPLETED -the web form has been successfully completed (final status);

• COMPLETED_WITH_ERROR - the web form has been completed with an error (final status);

• EXPIRED - the web form has expired (final status); This status means that either the expiresAthas passed, or the end-user closed the web form and we finalized the flow in the background;

• ABORTED - the web form has been cancelled by the end-user (final status).

Account Information Services (AIS)

There are only 2 AIS endpoints: “Import a bank connection” and “Update a bank connection”. The “Import a bank connection” endpoint has the same logic and behaviour as any of the PIS endpoints, providing the callbacks.finalised parameter.

Update a bank connection

For the “Update a bank connection” endpoint, we provide 2 callback options, which are triggered based on the bank connection status, stored consent, and whether any end-user interaction is required to finalise the operation. The 2 callback parameters are callbacks.finalised, which has the same meaning as for “Import a bank connection” endpoint, and callbacks.webFormRequired, which is triggered when a bank connection update task requires end-user interaction and a web form is created to guide the end-user through said interaction.

Furthermore, in the case of “Update a bank connection”, the callbacks POST request body is different:

{
  "taskId": "31c508d8-51da-11eb-ae93-0242ac130002",
  "status": "COMPLETED",
  "webForm": {
    "id": "946db09e-5bfc-11eb-ae93-0242ac130002",
    "url": "https://webform.finapi.io/wf/946db09e-5bfc-11eb-ae93-0242ac130002",
    "status": "COMPLETED"
  }
}

Web Form Required

In the case of callbacks.webFormRequired, the body will always contain status: WEB_FORM_REQUIRED, with the sub-object webForm providing the URL to which you need to redirect the user, and status: NOT_YET_OPENED.

{
  "taskId": "31c508d8-51da-11eb-ae93-0242ac130002",
  "status": "WEB_FORM_REQUIRED",
  "webForm": {
    "id": "946db09e-5bfc-11eb-ae93-0242ac130002",
    "url": "https://webform.finapi.io/wf/946db09e-5bfc-11eb-ae93-0242ac130002",
    "status": "NOT_YET_OPENED"
  }
}

Finalised

Will be called when the task can be finalised in the background, without any end-user interaction (status COMPLETED or COMPLETED_WITH_ERROR), or when the associated web form is finalised.

The task status can have the values:

• COMPLETED - the task has been successfully completed (final status);

• COMPLETED_WITH_ERROR - the task has been completed with an error (final status).

• WEB_FORM_REQUIRED - the task requires a web form to continue the flow with end-user involvement (final status). In this case, the web form details will also be included in the callback, and the webForm.status can have one of the values:

  • COMPLETED -the web form has been successfully completed (final status);

  • COMPLETED_WITH_ERROR - the web form has been completed with an error (final status);

  • EXPIRED - the web form has expired (final status); This status means that either the expiresAthas passed, or the end-user closed the web form and we finalized the flow in the background;

  • ABORTED - the web form has been cancelled by the end-user (final status).

Enhance end-user experience!

You can forward the URL to the user as it is. Or, you can optionally append the following parameters:

• redirectUrl, to which the Web Form will redirect the user after the Web Form flow is completed successfully. 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 the Web Form is unable to close by itself, the user will be shown a message that he can close the page manually and return to your application).

• errorRedirectUrl, same philosophy as redirectUrl except this URL will redirect the user when the Web Form runs into an unexpected error. Please remember! users Users are NOT automatically redirected, unlike redirectUrl. This was done intentionally to give the user enough time to read the error message, decide and gather data they want to report, etc. , Nevertheless, you can build a workflow for error conditions when the user comes back to this URL. If you don't pass a an errorRedirectUrl, the Web Form will simply attempt to close the page.

• abortRedirectUrl, same philosophy as redirectUrl except this URL will redirect the user when the Web Form is aborted by the user.

• customerSupportUrl, to which the Web Form will display a link to in case you want to offer the possibility for end-users to reach your customer support. We will display the URL in case the user cancels the workflow OR if there is an unexpected error. You can include encoded query parameters in the customerSupportUrl as well, they will be contained in the redirect. If you don't pass a customerSupportUrl, 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 redirectUrl and customerSupportUrl) would be:

https://live.finapi.io/webForm/nEvozFaPhCXw8ZnnRBb2KJGANW6y9RjZgQtX6YRAhB_Li7TzO19jTh0wtBg9AbvblAMnJFp7DS1C0zzj746U4B7GUj4LUIyt9ZR9Sn2UoLzg5SYaEx9Ps6ax_6ImXTOB
?redirectUrl=https%3A%2F%2Fyourapphttps%3A%2F%2Fyourapp.net%2Fwebnet%2Fweb-form-redirect%3FredirectParam%3Dfoobar&customerSupportUrl=https%3A%2F%2Fyourapphttps%3A%2F%2Fyourapp.net%2Fwebnet%2Fweb-form-redirect%3FsupportParam%3Dfoobar

Payment Initiation Services (Standalone Payments and Payment with account ID)

1. API parameter purpose - Some banks are unable to process payments without the field. It would be best to provide the purpose to ensure better success rates with payment initiation

2. Supported character set - Depending on the bank’s technology stack and other requirements, special characters in the input might lead to failed payments. We strongly urge customers to stick to the below character set. This impacts the API parameters purpose, endToEndId, recipient.name

a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . , ' +
Space

Some banks support umlauts (ä, Ä, ö, Ö, ü, Ü) while some don't. The simplest solution to ensure high success rates would be to substitute umlauts with ae, AE, oe, OE, ue, UE respectively.

Account Information Services

...

API parameter accountTypes - We urge customers to utilize the parameter and specify only those account types which apply to their business case. When you provide this parameter, the API will attempt to import only those accounts types and stop once we have covered every account type that is requested. (BAUSPAREN┃CHECKING┃CREDIT_CARD┃LOAN┃MEMBERSHIP┃SAVINGS┃SECURITY)

1. We use different protocols (interfaces) for different account types. The end user will be asked if they would like to loop over the entire workflow until we get all requested account types. To optimize the experience for the end user, provide only those account types that apply to your use case.

“Update a bank connection” endpoint - As mentioned in the API documentation, the “Update a bank connection” endpoint serves multiple purposes. Hence, configure the endpoint with the correct parameters according to your need.

...

API parameter importNewAccounts - Only when your end users would like to ADD new accounts to an existing bank connection, use the parameter, importNewAccounts for updates. To ensure the best user experience, you can use the API parameter accountTypes along with it, just like you might do with the “Import a bank connection” endpoint. Link this API call (with the specific parameter) to the trigger on your website or app, where you allow users to add new accounts to their portfolio overview

...

API parameter editSavedSettings - If you want to force the Web Form to go through the entire flow, in order to allow the end user to change the saved settings, use this parameter. For example, for end users who might have changed their online banking credentials, and would like to update the new credentials in our database as well.

...