Implementation Guide

Getting Started

Customers who want to use the nrich API for Financial Data are just three API calls away from accessing their users' financial data.

1. Create a Widget link for one-time account information access
2. Exchange an authorization code for an access token
3. Fetch the financial data

1. Flow initiation

POST /onetime/access

{
  "redirect_uri": "https://my-app.example.com/callback",
  "language": "de",
  "accounts": [],
  "sync_period": 90
}

Please note that the redirect_uri is the only mandatory parameter, as it leads the user back to your application. All other parameters are optional, but some have a direct effect on the user flow.

To shorten the flow for your users and achieve maximum conversion, we highly recommend using the accounts parameter. If the IBAN or other information about the user is known, such as an account number or PAN, it can be passed 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 and they will be prompted to directly authorize with their bank.

The sync_period defines the number of days of transaction history requested from the financial institution. The default value is set to 90 but can be set higher depending on the use case.

{
  "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

🫰

Looking for ongoing access instead?

If you would like to initiate ongoing account access, review the Multibanking Implementation Guide.

2. Exchange authorization code

https://example.com/callback?code=eyJhbGciO...&state=7fe78733&success=true&flow_id=3ca31c37-...&abort=false

// 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..."
}

3. Fetch financial data

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