Implementation Guide

Getting Started

With just three API calls you will get access to the verification report for your end-user:

  1. Create a Widget link for generating an Income Report
  2. Exchange an authorization code for an access token
  3. Fetching the verification report

Step 1: Create the Widget Link

Example request body:

POST /onetime/income-report

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

The redirect_uri is the only mandatory parameter. 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.

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.

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 and refresh token

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

  1. state: The state that was provided when creating the Widget link.
  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 minutes 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: Fetch the user's Disposable Income Report

Please view the Fetching your Verification Report section for a detailed overview