Implementation Guide

Getting Started

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 users 

  1. Create a Widget link for one-time account information access
  2. Exchange an authorization code for an access token
  3. Fetching the financial data 

Step 1: Create Widget Link

Example:

POST /onetime/access

{
  "redirect_uri": "https://my-app.example.com/callback",
  "language": "de",
  "accounts": [],
  "sync_period": 90
}

Please note that the redirect_uri is the only mandatory parameter as it will lead the user back to your application. All other parameters are optional, but some will have a direct effect on the user flow.

To shorten the flow for your users 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 and they will be prompted to directly authorize with their bank.

The sync_period defines the number of days of transaction history requested from the financial institution. The default value is set to 90 but can be set higher depending on the use case.

Example response:

{
  "location": "https://finx.finleap.cloud/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoYWhhIjoiaSBtYWRlIHlvdSBsb29rIn0.jk1WqP6S28bNuP5MwwlZHR_5GlksWsEZPMztWUAIiJY",
  "id": "3ca31c37-986a-454e-ad64-8e97143c86bc"
}

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

  1. an overlay/popup iframe
  2. a redirect in the same or a new window

Step 2:  Exchange an authorization code for an access token

Once the user has completed the widget flow they will be successfully redirected to your application. The callback URL has the following structure:

<redirect_uri>?state=<state>&code=<code>&success=true

It contains an authorization code (code) with a lifetime of 5 minutes and can be exchanged for an access 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 minutes.

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

The access token shall be used to fetch financial data on behalf of the user.

Step 3: Fetch the user's Financial Data

Please view the Fetching Account & Transaction Data section for a detailed overview.