Implementation Guide

Prerequisites

API Access & Authentication

The finX API is a restful API, that is accessed using HTTP Basic Auth with a clientID as a username and a Client secret as a password. Therefore each customer receives a Client ID and Client Secret from Qwist to access the finX API, which has a specific set of Scopes attached to it. Scopes define the usage rights of each Client ID on the finX platform.

Widget Integration

Before continuing with the implementation guide, please view our Widget Integration best practices.


Implementation Guide

Customers who want to make use of the finX API for Financial Data are just three API calls away from getting access to the financial data of their end-users 

  1. Create a Widget Link for ongoing account access
  2. Create an Access & Refresh Token from the Callback URL
  3. Get a new access token with a refresh token
  4. Fetching the financial data 
  5. Manual Synchronizations

Create a WidgetLink for authentication, declaration of intent and flow configuration

Example:

POST/ongoing/access

{
  "state": "b0bc2e10-838f-4955-b8a6-733666049655",
  "redirect_uri": "https://my-app.example.com/callback",
  "tracking_id": "string",
  "language": "de",
  "provider_id": "74bab9d2-9f60-4ab1-be63-706e67b99f58",
  "accounts": [],
  "account_types": [],
  "allow_multi_selection": true,
  "sync_period": 90,
  "save_secrets": false,
  "user_id": "[email protected]"
}

The redirect_uri and user_idare the only mandatory parameters. All other parameters are optional, but some will have an impact on the user flow.

The redirect_uri is the address of the location to which the user should be returned back to your application.

The user_id is the unique user identifier, which will allow multiple bank connections.

To shorten the flow for the end-user and achieve maximum conversion, we highly recommend to use the accounts parameter. In case the IBAN or other information (e.g. Account Number or PAN) of the users are known they can be passed on as an account_id.

"accounts": [
{"id": "DE82900948150000002881"}
]

To optimize conversion, you might consider asking the user for their account details before initiating the widget. This will allow the user to "skip" the bank selection screen.

Forward the user to the location provided in the WidgetLink response. This can be achieved by using:

  1. an Overlay/PopUp iframe
  2. a redirect in the same or a new window

The Widget UI will guide the user through the process of selecting the financial sources they want to provide access to. finX will then fetch the financial data associated with the user's selection.

Step 2:  Exchange an authorization code for an access and refresh token

The Widget UI then redirects the user to the redirect_uri provided in the WidgetLink with the following query-parameters

  1. state: The state that was provided when creating the WidgetLink.
  2. success: Indicator whether or not an initiated process was completed successfully.
  3. code: The Authorization Code to be processed by the partner. code is only returned on successful flow.

Example:

<https://example.com/callback?code=Oafd13...&state=a81132cf&success=true>

The authorization code (code), which has a lifetime of 5 minutes and should then be exchanged for an access and refresh token using:

POST/auth/token

{
  "grant_type": "authorization_code",
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YXRjaCI6Imh0dHBzOi8veW91dHUuYmUvZU1KazR5OU5HdkUifQ.SU9j32eCgtVLQo6gKiFIxHHq4LumpAKggIDfg9j97ZQ",
  "redirect_uri": "https://my-app.example.com/callback"
}

in return, you will receive the access token, which has a lifetime of 60 min and a refresh token.

{
  "access_token": "AoFmNJLDTW8jQtGSJ1iZeeoLiwNZ2ihz3iiCHGpuvE439nppuY",
  "expires_in": 3600,
  "scope": "accounts=ro balance=ro transactions=ro offline",
  "token_type": "Bearer",
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}

Step 3: Creating a new Access Token from a Refresh Token

The refresh_token allows you to request additional access tokens (e.g. after the access token has expired). The Refresh tokens are only valid for a maximum of 90 days.

POST/auth/token

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YXRjaCI6Imh0dHBzOi8veW91dHUuYmUvZU1KazR5OU5HdkUifQ.SU9j32eCgtVLQo6gKiFIxHHq4LumpAKggIDfg9j97ZQ",
  "scope": "accounts=ro balance=ro transactions=ro offline"
}

When issuing a refresh request the response may contain a new refresh token so that your application has to discard the old token and replace it with the new refresh token. This ensures that the lifetime of the refresh token is always preserved. If no user activity is present within 90 days, or the refresh token is not replaced with the new one, the access will be lost.

📘

The actual length in bytes of all tokens (access and refresh tokens as well as authorization codes) can vary. Therefore it is highly advised to not limit the size of the database field in your storage backend. If you have to specify a size for the corresponding database field a choice of at least 2048 bytes is highly recommended.

The access token will then be used to fetch and process the financial data on behalf of the user.

Best Practices

/

Flow Diagram