Implementation Guide

Getting Started

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

1. Create a Widget link for generating a Risk Report
2. Exchange an authorization code for an access token
3. 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"
}

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

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 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 Fetching your Risk Report section for a detailed overview. You will need the flow identifier to fetch the report. This ID was provided on flow initiation and in the callback with which you received the authorization code.