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

Functions

mountOnboarding

▸ mountOnboarding(options): 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

const platform = {
  name: 'ACME GmbH',
  websiteLogo: 'https://picsum.photos/120/32',
  supportEmail: '[email protected]',
  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 | Options with which onboarding iframe should be mounted. |

Returns

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

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 |

Returns

void

setCardPin

▸ setCardPin(options): void

Renders PIN set widget in given DOM element.

Example

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

Parameters

| Name | Type | Description | | :-------- | :---------------------------------------- | :-------------------------------------------------------- | | options | SetCardPinOptions | Options with which pin setting widget should be rendered. |

Returns

void

Types

Environment

Ƭ Environment: "production" | "sandbox"

API environment.

Locale

Ƭ Locale: "en-GB" | "de-DE"

Supported locales.

MountOnboardingOptions

Ƭ MountOnboardingOptions: OnboardingMode | 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 | - | | 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. | | platform | 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. This can trigger only once. | | onStateChange? | (state: 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 | - | | 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 | 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. 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 | Main colors and accent tints. | | supportEmail | string | Email for contacting support. | | faqPages? | FaqPages | FAQ pages URLs per locale. 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

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

FaqPages

Ƭ FaqPages: Object

FAQ pages URLs per locale.

See

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. 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. | | environment | Environment | - | | cardNumber? | CardNumberSettings | Card number element settings. | | expirationDate? | CardExpirationDateSettings | Card’s expiration date element settings. | | cvv? | CardCvvSettings | Card’s CVV number element settings. | | onSuccess? | () => void | Executed upon success of iframe rendering. 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. 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. If set to false, format is XXXXXXXXXXXXXXXX, which is useful in cases when you want to allow copy to buffer. Default true | | styles? | CardNumberStyles | A CSS-like style object applied to the iframe holding the card data. | | copyButton? | 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 | A CSS-like style object applied to the iframe holding the card data. | | copyButton? | 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 | A CSS-like style object applied to the iframe holding the card data. | | copyButton? | 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. You can customize the look-and-feel of the Copy to Clipboard button within the parent div. Transparent iframe will intercept click events. 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 | | span:hover? | ExtendedFontStyles |

CardExpirationDateStyles

Ƭ CardExpirationDateStyles: Object

Type declaration

| Name | Type | | :------------ | :------------------------------------------ | | span? | ExtendedFontStyles | | span:hover? | ExtendedFontStyles |

CardCvvStyles

Ƭ CardCvvStyles: Object

Type declaration

| Name | Type | | :------------ | :-------------------------- | | span? | FontStyles | | span:hover? | 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 | - | | domId | string | Id of an element in DOM where an iframe will be rendered. Recommended dimensions: width - at least 300px, height - 400px. | | token | string | A one-time token generated by Card - Create card PIN token API. | | onFinish | () => void | Executed upon successfully setting the PIN. The iframe will be removed immideately after this callback call. You can customize the method within this event handler to perform whatever action you want. | | locale | Locale | Locale that should be used for widget. |