Implementation Guide

Getting Started

With just three API calls, you can access 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. Fetch the verification report

1. Flow initiation

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 that redirect_uri and name are mandatory parameters.

• The redirect_uri is the address to which the user should be returned in your application.
• The name is the claimed name of the account holder, or the full name your end user used when registering in your application.

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

• language defines the language used in the Widget. You can use 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.

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

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. 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

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

// 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..."
}

3. Fetch the report

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