Getting Started

Customers who want to make use of the finX API for Multibanking are just three API calls away from getting access to the financial data of their end-users 

1. Create a Widget Link for ongoing account access
2. Create an Access & Refresh Token from the Callback URL
3. Fetching the financial data 

1. Flow initiation

Create a WidgetLink for authentication, declaration of intent and flow configuration

POST /ongoing/access

{
  "state": "b0bc2e10-838f-4955-b8a6-733666049655",
  "redirect_uri": "https://my-app.example.com/callback",
  "tracking_id": "string",
  "language": "de",
  "provider_id": "74bab9d2-9f60-4ab1-be63-706e67b99f58",
  "accounts": [],
  "account_types": [],
  "allow_multi_selection": true,
  "sync_period": 90,
  "save_secrets": false,
  "user_id": "[email protected]"
}

The redirect_uri and user_idare the only mandatory parameters. All other parameters are optional, but some will have an impact on the user flow.

The redirect_uri is used to 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.

To shorten the flow for the end-user and achieve maximum conversion, we highly recommend to use the accounts parameter. In case the IBAN or other information (e.g. Account Number or PAN) of the users are known they can be passed on as an account_id.

"accounts": [
	{"id": "DE82900948150000002881"}
]

To optimize conversion, you might consider asking the user for their account details before initiating the widget. This will allow the user to "skip" the bank selection screen.

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. finX will then fetch the financial data associated with the user's selection.

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:

1. 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.
2. success: Indicator whether or not the flow was successfully completed by the user.
3. 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.
4. 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

📘

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 financial data

Please view the Fetching Account & Transaction Data section for a detailed overview