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 one-time account information access
  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/account-verification

{
  "redirect_uri": "https://my-app.example.com/callback",
  "language": "de",
  "name": "Max Mustermann",
  "account": "DE93300308800013441006",
  "readout": []
}

Please note thatredirect_uri and thenameare mandatory parameters.

  • The redirect_uri is the address of the location to which the user should be returned back to your application.
  • The name is the alleged name of the account holder respectively the full name of your end-user how they registered themselves with your application.

All other parameters are optional, but some will have a direct effect on the user flow, so you might want to consider to also make use of them:

  • language defines the language used in the Widget. You can de for German, en for English and es for Spanish.
  • account is the IBAN of the bank account that should be used to verify the end-user. If the value is provided, the bank of the end-user is already preselected in the Widget, so that the user only needs to enter the bank credentials and authorize the account access with Strong Customer Authentication.
  • readout with the options ACCOUNTS and TRANSACTIONS allows you to also fetch the account data and the transaction data of your end-user.

Example response body:

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

Forward the user to the location provided in the API response.

The Widget UI will guide your end-user through the process of connecting their bank account. The user can either interactively select an account in the UI from the list of available accounts or, if the account-field is provided, the selection of the bank and respective account for the verification is done automatically by the Widget. finX will fetch the user's account data and look for an account-holder name.

Step 2:  Exchange an authorization code for an access token

Once the user has completed the widget flow, they will be redirected back to your application, which is addressed by the redirect_uri you provided in Step 1. Now you need to exchange the authorization code for an access token in order to be able to authenticate when fetching the account verification result in the upcoming step.

You receive as part of the redirect_uri now further query parameters:

General structure:

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

  • code is the authorization code, which has a lifetime of 5 minutes and shall be exchanged for an access_token

You find further information about the other query parameters here

Example request body for the token exchange:

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.

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

The access token authorizes your application to request the verification report in the next step.

Step 3:  Fetch the verification report

Please view the Getting your Verification Report section for a detailed overview.