npm package: @finapi/finapi-js-loader
Description: finAPI JS Loader
Author: support@finapi.io
Latest version: 0.50.0

# finAPI JS Loader for Web Components

The loader's primary responsibility is to fetch bundled finAPI Web Components (or: Widgets) and
inject them into the host document. The loader is available as an NPM package or
an UMD module, which can be imported into host pages.

## Widget Authentication

Widgets require a [process](interfaces/CreditCheckAccountProperties.html#processToken) (-token), or
a [mandator ID](interfaces/CreditCheckAccountProperties.html#mandatorId)
that allows the widget to create a process by himself.

Please refer to
the [DI Solutions Public Documentation](https://documentation.finapi.io/dippd/obtain-authorization-via-process-controller)
to understand
the authorization process with
finAPIs [Process Controller API](https://docs.finapi.io/?product=processctl#post-/processes) and its prerequisites.

### Prerequisites

To test the finAPI widgets, please request a test mandator via our [homepage](https://www.finapi.io/jetzt-testen/) to
obtain client credentials. Same applies for
if you decided to [order](https://www.finapi.io/jetzt-bestellen/) our product(s).

### Creating a Process with your own Backend Service

With your mandator's client ID and secret, your backend service can create a process via the finAPI Process Controller
[POST /processes](https://docs.finapi.io/?product=processctl#post-/processes) API.

### Creating a Process from your Frontend (-Application)

With your mandator ID, your frontend can create a process via the finAPI Process Controller
via [POST /processes/{mandatorId}/link](https://docs.finapi.io/?product=processctl#post-/processes/-mandatorId-/link).

Another option is to start your application using a redirect with the API
endpoint [GET /processes/{mandatorId}/link](https://docs.finapi.io/?product=processctl#get-/processes/-mandatorId-/link),
redirecting to your website, passing the `processToken` as a query parameter of the URL.

> Note: it is mandatory for this approach to have your mandator configured in the finAPI Process Controller. Please
> contact <support@finapi.io> to have it set up for you.

## Sandbox and Live Environments

If you are developing your application against our sandbox environment, please change/add the following URLs to our examples.

### JS Loader Script (UMD only)

|     | Sandbox                                            | Live                                            |
| --- | -------------------------------------------------- | ----------------------------------------------- |
| URL | https://js-loader-finapi-general-sandbox.finapi.io | https://js-loader-finapi-general-live.finapi.io |

### Widget Class Constructor Parameters

|        | Sandbox                                                 | Live (default)                                       |
| ------ | ------------------------------------------------------- | ---------------------------------------------------- |
| target | https://widget-library-finapi-general-sandbox.finapi.io | https://widget-library-finapi-general-live.finapi.io |

### Widget Properties

| property                  | Sandbox                                                      | Live (default)                                            |
|---------------------------|--------------------------------------------------------------|-----------------------------------------------------------|
| processctlServer          | https://di-processctl-finapi-general-sandbox.finapi.io       | https://di-processctl-finapi-general-live.finapi.io       |
| processctlSolutionsServer | https://di-processctl-finapi-general-sandbox.finapi.io       | https://di-processctl-finapi-general-live.finapi.io       |
| jsStaticResourcesServer   | https://js-static-resources-finapi-general-sandbox.finapi.io | https://js-static-resources-finapi-general-live.finapi.io |

## Loading a Widget using the Universal Module Definition in plain HTML page

### GiroIdent Basis

```html
<html>
  <head>
    <script src="https://js-loader-finapi-general-live.finapi.io/finapi-js-loader.umd.production.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const container = document.getElementById('container');
        const loader = window['@finapi/finapi-js-loader'];
        const widget = new loader.GiroIdentBasis(container);
        const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
        const widgetProperties = {
          processToken,
          // personal details for the user to be identified
          firstName: 'USER_FIRST_NAME',
          lastName: 'USER_LAST_NAME',
        };
        const widgetCallbacks = {}; // optionally register your own functions to be called
        widget.load(widgetProperties, widgetCallbacks);
      });
    </script>
  </body>
</html>
```

> Note: Refer to [GiroIdentProperties](interfaces/GiroIdentProperties.html)
> and [GiroIdentCallbacks](interfaces/GiroIdentCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### KontoCheck (KreditCheck B2C Account)

```html
<html>
  <head>
    <script src="https://js-loader-finapi-general-live.finapi.io/finapi-js-loader.umd.production.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const container = document.getElementById('container');
        const loader = window['@finapi/finapi-js-loader'];
        const widget = new loader.CreditcheckAccount(container);
        const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
        const widgetProperties = {processToken};
        const widgetCallbacks = {}; // optionally register your own functions to be called
        widget.load(widgetProperties, widgetCallbacks);
      });
    </script>
  </body>
</html>
```

> Note: Refer to [CreditCheckAccountProperties](interfaces/CreditCheckAccountProperties.html)
> and [CreditCheckAccountCallbacks](types/CreditCheckAccountCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### KreditCheck (KreditCheck B2C Loan)

```html
<html>
  <head>
    <script src="https://js-loader-finapi-general-live.finapi.io/finapi-js-loader.umd.production.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const container = document.getElementById('container');
        const loader = window['@finapi/finapi-js-loader'];
        const widget = new loader.CreditCheckLoan(container);
        const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
        const widgetProperties = {processToken};
        const widgetCallbacks = {}; // optionally register your own functions to be called
        widget.load(widgetProperties, widgetCallbacks);
      });
    </script>
  </body>
</html>
```

> Note: Refer to [CreditCheckLoanProperties](interfaces/CreditCheckLoanProperties.html)
> and [CreditCheckLoanCallbacks](types/CreditCheckLoanCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### KreditCheck B2B

```html
<html>
  <head>
    <script src="https://js-loader-finapi-general-live.finapi.io/finapi-js-loader.umd.production.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const container = document.getElementById('container');
        const loader = window['@finapi/finapi-js-loader'];
        const widget = new loader.CreditCheckB2B(container);
        const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
        const widgetProperties = {processToken};
        const widgetCallbacks = {}; // optionally register your own functions to be called
        widget.load(widgetProperties, widgetCallbacks);
      });
    </script>
  </body>
</html>
```

### Digital Account Check (B2C)

```html
<html>
  <head>
    <script src="https://js-loader-finapi-general-live.finapi.io/finapi-js-loader.umd.production.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const container = document.getElementById('container');
        const loader = window['@finapi/finapi-js-loader'];
        const widget = new loader.DigitalAccountCheck(container);
        const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
        const widgetProperties = {processToken};
        const widgetCallbacks = {}; // optionally register your own functions to be called
        widget.load(widgetProperties, widgetCallbacks);
      });
    </script>
  </body>
</html>
```

### Digital Account Check (B2B)

```html
<html>
  <head>
    <script src="https://js-loader-finapi-general-live.finapi.io/finapi-js-loader.umd.production.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const container = document.getElementById('container');
        const loader = window['@finapi/finapi-js-loader'];
        const widget = new loader.DigitalAccountCheck(container);
        const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
        const widgetProperties = {processToken};
        const widgetCallbacks = {}; // optionally register your own functions to be called
        widget.load(widgetProperties, widgetCallbacks);
      });
    </script>
  </body>
</html>
```

> Note: Refer to [CreditCheckB2BProperties](interfaces/CreditCheckB2BProperties.html)
> and [CreditCheckB2BCallbacks](types/CreditCheckB2BCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

## Loading a Widget using NPM package in a React Application

### Loader Installation

```
npm install @finapi/finapi-js-loader
```

### GiroIdent Basis

```tsx
import { GiroIdentBasis } from '@finapi/finapi-js-loader';
import React from 'react';

function AppGi() {
  const containerRef = (container: HTMLDivElement) => {
    if (container) {
      const widget = new GiroIdentBasis(container);
      const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
      const widgetProperties = {
        processToken,
        // personal details for the user to be identified
        firstName: 'USER_FIRST_NAME',
        lastName: 'USER_LAST_NAME',
      };
      const widgetCallbacks = {}; // optionally register your own functions to be called
      widget.load(widgetProperties, widgetCallbacks);
    }
  };
  return <div className="AppGi" ref={containerRef}></div>;
}

export default AppGi;
```

> Note: Refer to [GiroIdentProperties](interfaces/GiroIdentProperties.html)
> and [GiroIdentCallbacks](interfaces/GiroIdentCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### KontoCheck (KreditCheck B2C Account) Integration

```tsx
import { CreditCheckAccount } from '@finapi/finapi-js-loader';
import React from 'react';

function AppKcAcc() {
  const containerRef = (container: HTMLDivElement) => {
    if (container) {
      const widget = new CreditCheckAccount(container);
      const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
      const widgetProperties = { processToken };
      const widgetCallbacks = {}; // optionally register your own functions to be called
      widget.load(widgetProperties, widgetCallbacks);
    }
  };
  return <div className="AppKcAcc" ref={containerRef}></div>;
}

export default AppKcAcc;
```

> Note: Refer to [CreditCheckAccountProperties](interfaces/CreditCheckAccountProperties.html)
> and [CreditCheckAccountCallbacks](types/CreditCheckAccountCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### KreditCheck (KreditCheck B2C Loan) Integration

```tsx
import { CreditCheckLoan } from '@finapi/finapi-js-loader';
import React from 'react';

function AppKcL() {
  const containerRef = (container: HTMLDivElement) => {
    if (container) {
      const widget = new CreditCheckLoan(container);
      const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
      const widgetProperties = { processToken };
      const widgetCallbacks = {}; // optionally register your own functions to be called
      widget.load(widgetProperties, widgetCallbacks);
    }
  };
  return <div className="AppKcL" ref={containerRef}></div>;
}

export default AppKcL;
```

> Note: Refer to [CreditCheckLoanProperties](interfaces/CreditCheckLoanProperties.html)
> and [CreditCheckLoanCallbacks](types/CreditCheckLoanCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### KreditCheck B2B Integration

```tsx
import { CreditCheckB2B } from '@finapi/finapi-js-loader';
import React from 'react';

function AppKcB2b() {
  const containerRef = (container: HTMLDivElement) => {
    if (container) {
      const widget = new CreditCheckB2B(container);
      const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
      const widgetProperties = { processToken };
      const widgetCallbacks = {}; // optionally register your own functions to be called
      widget.load(widgetProperties, widgetCallbacks);
    }
  };
  return <div className="AppKcB2b" ref={containerRef}></div>;
}

export default AppKcB2b;
```

> Note: Refer to [CreditCheckB2BProperties](interfaces/CreditCheckB2BProperties.html)
> and [CreditCheckB2BCallbacks](types/CreditCheckB2BCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### Digital Account Check (B2C)

```tsx
import { DigitalAccountCheck } from '@finapi/finapi-js-loader';
import React from 'react';

function AppKcDacB2c() {
  const containerRef = (container: HTMLDivElement) => {
    if (container) {
      const widget = new DigitalAccountCheck(container);
      const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
      const widgetProperties = { processToken };
      const widgetCallbacks = {}; // optionally register your own functions to be called
      widget.load(widgetProperties, widgetCallbacks);
    }
  };
  return <div className="AppKcDacB2c" ref={containerRef}></div>;
}

export default AppKcDacB2c;
```

> Note: Refer to [DigitalAccountCheckProperties](interfaces/DigitalAccountCheckProperties.html)
> and [DigitalAccountCheckCallbacks](types/DigitalAccountCheckCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.

### Digital Account Check (B2B)

```tsx
import { DigitalAccountCheck } from '@finapi/finapi-js-loader';
import React from 'react';

function AppKcDacB2b() {
  const containerRef = (container: HTMLDivElement) => {
    if (container) {
      const widget = new DigitalAccountCheck(container);
      const processToken = 'PROCESS_TOKEN'; // process token, pass it to your application
      const widgetProperties = { processToken };
      const widgetCallbacks = {}; // optionally register your own functions to be called
      widget.load(widgetProperties, widgetCallbacks);
    }
  };
  return <div className="AppKcDacB2b" ref={containerRef}></div>;
}

export default AppKcDacB2b;
```

> Note: Refer to [DigitalAccountCheckProperties](interfaces/DigitalAccountCheckProperties.html)
> and [DigitalAccountCheckCallbacks](types/DigitalAccountCheckCallbacks.html)
> to understand the available `widgetProperties` and `widgetCallbacks` definition.