HomeGuidesAPI Reference
Log In
Guides

Widget Integration

Suggest Edits

Overview

The Widget is a white-label user interface designed to simplify the integration of the nrich API.
It guides users through the entire process of connecting bank accounts or initiating payments,
providing seamless access to the financial data, enrichments and powerful reports that are important to your business. By using the Widget, you can reduce the integration complexity in most cases to just three API calls.

Internationalization

The Widget provides multi-language support, with German (de) as the default locale. The Widget does not automatically detect the user's language preferences from the Accept-Language header. To set the display language, you must explicitly specify the desired locale using the language parameter when initiating the flow.

Flow Initiation

The Widget flow can be initiated through several purpose-specific endpoints. Each endpoint is designed for a distinct use case, such as one-time account access, payment initiation or risk report creation. Please refer to the corresponding guides and the API reference for details.

All flow initiation endpoints return a standardized response:

{
  "location": "https://ui-next.regshield-p.qwist.cloud/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoYWhhIjoiaSBtYWRlIHlvdSBsb29rIn0.jk1WqP6S28bNuP5MwwlZHR_5GlksWsEZPMztWUAIiJY",
  "id": "3ca31c37-986a-454e-ad64-8e97143c86bc"
}
  • location: The URL endpoint that launches the Widget interface. Your application must direct users to this URL to start the flow.
  • id: A unique identifier for the flow session. This ID is returned in callbacks when the flow completes, allowing you to track user sessions.

Browser Support

The Widget is explicitly compatible with:

  • Google Chrome
  • Mozilla Firefox
  • Microsoft Edge
  • Safari
  • Internet Explorer 11

🚧

Due to technical limitations in Internet Explorer 11, iframe integration is not supported. Applications requiring IE11 compatibility must integrate the Widget at the top level using the URL provided by the initiation service.

Native / Mobile App Integration

When integrating the Widget in a native app, we strongly recommend launching it at the top level (browser or WebView) using the location URL received from the flow initiation. Avoid embedding the Widget in an iframe.

Note: In environments where programmatic tab opening is restricted (such as WebViews), iframe integration may prevent the Widget from completing redirect challenges successfully.

iframe Integration

The Widget can be integrated within an iframe using the same flow as top-level integration, with one key difference: instead of receiving a URL callback, the Widget communicates with the parent window via the postMessage API.

Basic Implementation

Use the following code snippet to integrate the Widget inside an iframe in your application

  <iframe src="{WidgetLink.location}"></iframe>

Message Handling

Register an event listener to receive a message when the flow is finished. The event.data will include the fields as shown below.

  window.addEventListener('message', receiveMessage, false);

  /**
   * postMessage listner
   *
   * @param  {event}  event
   * @param  {Object} event.data               payload of the `postMessage` event
   * @param  {String} event.data.link          callback url AS-IS. `https://example.com/callback?state=...e&code=...&success=true`
   * @param  {Object} event.data.query         query parameters
   * @param  {Object} event.data.query.state   customer provided state
   * @param  {Object} event.data.query.code    auth code to be exchanged for an access/refresh token
   * @param  {Object} event.data.query.success indicates if the flow was finished successfully
   * @param  {Object} event.data.query.abort   indicates if the flow was aborted by the user
   * @param  {Object} event.data.query.flow_id unique flow identifier as provided on flow initiation
   *
   */
  function receiveMessage(event) {
    ...
  }
  • Flow Identification: The flow_id in the callback matches the id provided in the original WidgetLink creation response. It can be used alongside or instead of the state parameter for client-side flow tracking.
  • Authorization: The code parameter is only included in successful flows and can be exchanged for an access token.
  • Success Indicator: The success and abort flags let you understand if the flow was successfully finished.

Development Environment

The following domains are whitelisted for iframe integration during development:

  • http://127.0.0.1
  • https://127.0.0.1
  • http://localhost
  • https://localhost

All ports are allowed on the whitelisted domains.

📘

  1. The Widget operates in one-way communication mode and does not process incoming postMessages, even when using event.source.postMessage.
  2. iframe integration and URL callbacks are mutually exclusive:
    1. iframe integration uses the postMessage API
    2. Redirect integration uses URL callback endpoints

For detailed information about the postMessage API, refer to the MDN documentation.

Error handling

Overview

The Widget provides comprehensive error handling through callback responses for both redirect and iframe integrations. All responses include a success flag indicating the flow status.

Successful Flow

The postMessage event or callback of a successful flow includes an authorization code (code) and a positive status indicator (success=true).

{
  link: "<WidgetLink.redirect_uri>?state=<state>&code=<code>&success=true&abort=false&flow_id=<widget-link-id>",
  query: {
    code: "<code>",
    state: "<state>",
    success: true,
    abort: false,
    flow_id: "<widget-link-id>"
  }
}

<WidgetLink.redirect_uri>?state=<state>&code=<code>&success=true

In the case where an error has occurred, redirect_uri provided in Widget link will be called with a query parameter success=false.

General Errors

In the case where an error has occurred, it will be

  • indicated by the success=false flag
  • no authorization code is provided
  • the original state parameter is preserved
{
  link: "<WidgetLink.redirect_uri>?state=<state>&success=false&abort=false&flow_id=<widget-link-id>",
  query: {
    state: "<state>",
    success: false,
    abort: false,
    flow_id: "<widget-link-id>"
  }
}

<WidgetLink.redirect_uri>?state=<state>&success=false

User-Initiated Cancellation

Widget users can cancel the flow at any time and return to your application. If a user has canceled the process, it will be

  • indicated by the abort=true flag
  • considered an error state (success=false)
  • no authorization code is provided
  • response format matches general errors with the addition of the abort flag

Updated about 5 hours ago