Implementation Guide

Getting Started

With just three API calls, you can access the verification report for your end user:

Create a Widget link for generating an Income Report
Exchange an authorization code for an access token
Fetch the verification report

1. Flow initiation

{
  "redirect_uri": "https://my-app.example.com/callback",
  "accounts": [{
    "id": "DE82900948150000002881", 
    "currency": "EUR"
  }],
  "account_types": [
    "Giro account"
  ],
  "reporting_period": 12,
  "allow_multi_selection": true,
	"language": "de",
}

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

The redirect_uri is the address to which the user should be returned in your application.

To shorten the flow for your users and achieve maximum conversion, we highly recommend using the accounts parameter. If the IBAN or other information about the user is known, such as an account number or PAN, it can be passed 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 reporting_period defines the length of the retrospective transaction period in months that will be fetched. For a reliable result, we suggest setting this to a minimum of 6. The default value is 12.

{
  "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 WidgetLink response. This can be achieved by using:

an Overlay/PopUp iframe
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. We will then fetch the financial data associated with the user's selection.

Read more about the Widget UI integration here

2. Exchange authorization code

After successful completion of the flow, users are redirected to your specified redirect_uri with the following query parameters:

state: Your provided identifier to maintain session state and identify the returning user
success: Boolean indicating successful flow completion
code: Authorization code valid for 1 hour, used to obtain an access token (only present on successful completion)
abort: Boolean indicating if the user canceled the flow
flow_id: Unique identifier for accessing flow-specific resources

https://example.com/callback?code=eyJhbGciO...&state=7fe78733&success=true&flow_id=3ca31c37-...&abort=false

Exchanging the Code for Tokens

Request an access token by calling POST /auth/token with the following payload

// Request
{
  "grant_type": "authorization_code",
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
  "redirect_uri": "https://my-app.example.com/callback"
}

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

Using and Maintaining Tokens

Include the access_token in the Authorization header for all API requests
For ongoing access, store the refresh_token securely
Each refresh token usage returns a new refresh token that must replace the previous one
Access is revoked if:
- No user activity occurs within 90 days
- The refresh token isn't regularly renewed

📘
Token lengths
Token lengths can vary. Avoid fixed-size database fields for storing tokens. If a size limit is required, allocate at least 2048 bytes per token field.

Token lifetimes

Type	Lifetime
Authorization code	1 hour
Access token	1 hour
Refresh token	90 days

3. Fetch the report

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