npm package: @finmid/client
Description: Javascript client for finmid integration
Latest version: 0.4.1

Javascript client for finmid integration

## Installation

Our client is framework-agnostic, you can use it with React, Vue, Svelte, or any other core framework.
It is written in TypeScript, has zero dependencies, and we bundle our sources with API reference in package.

```
npm i @finmid/client
# or
yarn add @finmid/client
# or
pnpm i @finmid/client
```

<br/><br/>

## Functions

### mountOnboarding

▸ **mountOnboarding**(`options`): [`OnboardingFrame`](#onboardingframe)

Mounts an onboarding iframe.

An empty `div` element with absolute positioning and high z-index will be appended to body. This element will host the iframe.

This operation is idempotent — it will create only one host-div and iframe regardless of amount of times you call it.

**`Example`**

```ts
const platform = {
  name: 'ACME GmbH',
  websiteLogo: 'https://picsum.photos/120/32',
  supportEmail: 'acme.support@example.com',
  brandColors: [
    '#F5F3FF',
    '#EDEAFD',
    '#DCD7FD',
    '#C3B7FB',
    '#A58FF7',
    '#8864F2',
    '#7848E9',
    '#6938D5',
    '#582EB3',
    '#492792',
  ],
  faqPages: {
    en: 'https://finmid.zendesk.com/hc/en-150',
    'de-DE': 'https://finmid.zendesk.com/hc/de',
  },
};

mountOnboarding({
  environment: 'sandbox',
  mode: 'onboarding',

  platform,

  async refreshToken() {
    return await authenticate();
  },

  onStateChange(state) {
    switch (state) {
      case 'STARTED':
        log('onboarding started');
        sendComplimentEmail();
        break;
      case 'DONE':
        log('onboarding done');
        break;

      default:
        break;
    }
  },

  onFinish() {
    enableFinancePages();
  },
});
```

#### Parameters

| Name      | Type                                                | Description                                             |
| :-------- | :-------------------------------------------------- | :------------------------------------------------------ |
| `options` | [`MountOnboardingOptions`](#mountonboardingoptions) | Options with which onboarding iframe should be mounted. |

#### Returns

[`OnboardingFrame`](#onboardingframe)

Onboarding frame object to manage iframe state.

---

### showCardDetails

▸ **showCardDetails**(`options`): `void`

Renders card's details in given DOM elements.

Due to security concerns, each data element is rendered in an iframe.  
Elements can be partially styled.

Details:

- Card number, optionally formatted like `XXXX XXXX XXXX XXXX`
- Expiration date, formatted like `MM/YY`
- CVV - card's CVV number

**`Example`**

```ts
showCardDetails({
  token: 'some_valid_token',
  environment: 'sandbox',
  cardNumber: {
    domId: 'finmid-card-number',
    format: true,
    styles: {
      span: {
        'font-family': 'Consolas, monospace',
        'font-size': '24px',
        color: 'white',
      },
    },
  },
});
```

#### Parameters

| Name      | Type                                                |
| :-------- | :-------------------------------------------------- |
| `options` | [`ShowCardDetailsOptions`](#showcarddetailsoptions) |

#### Returns

`void`

---

### setCardPin

▸ **setCardPin**(`options`): `void`

Renders PIN set widget in given DOM element.

**`Example`**

```ts
setCardPin({
  environment: 'sandbox',
  token: 'some_valid_token',
  domId: 'card-set-pin-widget',
  locale: 'de-DE',
  onFinish() {
    showSuccessMessage();
  },
});
```

#### Parameters

| Name      | Type                                      | Description                                               |
| :-------- | :---------------------------------------- | :-------------------------------------------------------- |
| `options` | [`SetCardPinOptions`](#setcardpinoptions) | Options with which pin setting widget should be rendered. |

#### Returns

`void`

<br/><br/><br/>

## Types

### Environment

Ƭ **Environment**: `"production"` \| `"sandbox"`

API environment.

---

### Locale

Ƭ **Locale**: `"en-GB"` \| `"de-DE"`

Supported locales.

---

### MountOnboardingOptions

Ƭ **MountOnboardingOptions**: [`OnboardingMode`](#onboardingmode) \| [`FillUboDataMode`](#fillubodatamode)

Onboarding can be opened in two different modes,

- either to fill data about company by legal representative (`onboarding` mode),
- or to fill data for an invited anonymous company beneficiar (`fill-ubo-data` mode)

---

### OnboardingMode

Ƭ **OnboardingMode**: `Object`

`onboarding` mode helps legal representatives to fill data about company.

This mode is supposed to be executed in authorized context, where platform knows which user fills data.

#### Type declaration

| Name             | Type                                                       | Description                                                                                                                               |
| :--------------- | :--------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `environment`    | [`Environment`](#environment)                              | -                                                                                                                                         |
| `mode`           | `"onboarding"`                                             | `onboarding` mode starts up the regular onboarding.                                                                                       |
| `refreshToken`   | () => `Promise`\<`string`\>                                | A function to get a new authorization token  provided by [User - Create onboarding widget token API](https://docs.finmid.com/reference/create-onboarding-token).                                                                                              |
| `platform`       | [`PlatformData`](#platformdata)                            | Platform's data for white-labelling.                                                                                                      |
| `onExit?`        | () => `void`                                               | Action to execute when user leaves the onboarding.                                                                                        |
| `onFinish?`      | () => `void`                                               | Action to execute when user finishes the onboarding.<br/><br/> This can trigger only once.                                                |
| `onStateChange?` | (`state`: [`OnboardingState`](#onboardingstate)) => `void` | A callback for state-change event.                                                                                                        |

---

### FillUboDataMode

Ƭ **FillUboDataMode**: `Object`

`fill-ubo-data` helps invited company beneficiars to fill personal data.

This mode is supposed to work in an anonymous context. URL where this mode is hosted should be publically accessible and expected to have following structure:

`<https://{platform.host}/{path}?token={ubo_token}`>

where `ubo_token` from query parameters should be passed to the `token`  
property of this object.

#### Type declaration

| Name          | Type                            | Description                                                        |
| :------------ | :------------------------------ | :----------------------------------------------------------------- |
| `environment` | [`Environment`](#environment)   | -                                                                  |
| `mode`        | `"fill-ubo-data"`               | `fill-ubo-data` starts limited onboarding for specific beneficiar. |
| `token`       | `string`                        | An autorization token provided by URL's `token` query parameter.   |
| `platform`    | [`PlatformData`](#platformdata) | Platform's data for white-labelling.                               |
| `onExit?`     | () => `void`                    | Action to execute when invited UBO leaves the onboarding.          |

---

### OnboardingState

Ƭ **OnboardingState**: `"NOT_STARTED"` \| `"STARTED"` \| `"DONE"`

- `NOT_STARTED` — onboarding is not yet started
- `STARTED` — at least company info has been filled
- `DONE` — onboarding is complete

---

### PlatformData

Ƭ **PlatformData**: `Object`

This object contains information about white-labelling for onboarding flow.

Our support will provide you reasonable defaults for your platform.

#### Type declaration

| Name           | Type                          | Description                                                                                                        |
| :------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `websiteLogo`  | `string`                      | Platform's logo. Will be shown in top left corner.<br/><br/> Recommended resolution: width `120px`, height `32px`. |
| `name`         | `string`                      | Platform's name. Will be shown in top left corner if `websiteLogo` coundn't be displayed.                          |
| `brandColors`  | [`BrandColors`](#brandcolors) | Main colors and accent tints.                                                                                      |
| `supportEmail` | `string`                      | Email for contacting support.                                                                                      |
| `faqPages?`    | [`FaqPages`](#faqpages)       | FAQ pages URLs per locale. <br/> Default fallback locale is `en`.                                                  |

---

### BrandColors

Ƭ **BrandColors**: [`string`, `string`, `string`, `string`, `string`, `string`, `string`, `string`, `string`, `string`]

Ten html colors representing following tints:  
`50`, `100`, `200`, `300`, `400`, `500`, `600`, `700` (main color), `800`, `900`.

**`Example`**

```ts
[
  '#F5F3FF',
  '#EDEAFD',
  '#DCD7FD',
  '#C3B7FB',
  '#A58FF7',
  '#8864F2',
  '#7848E9',
  '#6938D5',
  '#582EB3',
  '#492792',
];
```

---

### FaqPages

Ƭ **FaqPages**: `Object`

FAQ pages URLs per locale.

**`See`**

[Locale](#locale)

#### Type declaration

| Name     | Type     |
| :------- | :------- |
| `en-GB?` | `string` |
| `de-DE?` | `string` |

---

### OnboardingFrame

Ƭ **OnboardingFrame**: `Object`

#### Type declaration

| Name      | Type         | Description                                                                                                    |
| :-------- | :----------- | :------------------------------------------------------------------------------------------------------------- |
| `open`    | () => `void` | Makes onboarding iframe visible by switching `display` CSS property of it's host element.                      |
| `unmount` | () => `void` | Removes the onboarding iframe.<br/><br/> This is called automatically when onboarding changes state to `DONE`. |

---

### ShowCardDetailsOptions

Ƭ **ShowCardDetailsOptions**: `Object`

#### Type declaration

| Name              | Type                                                        | Description                                                                                                                                      |
| :---------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`           | `string`                                                    | A one-time access token generated by [Card - Create card details token API](https://docs.finmid.com/reference/create-view-details-token).        |
| `environment`     | [`Environment`](#environment)                               | -                                                                                                                                                |
| `cardNumber?`     | [`CardNumberSettings`](#cardnumbersettings)                 | Card number element settings.                                                                                                                    |
| `expirationDate?` | [`CardExpirationDateSettings`](#cardexpirationdatesettings) | Card’s expiration date element settings.                                                                                                         |
| `cvv?`            | [`CardCvvSettings`](#cardcvvsettings)                       | Card’s CVV number element settings.                                                                                                              |
| `onSuccess?`      | () => `void`                                                | Executed upon success of iframe rendering.<br/><br/> You can customize the method within this event handler to perform whatever action you want. |
| `onFailure?`      | (`error`: `Error`) => `void`                                | Executed upon failure of iframe rendering.<br/><br/> You can customize the method within this event handler to perform whatever action you want. |

---

### CardNumberSettings

Ƭ **CardNumberSettings**: `Object`

#### Type declaration

| Name          | Type                                      | Description                                                                                                                                                                                          |
| :------------ | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `domId`       | `string`                                  | Id of an element in DOM where an iframe will be rendered.                                                                                                                                            |
| `format?`     | `boolean`                                 | Format card number as `XXXX XXXX XXXX XXXX`.<br/><br/> If set to `false`, format is `XXXXXXXXXXXXXXXX`, which is useful in cases when you want to allow copy to buffer.<br/><br/> **`Default`** true |
| `styles?`     | [`CardNumberStyles`](#cardnumberstyles)   | A CSS-like style object applied to the iframe holding the card data.                                                                                                                                 |
| `copyButton?` | [`CopyDetailsButton`](#copydetailsbutton) | An optional transparent button used to copy the card’s number to the clipboard.                                                                                                                      |

---

### CardExpirationDateSettings

Ƭ **CardExpirationDateSettings**: `Object`

#### Type declaration

| Name          | Type                                                    | Description                                                                              |
| :------------ | :------------------------------------------------------ | :--------------------------------------------------------------------------------------- |
| `domId`       | `string`                                                | Id of an element in DOM where an iframe will be rendered.                                |
| `styles?`     | [`CardExpirationDateStyles`](#cardexpirationdatestyles) | A CSS-like style object applied to the iframe holding the card data.                     |
| `copyButton?` | [`CopyDetailsButton`](#copydetailsbutton)               | An optional transparent button used to copy the card’s expiration date to the clipboard. |

---

### CardCvvSettings

Ƭ **CardCvvSettings**: `Object`

#### Type declaration

| Name          | Type                                      | Description                                                                         |
| :------------ | :---------------------------------------- | :---------------------------------------------------------------------------------- |
| `domId`       | `string`                                  | Id of an element in DOM where an iframe will be rendered.                           |
| `styles?`     | [`CardCvvStyles`](#cardcvvstyles)         | A CSS-like style object applied to the iframe holding the card data.                |
| `copyButton?` | [`CopyDetailsButton`](#copydetailsbutton) | An optional transparent button used to copy the card’s CVV number to the clipboard. |

---

### CopyDetailsButton

Ƭ **CopyDetailsButton**: `Object`

#### Type declaration

| Name             | Type                         | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| :--------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `domId`          | `string`                     | Id of an element in DOM where a transparent iframe will be rendered.<br/><br/> You can customize the look-and-feel of the Copy to Clipboard button within the parent div. Transparent iframe will intercept click events.<br/><br/> The parent div element must have its CSS position set to relative, for example `style="position: relative;"` to ensure it remains tightly aligned with its iframe. |
| `onCopySuccess?` | () => `void`                 | Called when the element’s text is successfully copied to the clipboard. You can use this callback to update your user interface in response to a click.                                                                                                                                                                                                                                                |
| `onCopyFailure?` | (`error`: `Error`) => `void` | Called when there is an error attempting to copy the element’s text to the clipboard.                                                                                                                                                                                                                                                                                                                  |

---

### CardNumberStyles

Ƭ **CardNumberStyles**: `Object`

#### Type declaration

| Name          | Type                                        |
| :------------ | :------------------------------------------ |
| `span?`       | [`ExtendedFontStyles`](#extendedfontstyles) |
| `span:hover?` | [`ExtendedFontStyles`](#extendedfontstyles) |

---

### CardExpirationDateStyles

Ƭ **CardExpirationDateStyles**: `Object`

#### Type declaration

| Name          | Type                                        |
| :------------ | :------------------------------------------ |
| `span?`       | [`ExtendedFontStyles`](#extendedfontstyles) |
| `span:hover?` | [`ExtendedFontStyles`](#extendedfontstyles) |

---

### CardCvvStyles

Ƭ **CardCvvStyles**: `Object`

#### Type declaration

| Name          | Type                        |
| :------------ | :-------------------------- |
| `span?`       | [`FontStyles`](#fontstyles) |
| `span:hover?` | [`FontStyles`](#fontstyles) |

---

### ExtendedFontStyles

Ƭ **ExtendedFontStyles**: `Object`

#### Type declaration

| Name              | Type     |
| :---------------- | :------- |
| `color?`          | `string` |
| `font-family?`    | `string` |
| `font-size?`      | `string` |
| `background?`     | `string` |
| `font-weight?`    | `string` |
| `letter-spacing?` | `string` |

---

### FontStyles

Ƭ **FontStyles**: `Object`

#### Type declaration

| Name           | Type     |
| :------------- | :------- |
| `color?`       | `string` |
| `font-family?` | `string` |
| `font-size?`   | `string` |
| `background?`  | `string` |

---

### SetCardPinOptions

Ƭ **SetCardPinOptions**: `Object`

#### Type declaration

| Name          | Type                          | Description                                                                                                                                                                                                                  |
| :------------ | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment` | [`Environment`](#environment) | -                                                                                                                                                                                                                            |
| `domId`       | `string`                      | Id of an element in DOM where an iframe will be rendered.<br/><br/> Recommended dimensions: width - at least 300px, height - 400px.                                                                                          |
| `token`       | `string`                      | A one-time token generated by [Card - Create card PIN token API](https://docs.finmid.com/reference/create-set-pin-token).                                                                                                    |
| `onFinish`    | () => `void`                  | Executed upon successfully setting the PIN.<br/><br/> The iframe will be removed immideately after this callback call.<br/><br/> You can customize the method within this event handler to perform whatever action you want. |
| `locale`      | [`Locale`](#locale)           | Locale that should be used for widget.                                                                                                                                                                                       |