Enhance your experience!

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

...

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:

...

• 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.

...

{
  "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.

...

• 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:

...