0.4.1 • Published 3 years ago

@finmid/client v0.4.1

Weekly downloads
-
License
-
Repository
-
Last release
3 years ago

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: '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

NameTypeDescription
optionsMountOnboardingOptionsOptions 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

NameType
optionsShowCardDetailsOptions

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

NameTypeDescription
optionsSetCardPinOptionsOptions 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

NameTypeDescription
environmentEnvironment-
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.
platformPlatformDataPlatform's data for white-labelling.
onExit?() => voidAction to execute when user leaves the onboarding.
onFinish?() => voidAction to execute when user finishes the onboarding. This can trigger only once.
onStateChange?(state: OnboardingState) => voidA 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

NameTypeDescription
environmentEnvironment-
mode"fill-ubo-data"fill-ubo-data starts limited onboarding for specific beneficiar.
tokenstringAn autorization token provided by URL's token query parameter.
platformPlatformDataPlatform's data for white-labelling.
onExit?() => voidAction 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

NameTypeDescription
websiteLogostringPlatform's logo. Will be shown in top left corner. Recommended resolution: width 120px, height 32px.
namestringPlatform's name. Will be shown in top left corner if websiteLogo coundn't be displayed.
brandColorsBrandColorsMain colors and accent tints.
supportEmailstringEmail for contacting support.
faqPages?FaqPagesFAQ 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

NameType
en-GB?string
de-DE?string

OnboardingFrame

Ƭ OnboardingFrame: Object

Type declaration

NameTypeDescription
open() => voidMakes onboarding iframe visible by switching display CSS property of it's host element.
unmount() => voidRemoves the onboarding iframe. This is called automatically when onboarding changes state to DONE.

ShowCardDetailsOptions

Ƭ ShowCardDetailsOptions: Object

Type declaration

NameTypeDescription
tokenstringA one-time access token generated by Card - Create card details token API.
environmentEnvironment-
cardNumber?CardNumberSettingsCard number element settings.
expirationDate?CardExpirationDateSettingsCard’s expiration date element settings.
cvv?CardCvvSettingsCard’s CVV number element settings.
onSuccess?() => voidExecuted upon success of iframe rendering. You can customize the method within this event handler to perform whatever action you want.
onFailure?(error: Error) => voidExecuted 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

NameTypeDescription
domIdstringId of an element in DOM where an iframe will be rendered.
format?booleanFormat 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?CardNumberStylesA CSS-like style object applied to the iframe holding the card data.
copyButton?CopyDetailsButtonAn optional transparent button used to copy the card’s number to the clipboard.

CardExpirationDateSettings

Ƭ CardExpirationDateSettings: Object

Type declaration

NameTypeDescription
domIdstringId of an element in DOM where an iframe will be rendered.
styles?CardExpirationDateStylesA CSS-like style object applied to the iframe holding the card data.
copyButton?CopyDetailsButtonAn optional transparent button used to copy the card’s expiration date to the clipboard.

CardCvvSettings

Ƭ CardCvvSettings: Object

Type declaration

NameTypeDescription
domIdstringId of an element in DOM where an iframe will be rendered.
styles?CardCvvStylesA CSS-like style object applied to the iframe holding the card data.
copyButton?CopyDetailsButtonAn optional transparent button used to copy the card’s CVV number to the clipboard.

CopyDetailsButton

Ƭ CopyDetailsButton: Object

Type declaration

NameTypeDescription
domIdstringId 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?() => voidCalled 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) => voidCalled when there is an error attempting to copy the element’s text to the clipboard.

CardNumberStyles

Ƭ CardNumberStyles: Object

Type declaration

NameType
span?ExtendedFontStyles
span:hover?ExtendedFontStyles

CardExpirationDateStyles

Ƭ CardExpirationDateStyles: Object

Type declaration

NameType
span?ExtendedFontStyles
span:hover?ExtendedFontStyles

CardCvvStyles

Ƭ CardCvvStyles: Object

Type declaration

NameType
span?FontStyles
span:hover?FontStyles

ExtendedFontStyles

Ƭ ExtendedFontStyles: Object

Type declaration

NameType
color?string
font-family?string
font-size?string
background?string
font-weight?string
letter-spacing?string

FontStyles

Ƭ FontStyles: Object

Type declaration

NameType
color?string
font-family?string
font-size?string
background?string

SetCardPinOptions

Ƭ SetCardPinOptions: Object

Type declaration

NameTypeDescription
environmentEnvironment-
domIdstringId of an element in DOM where an iframe will be rendered. Recommended dimensions: width - at least 300px, height - 400px.
tokenstringA one-time token generated by Card - Create card PIN token API.
onFinish() => voidExecuted 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.
localeLocaleLocale that should be used for widget.
0.4.1

3 years ago

0.4.0

3 years ago

0.3.2

3 years ago

0.3.1

3 years ago

0.3.0

3 years ago