Enhance your experience!

Use callback URLs, avoid polling!

...

After opening the Web Form for your user, your application has to wait until the Web Form flow is completed and then get the result. In case you included callback.finalised in the API call, your application will receive a POST request to the callbacks.finalised once the Web Form flow has been completed. You can then get more details on the result with the “Get a web form” REST service.

...

Bank connection update

For the bank connection update flow, there is an additional callback option, callbacks.webFormRequired. This callback gets triggered if we are unable to download the account data without end-user intervention (e.g. second-factor authentication gets triggered). Use this notification to forward the end-user to the Web Form workflow.

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 minimal information. Use the “Get a web form”/”Get a task” call to fetch additional information about the executed flow.

• bankConnectionId, paymentId or standingOrderId - when the Web Form is completed successfully, can be used in Access to get more bank connection or payment data.

• (optionally) 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 carries -

...

bankConnectionId or paymentId - when the Web Form is 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!

...