Implementation Guide
Getting Started
With just three API calls you will get access to the verification report for your end-user:
- Create a Widget link for one-time account information access
- Exchange an authorization code for an access token
- 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 thename
are 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 cande
for German,en
for English andes
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 optionsACCOUNTS
andTRANSACTIONS
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 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.
2. Exchange authorization code
After a user successfully went through the flow, they are redirected to the redirect_uri
provided in your initial request to create the Widget link. The following query-parameters will be automatically added by us:
state
: The value provided by you during flow initiation. You can use this to identify which user is now being redirected to theredirect_uri
and reinstantiate the state of your website accordingly.success
: Indicator whether or not the flow was successfully completed by the user.code
: The authorization code to be exchanged for an access token to gain access to the financial data of the user. It is only returned in case the user successfully went through the flow and is valid for one hour.cancel
: Indicator whether or not the flow was canceled by the user. Only present in case the user actually canceled the flow and not in other error cases.
https://example.com/callback?code=eyJhbGciO...&state=7fe78733&success=true
Requesting an access token
{
"grant_type": "authorization_code",
"code": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
"redirect_uri": "https://my-app.example.com/callback"
}
{
"access_token": "AoFmNJLDTW8jQtGSJ1iZeeoLiwNZ2ihz3iiCHGpuvE439nppuY...",
"expires_in": 3600,
"scope": "accounts=ro balance=ro transactions=ro offline",
"token_type": "Bearer",
"refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}
You have to provide the returned access_token
in the HTTP Authorization
header of subsequent API requests. In case of an ongoing use-case, you additionally need to store the returned refresh_token
on your end to permanently keep access to your enduser's data. Whenever you use an existing refresh token you will automatically get a new one in the response. Your application has update it's existing one in your storage backend to ensure the token is valid and not expired. If no user activity is present within 90 days, or the refresh token is not replaced with a new one, your access will be lost.
Token lifetimes
Type | Lifetime |
---|---|
Authorization code | 1 hour |
Access token | 1 hour |
Refresh token | 90 days |
The actual length in bytes of all tokens (access and refresh tokens as well as authorization codes) can vary. Therefore it is highly advised to not limit the size of the database field in your storage backend. If you have to specify a size for the corresponding database field a choice of at least 2048 bytes is highly recommended.
3. Fetch the report
Please view the Getting your Verification Report section for a detailed overview.
Updated 2 months ago