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

Embed the Widget inside an <iframe> in your page. Instead of a URL redirect, the Widget communicates with your parent page via the browser's postMessage API.

Best for: Web applications where you want to keep the user on your page during the flow.

⚠️
Not supported in Internet Explorer 11
Due to IE11 limitations, iframe integration is not supported. IE11 users must use the redirect flow.

⚠️
Not recommended for native mobile apps
In WebViews, the Widget may not be able to complete redirect-based SCA challenges. Use the redirect flow for native mobile apps.

Implementation:

<iframe
  src="{widget_location}"
  id="nrich-widget"
  style="width: 100%; height: 600px; border: none;"
></iframe>

Listen for the CALLBACK event:

window.addEventListener('message', function(event) {
  // Filter to Widget events only
  if (event.data.type !== 'CALLBACK') return;

  const { code, success, abort, flow_id, state } = event.data.query;

  if (success && code) {
    // Exchange code for access token
    exchangeCode(code);
  } else if (abort) {
    // User cancelled - show dismissal UI
    showCancelled();
  } else {
    // Flow failed - show error UI
    showError();
  }
});

postMessage payload structure:

{
  "type": "CALLBACK",
  "link": "https://my-app.example.com/callback?flow_id=...&code=...&success=true&abort=false",
  "query": {
    "flow_id": "3ca31c37-986a-454e-ad64-8e97143c86bc",
    "code": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "success": true,
    "abort": false,
    "state": "session_42"
  }
}

📘
One-way communication
The Widget does not process incoming postMessage calls. Communication is Widget → your page only.

Development whitelist:

During development, the following origins are whitelisted for iframe integration:

http://127.0.0.1 and https://127.0.0.1 (all ports)
http://localhost and https://localhost (all ports)

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.