@finapi/finapi-js-loader
Version:
finAPI JS Loader
402 lines (330 loc) • 15.7 kB
Markdown
# 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.