Getting Started

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

Create a Widget Link for ongoing account access
Create an Access & Refresh Token from the Callback URL
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_id are the only mandatory parameters. All other parameters are optional, but some have an impact on the user flow.

The redirect_uri is the address to which the user should be returned in your application.

The user_id is a unique user identifier that allows multiple bank connections.

To shorten the flow for the end user 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 allows 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:

an Overlay/PopUp iframe
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 one-time access instead?
If you would like to initiate one-time account access, 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)
abort: Boolean indicating if the user canceled the flow
flow_id: Unique identifier for accessing flow-specific resources

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

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

Type	Lifetime
Authorization code	1 hour
Access token	1 hour
Refresh token	90 days

3. Fetch the financial data

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