Implementation Guide

Getting Started

With just three API calls you will get access to the Risk Report for your end-user:

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

1. Flow initiation

Onetime Risk Report

The one-time Risk Report relates to the One-time Account Access and should be used if you want to perform a single snapshot risk review of a user.

POST /onetime/risk-report

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

Ongoing Risk Report

The ongoing Risk Report relates to the Ongoing Account Access and should be used if you want to perform an ongoing analysis of the risk indicators for a specific user.

POST /ongoing/risk-report

{
  "account_types": [
    "Giro account"
  ],
  "allow_multi_selection": true,
  "reporting_period": 12,
  "save_secrets": false,
  "redirect_uri": "https://my-app.example.com/callback",
  "language": "en",
  "accounts": [{
    "id": "DE93300308800013441006"
  }],
  "name": "Max Mustermann",
  "user_id": "[email protected]"
}

The redirect_uri and user_id (for an Ongoing Request) are the only mandatory parameters. All other parameters are optional, but some will have an impact on the user flow.

The redirect_uri is the address of the location to which the user should be returned back to your application.

The user_id is the unique user identifier, which will allow multiple bank connections.

The name is the input parameter that will be matched against the account holder's name to provide the account verification result. No account verification will be performed in case no value has been provided.

The reporting_period defines the length of the retrospective transaction months that will be fetched. For a reliable result, we suggest setting this to a minimum of 6. The default value is 12.

The accounts list preselects the bank accounts and the user will not see the account selection screen. For an account you can also specify the currency, but it's optional - as you can see it was present in previous example and skipped here.

Redirect the user

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

The response of the flow initiation contains exactly two fields:

location: Forward the user to this URL to actually start the flow on the user's side. You can achieve this by either redirecting him in the same or a new window or by using an overlay/popup iframe. We strongly advice you to redirect your user to the returned URL. See our widget integration guide for more details.
id: Make sure to store this value on your end to be able to fetch the report after the user successfully completed the flow. It will additionally come in handy if you are reaching out to our support and having questions related to a specific flow. Make sure to provide this value in your communication with us.

Optimize the flow

To shorten the flow for your users and achieve maximum conversion, we highly recommend using the accounts parameter in case the IBAN or other information (e.g. Account Number or PAN) of the users are known. With this information the UI will skip the bank selection and the users will directly be prompted to authorize with their bank. Additionally, if you want to allow the user to connect only certain account types, such as Giro accounts, the account_types parameter can be used. This will skip the account type selection screen in the Widget UI.

{
  "account_types": [
    "Giro account"
  ],
  "accounts": [{"id": "DE93300308800013441006"}],
}

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 the redirect_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

POST /auth/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 Fetching your Risk Report section for a detailed overview