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

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

{
  "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

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)
• cancel: Boolean indicating if the user canceled the flow (only present when canceled)
• flow_id: Unique identifier for accessing flow-specific resources

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

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

3. Fetch the report

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