Widget Integration

Overview

The Widget is a white-label UI that guides users through bank authentication and account authorisation. It handles bank selection, credential entry, and Strong Customer Authentication - so you don't have to.

Most nrich products require only three API calls: create a Widget link → user completes Widget → exchange the code. This guide covers how to embed the Widget in your application.

📘
Languages
The Widget defaults to German (de). Set the display language explicitly using the language parameter when creating the Widget link. Available: de, en, es, fr, ar.

Two integration modes

The simplest integration. You redirect the user to the Widget URL. After completing the flow, the Widget redirects the user back to your redirect_uri with query parameters.

Best for: Server-side applications, mobile apps, any scenario where you can redirect the browser.

Flow:

Call a flow initiation endpoint (e.g. POST /onetime/access) to get the Widget URL.
Redirect the user to location from the response.
The user completes bank selection and authentication in the Widget.
The Widget redirects back to your redirect_uri with the result as query parameters.

Callback parameters:

Parameter	Description
`flow_id`	Matches the `id` from the Widget link creation response.
`code`	Authorization code (1-hour lifetime). Only present on success.
`success`	`true` if the user completed the flow successfully.
`abort`	`true` if the user cancelled.
`state`	Your original `state` value, echoed back.

Successful callback:

https://my-app.example.com/callback
  ?flow_id=3ca31c37-986a-454e-ad64-8e97143c86bc
  &code=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  &success=true
  &abort=false
  &state=session_42

Cancelled callback:

https://my-app.example.com/callback
  ?flow_id=3ca31c37-986a-454e-ad64-8e97143c86bc
  &success=false
  &abort=true
  &state=session_42

Error callback (not cancelled, but failed):

https://my-app.example.com/callback
  ?flow_id=3ca31c37-986a-454e-ad64-8e97143c86bc
  &success=false
  &abort=false
  &state=session_42

Speeding up the flow

The Widget has three screens by default: bank search → account type selection → authentication. You can skip screens by pre-filling information in the flow initiation request.

Parameter	What it skips	When to use
`accounts: [{id: "DE89..."}]`	Bank search (resolves bank from IBAN) + account selection	When you know the user's IBAN
`account_types: ["Giro account"]`	Account type selection	When you only want a specific account type
`provider_id`	Bank search entirely	When you want a specific bank from the catalog

📘
Maximum conversion tip
Passing accounts with the user's IBAN is the single most impactful optimisation. The user goes directly from opening the Widget to authenticating with their bank - no search, no selection. Ask for the IBAN before initiating the Widget when possible.

Combining products in one flow

The artifacts parameter lets you request multiple outputs in a single Widget flow. Instead of creating separate flows for account data + income report, you can combine them:

{
  "redirect_uri": "https://my-app.example.com/callback",
  "accounts": [{ "id": "DE89370400440532013000" }],
  "artifacts": [
    { "type": "income_report" }
  ]
}

This is available on /onetime/access and /ongoing/access. The user authenticates once, and you get both the account/transaction data and the requested report.

Browser support

Browser	Redirect flow	iframe flow
Chrome	✓	✓
Firefox	✓	✓
Edge	✓	✓
Safari	✓	✓
Internet Explorer 11	✓	✗

Error handling in the Widget

The Widget communicates outcome through the success and abort flags:

success	abort	Meaning
`true`	`false`	Flow completed successfully. `code` is present.
`false`	`true`	User cancelled the flow.
`false`	`false`	Flow failed (bank error, technical issue, etc.).

Always handle all three cases in your callback handler.