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

🫰

Looking for onetime access instead?

In case you would like to initiate an ongoing account access please review the Financial Data Implementation Guide

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

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